com.webobjects.appserver
Class WOComponent

java.lang.Object
  com.webobjects.appserver.WOElement
      com.webobjects.appserver.WOComponent

All Implemented Interfaces:

WOActionResults, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions, NSValidation, Serializable, Cloneable

Direct Known Subclasses:

BASSidePageWrapper, D2WCollapsibleComponentContent, D2WComponent, D2WDefaultCustomComponent, D2WEmbeddedComponent, D2WEmptyWrapper, D2WGenerationWrapper, D2WSwitchComponent, DarwinShadow, DefaultHeader, JSComponent, JSValidatedField, NEUHeader, WOAnyField, WOBatchNavigationBar, WOCheckboxMatrix, WOCollapsibleComponentContent, WOCompletionBar, WODictionaryRepetition, WOEventPage, WOEventRow, WOExceptionPage, WOIFrame, WOJavaClientApplet, WOJavaClientComponent, WOJavaClientJNLP, WOKeyValueConditional, WOLongResponsePage, WOMetaRefresh, WOOperation, WOOperationWSDLTemplate, WOPageRestorationError, WORadioButtonMatrix, WORedirect, WOSessionCreationError, WOSessionRestorationError, WOSimpleArrayDisplay, WOSortOrder, WOSortOrderManyKey, WOStatsPage, WOTable, WOTableString, WOTabPanel, WOThresholdColoredNumber, WOToManyRelationship, WOToOneRelationship, WXAccessControl, WXBar, WXOutlineControl, WXOutlineEntry, WXOutlineRepetition, WXSortOrder

public class WOComponent
extends WOElement
implements NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions, NSValidation, WOActionResults, Cloneable, Serializable

WOComponent objects dynamically render web pages (or sections of pages) at runtime. They provide custom navigation and other logic for the page, provide a framework for organizing constituent objects (static and dynamic HTML elements and subcomponents), and enable the attribute bindings of dynamic elements.

The WOComponent class has many methods that have the same names as methods of the WOApplication class. However, the scope of the WOComponent methods is limited to a component rather than being application-wide. For example, you can control component-definition caching on a per-component basis using setCachingEnabled, which has a WOApplication counterpart. When this kind of caching is enabled for a component, the application parses the contents of the component directory the first time the component is requested, creates the component definition, stores this object in memory, and restores it for subsequent requests.

WOComponent objects also respond to awake(), sleep() and the three request-handling methods: takeValuesFromRequest, invokeAction and appendToResponse. You can override these methods in your compiled subclasses, and thereby integrate your custom behavior into the request-response loop.

SubComponents

A WOComponent object can represent a dynamic fragment of a Web page as well as an entire page. Such subcomponents, or reusable components, are nested within a parent component representing the page or another subcomponent. Each component keeps track of its parent and subcomponents when a component receives a request-handling message, such as takeValuesFromRequest, it forwards that message to its subcomponents.

The WOComponent class also provides a child-parent callback mechanism to allow a child component to communicate with its parent. In the parent's declaration file, bind an arbitrary attribute of the child to an action method of the parent. Then, as the last step in the child's action method, invoke performParentAction with the argument being the arbitrary attribute, returning the object received back as the response page.

Stateless Components

For extra efficiency, you can create stateless components: components that can be shared between sessions. Stateless components aren't replicated each time they're needed; rather, a single shared instance is referenced each time the component is used.

Stateless components cannot have state. They can have instance variables, but the variable's content must be transient. To ensure that when the shared instance of a component is reused by another session there are no side effects, reset your component's instance variables by implementing the reset method. In your implementation of reset , set to null each instance variable. Note that a stateless component's instance variables will remain valid for the duration of the phase (takeValuesFromRequest , invokeAction , appendToResponse ); this lets you use instance variables in the stateless components to hold things analogous to items in a WORepetition.

Stateless components primarily save memory, but they can significantly speed up the application as well depending on how many stateless components you use in the application. To make a component stateless, override the component's isStateless method so that it returns true.

If a stateless component is needed simultaneously in separate threads, additional instances of the component are created (and later discarded) as necessary to prevent conflicts. Thus, the number of threads in which a component could be used determines the maximum number of instances of a stateless component that may be allocated at any given time.

See Also:

WOComponent.setCachingEnabled(boolean), WOComponent.awake(), WOComponent.sleep(), WOComponent.takeValuesFromRequest(WORequest, WOContext), WOComponent.invokeAction(WORequest, WOContext), WOComponent.appendToResponse(WOResponse aResponse, WOContext aContext), WOComponent.performParentAction(String anActionName), WOComponent.reset(), WOComponent.isStateless(), Serialized Form

Nested Class Summary

static class

WOComponent.Event The WOComponent.Event class is used to time various operations at the component level.

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSValidation

NSValidation.DefaultImplementation, NSValidation.Utility, NSValidation.ValidationException

Field Summary

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

WOComponent()
Deprecated. use WOComponent(WOContext aContext) instead. Using this constructor will slow down your application considerably.

WOComponent(WOContext aContext)
WebObjects Builder archive files exist in the component directory, and this constructor initializes component variables from this archive.

Method Summary

void	appendToResponse(WOResponse aResponse, WOContext aContext) Forces the component to generate its interface and output it in the response's content.
WOApplication	application() Returns the WOApplication object for the current application.
void	awake() Invoked at the beginning of a WOComponent's involvement in a cycle of the request-response loop.
String	baseURL() Returns the component URL relative to the server's document root.
NSArray	bindingKeys() Returns an NSArray containing the binding keys (as String objects) for each of the WOComponent's associations.
static boolean	canAccessFieldsDirectly() WOComponent's implementation of this static method returns true.
boolean	canGetValueForBinding(String aBindingName) Verifies that the binding exists and that valueForBinding will return a value.
boolean	canSetValueForBinding(String aBindingName) Verifies that the binding exists and that setValueForBinding will succeed.
Object	clone() Conformance to Cloneable.
WOContext	context() Returns the WOContext object for the current transaction (request-response loop)
static void	debugString(String string) Deprecated. debugString is no longer supported
String	descriptionForResponse(WOResponse aResponse, WOContext aContext) Records information about the component, if it is the top-level component.
void	ensureAwakeInContext(WOContext aContext) Ensures that the receiver is awake in the specified context.
String	frameworkName() If the component is stored in a framework, this method returns the name of that framework.
WOResponse	generateResponse() Conformance to WOActionResults.
Object	handleQueryWithUnboundKey(String key) Conformance to NSKeyValueCoding.ErrorHandling.
void	handleTakeValueForUnboundKey(Object value, String key) Conformance to NSKeyValueCoding.ErrorHandling.
boolean	hasBinding(String aBindingName) Returns whether the component has a binding named aBindingName.
boolean	hasSession() Returns whether the component is already in a session.
WOActionResults	invokeAction(WORequest aRequest, WOContext aContext) Tells the component to execute any action specified in the request.
boolean	isCachingEnabled() Returns whether component definition caching is enabled for this component.
boolean	isEventLoggingEnabled() Called to determine if a component wants event logging.
boolean	isStateless() By default, this method returns false, indicating that state will be maintained for instances of the receiver.
static void	logString(String string) Deprecated. logString is no longer supported.
String	name() Returns the name of the component, which includes a path of all directories under DOCUMENTROOT/WebObjects and is minus the ".wo" extension.
WOComponent	pageWithName(String aName) Returns a new page instance (a WOComponent object) identified by aName.
WOComponent	parent()
String	path() Deprecated. use pathURL instead.
URL	pathURL() Returns the path URL to the component.
WOActionResults	performParentAction(String anActionName) Allows a subcomponent to invoke an action method of its parent component bound to the child component.
void	pullValuesFromParent() Pulls binding values from the parent component.
void	pushValuesToParent() Pushes binding values to the parent component.
void	reset() Allows a stateless component to reset temporary references.
WOSession	session() Returns the current WOSession object.
void	set_componentUnroll(Object anObject) Private.
void	set_unroll(Object anObject) Private - this method is used by the Direct to Web generation layer, and does nothing in WOComponent.
void	setCachingEnabled(boolean aFlag) Enables or disables the caching of this component's definition.
void	setValueForBinding(Object aValue, String aBindingName) Sets the value of the binding specified in the parent component.
void	setVariableValueForName(String name, Object value)
void	sleep() Invoked at the conclusion of a request-handling cycle.
boolean	synchronizesVariablesWithBindings() Indicates if the push-pull of values in the parent component is enabled.
void	takeValueForKey(Object value, String key) Conformance to NSKeyValueCoding.
void	takeValueForKeyPath(Object value, String keyPath) Conformance to NSKeyValueCodingAdditions.
void	takeValuesFromRequest(WORequest aRequest, WOContext aContext) Tells the component to synchronize its variables with values from the request.
WOElement	template() Returns the graph of static, dynamic elements and components that compose this component.
static WOElement	templateWithHTMLString(String anHTMLString, String aDeclarationString, NSArray aLanguageArray) Deprecated. Use WOComponent.templateWithHTMLString(String, String, String, NSArray, WOAssociationFactory, WOMLNamespaceProvider) instead.
static WOElement	templateWithHTMLString(String referenceName, String anHTMLString, String aDeclarationString, NSArray aLanguageArray, WOAssociationFactory associationFactory, WOMLNamespaceProvider namespaceProvider) Deprecated. since 5.4
static WOElement	templateWithHTMLString(String frameworkName, String referenceName, String anHTMLString, String aDeclarationString, NSArray aLanguageArray, WOAssociationFactory associationFactory, WOMLNamespaceProvider namespaceProvider) Programmatically creates a component's template.
WOElement	templateWithName(String aName) Deprecated. Use template instead.
String	toString()
void	unableToSetNullForKey(String key) Conformance to NSKeyValueCoding.ErrorHandling.
Object	validateTakeValueForKeyPath(Object value, String keyPath) Validates (and coerces) the given value, assigning it if it is different than the current value.
Object	validateValueForKey(Object value, String key) Conformance to NSValidation.
void	validationFailedWithException(Throwable t, Object value, String keyPath) Called when an Enterprise Object or formatter failed validation during an assignment.
Object	valueForBinding(String aBindingName) Gets the value for the specified binding from the parent component.
boolean	valueForBooleanBinding(String binding, boolean defaultValue) Gets the value of an optional boolean binding of the component.
Integer	valueForIntegerBinding(String binding, Number defaultValue) Gets the value of an optional integer binding of the component.
Object	valueForKey(String key) Conformance to NSKeyValueCoding.
Object	valueForKeyPath(String keyPath) Conformance to NSKeyValueCodingAdditions.
NSArray	valueForNSArrayBindings(String binding, NSArray defaultValue) Gets the value of an optional NSArray binding of the component.
NSDictionary	valueForNSDictionaryBindings(String binding, NSDictionary defaultValue) Gets the value of an optional NSDictionary binding of the component.
Number	valueForNumberBinding(String binding, Number defaultValue) Gets the value of an optional number binding of the component.
String	valueForStringBinding(String binding, String defaultValue) Gets the value of an optional String binding of the component.
Object	variableValueForName(String name)
WOComponentVariable	variableWithName(String name)

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

WOComponent

@Deprecated
public WOComponent()

Deprecated. use WOComponent(WOContext aContext) instead. Using this constructor will slow down your application considerably.

See Also:

WOComponent.WOComponent(WOContext aContext)

WOComponent

public WOComponent(WOContext aContext)

WebObjects Builder archive files exist in the component directory, and this constructor initializes component variables from this archive. This constructor throws exceptions if it cannot determine the name of the component or if it cannot initialize the object for any other reason. Override WOComponent(WOContext aContext) in compiled subclasses to perform custom initializations; as always, first invoke super's default constructor.

Parameters:

aContext - context of a transaction

Method Detail

clone

public Object clone()
             throws CloneNotSupportedException

Conformance to Cloneable.

Overrides:

clone in class Object

Returns:

a new object that is a copy of the receiver

Throws:

CloneNotSupportedException - when the object is not of known format

toString

public String toString()

Overrides:

toString in class WOElement

Returns:

a String including the name of the receiving class plus the name of each subcomponent

name

public String name()

Returns the name of the component, which includes a path of all directories under DOCUMENTROOT/WebObjects and is minus the ".wo" extension. For example, "Main" is a typical component name.

Returns:

name of the current component

See Also:

WOComponent.baseURL(), WOComponent.path()

path

@Deprecated
public String path()

Deprecated. use pathURL instead.

Returns:

path of the component

See Also:

WOComponent.pathURL()

pathURL

public URL pathURL()

Returns the path URL to the component. The URL includes the .wo extension. For example file://Users/auser/MyApp.woa/Resources/Main.wo or jar:file://Users/auser/MyApp.jar!/Resources/Main.wo or

Returns:

path URL of the component

Since:

5.2.2

See Also:

WOComponent.baseURL(), WOComponent.name()

baseURL

public String baseURL()

Returns the component URL relative to the server's document root. For example:"/WebObjects/MyApp.woa/Resources/Main.wo".

Returns:

server relative URL

See Also:

WOComponent.name(), WOComponent.path()

frameworkName

public String frameworkName()

If the component is stored in a framework, this method returns the name of that framework. For example, if the component is in the framework NeXT_ROOT/System/Library/Frameworks/WOExtensions.framework, then this method returns the String "WOExtensions". If the component is not stored in a framework, this method returns null.

Returns:

name of the framework containing the component

See Also:

WOResourceManager

setCachingEnabled

public void setCachingEnabled(boolean aFlag)

Enables or disables the caching of this component's definition. WOComponent definitions contain templates and other common information related to components and are used to generate instances of these components. When this attribute is set to true, the application parses the HTML template and the declaration (".wod") file of a component once and then stores the resulting component definition for future requests.

By default, individual component definition caching is controlled by WOApplication's global component definition caching policy. The global policy is set according to the start-up parameter WOCachingEnabled, or WOApplication's setCachingEnabled(boolean aFlag). With it, you can turn component definition caching off globally. You can then control caching of individual component definitions using WOComponent's version of this method. Note that most large applications will set the global caching to false at deployment time. Selective caching is an especially valuable technique for large applications where a few highly specialized components should not be cached but re-parsed everytime they are requested.

Parameters:

aFlag - flag deciding the caching of the receiving component

See Also:

WOComponent.isCachingEnabled(), WOApplication.setCachingEnabled(boolean aFlag)

isCachingEnabled

public boolean isCachingEnabled()

Returns whether component definition caching is enabled for this component. False is the default. Note that most large applications will set the global caching to true at deployment time, so this flag often has a different value between development and deployment.

Returns:

true if caching is enabled for the component, false otherwise

See Also:

WOComponent.setCachingEnabled(boolean flag), WOApplication.isCachingEnabled()

template

public WOElement template()

Returns the graph of static, dynamic elements and components that compose this component. It is a WOElement representing the root object of the graph of static and dynamic HTML elements and subcomponents that is used to graphically render the receiving component. This template is constructed from the ".html" and ".wod" files found in the component directory. Note that this WOElement template is shared amongst all instances of the component. If component definition caching is set to false, the WOElement template will be reconstructed from the ".html" and .wod" files, for every request of this particular component, and the object returned will change with every request. Therefore, the return value of this method may change between development and deployment if you trigger caching and non-caching modes.

Returns:

the WOElement object corresponding to the receiving component

See Also:

WOElement, WOComponent.setCachingEnabled(boolean), WOApplication.setCachingEnabled(boolean aFlag)

pullValuesFromParent

public void pullValuesFromParent()

Pulls binding values from the parent component. If this component synchronizes its bindings with its parent component (that is, if synchronizesVariablesWithBindings() returns true), this method causes binding values to be pulled from the parent component.

pushValuesToParent

public void pushValuesToParent()

Pushes binding values to the parent component. If this component synchronizes its bindings with its parent component (that is, if synchronizesVariablesWithBindings() returns true), this method causes binding values to be pushed up to the parent component.

templateWithName

@Deprecated
public WOElement templateWithName(String aName)

Deprecated. Use template instead.

This method should not be used.

Parameters:

aName - ignored

Returns:

the root WOElement object of the component definition.

See Also:

WOComponent.template()

bindingKeys

public NSArray bindingKeys()

Returns an NSArray containing the binding keys (as String objects) for each of the WOComponent's associations. The binding keys are defined in the left column of the table in the component inspector window in WebObjects Builder

Returns:

NSArray array of keys for the component

isStateless

public boolean isStateless()

By default, this method returns false, indicating that state will be maintained for instances of the receiver. Overriding this method to return true will make the component stateless. A single instance of each stateless component is shared between multiple sessions, reducing the application's memory footprint.

By default, stateless components don't synchronize. So, if you override this method to return true and you want the component to synchronize, you must also override synchronizesVariablesWithBindings and return true.

Returns:

true if this method is overidden, false otherwise

See Also:

WOComponent.reset(), WOComponent.synchronizesVariablesWithBindings()

reset

public void reset()

Allows a stateless component to reset temporary references. This method -- which is only invoked if the component is stateless -- allows a component instance to reset or delete temporary references to objects that are specific to a given context. To ensure that when the shared instance of a component is reused by another session there are no side effects, implement this method so that it releases and sets to null each of the component's instance variables.

See Also:

WOComponent.isStateless()

synchronizesVariablesWithBindings

public boolean synchronizesVariablesWithBindings()

Indicates if the push-pull of values in the parent component is enabled. Returns whether a nested component pulls all values down from its parent and pushes all values to its parent before and after each phase of the request-response loop.

This method returns false for stateless components and true otherwise. Override this method to create a non-synchronizing, stateful component (return false ), or a synchronizing stateless component (return true).

Returns:

false if this method creates a non-synchronizing component, true otherwise

See Also:

WOComponent.valueForBinding(String aBindingName), WOComponent.setValueForBinding(Object aValue, String aBindingName), WOComponent.pullValuesFromParent(), WOComponent.pushValuesToParent(), WOComponent.isStateless()

valueForBinding

public Object valueForBinding(String aBindingName)

Gets the value for the specified binding from the parent component. If the current component doesn't define this key, this method returns null.

Parameters:

aBindingName - name of a binding

Returns:

value for the input binding name

See Also:

WOComponent.canGetValueForBinding(String aBindingName), WOComponent.setValueForBinding(Object aValue, String aBindingName), WOComponent.synchronizesVariablesWithBindings()

valueForBooleanBinding

public boolean valueForBooleanBinding(String binding,
                                      boolean defaultValue)

Gets the value of an optional boolean binding of the component.

Parameters:

binding - The binding name

defaultValue - The default value

Returns:

binding value or default

Since:

5.4

valueForNumberBinding

public Number valueForNumberBinding(String binding,
                                    Number defaultValue)

Gets the value of an optional number binding of the component.

Parameters:

binding - The binding name

defaultValue - The default value

Returns:

binding value or default

Since:

5.4

valueForIntegerBinding

public Integer valueForIntegerBinding(String binding,
                                      Number defaultValue)

Gets the value of an optional integer binding of the component.

Parameters:

binding - The binding name

defaultValue - The default value

Returns:

binding value or default

Since:

5.4

valueForStringBinding

public String valueForStringBinding(String binding,
                                    String defaultValue)

Gets the value of an optional String binding of the component.

Parameters:

binding - The binding name

defaultValue - The default value

Returns:

binding value or default

Since:

5.4

valueForNSArrayBindings

public NSArray valueForNSArrayBindings(String binding,
                                       NSArray defaultValue)

Gets the value of an optional NSArray binding of the component.

Parameters:

binding - The binding name

defaultValue - The default value

Returns:

binding value or default

Since:

5.4

valueForNSDictionaryBindings

public NSDictionary valueForNSDictionaryBindings(String binding,
                                                 NSDictionary defaultValue)

Gets the value of an optional NSDictionary binding of the component.

Parameters:

binding - The binding name

defaultValue - The default value

Returns:

binding value or default

Since:

5.4

setValueForBinding

public void setValueForBinding(Object aValue,
                               String aBindingName)

Sets the value of the binding specified in the parent component. The binding specified by aBindingName is set to aValue in the parent component. If the binding isn't settable, this method throws an exception.

Parameters:

aValue - value of the binding

aBindingName - name of the binding to be set

See Also:

WOAssociation.isValueSettableInComponent(WOComponent aComponent)

hasBinding

public boolean hasBinding(String aBindingName)

Returns whether the component has a binding named aBindingName. This method traverses the chain of associations to the top-level parent, if necessary.

Parameters:

aBindingName - name of the binding

Returns:

true if the binding exists on the component else false

See Also:

WOComponent.canGetValueForBinding(String aBindingName), WOComponent.canSetValueForBinding(String aBindingName)

canGetValueForBinding

public boolean canGetValueForBinding(String aBindingName)

Verifies that the binding exists and that valueForBinding will return a value. The default implementation just calls hasBinding(String aBindingName)

Parameters:

aBindingName - binding name used when values are pushed to or pulled from the parent component

Returns:

true if key gets value for binding, otherwise false

See Also:

WOComponent.canSetValueForBinding(String aBindingName), WOComponent.hasBinding(String aBindingName), WOComponent.valueForBinding(String aBindingName)

canSetValueForBinding

public boolean canSetValueForBinding(String aBindingName)

Verifies that the binding exists and that setValueForBinding will succeed.

Parameters:

aBindingName - binding name used when values are pushed to or pulled from the parent component

Returns:

true if key can set value for binding, otherwise false

See Also:

WOComponent.canGetValueForBinding(String aBindingName), WOComponent.hasBinding(String aBindingName), WOComponent.setValueForBinding(Object aValue, String aBindingName)

awake

public void awake()

Invoked at the beginning of a WOComponent's involvement in a cycle of the request-response loop. It gives the WOComponent an opportunity to initialize its instance variables or perform setup operations. The default implementation does nothing.

See Also:

WOComponent.ensureAwakeInContext(WOContext aContext), WOComponent.sleep()

ensureAwakeInContext

public void ensureAwakeInContext(WOContext aContext)

Ensures that the receiver is awake in the specified context. Invoke this method before using a component which was stored in a variable. You don't need to invoke ensureAwakeInContext() if the component was just created with pageWithName, if it was restored from the WebObjects page cache, or if the page will simply be returned as the result of an action. That is, you only need to invoke this method if you're going to invoke methods on a component that is otherwise not awakened. If the receiving component is already awake, this method has no effect.

Parameters:

aContext - context of a transaction

See Also:

WOComponent.awake(), WOComponent.pageWithName(String aName)

takeValuesFromRequest

public void takeValuesFromRequest(WORequest aRequest,
                                  WOContext aContext)

Tells the component to synchronize its variables with values from the request. It is systematically called during the first phase of the component request handling. All WOComponent objects associated with a request are called with this method during the first phase of the request-response loop. The default WOComponent behavior is to invoke the method on the root WOElement object of the component's template (returned by template(). In this phase, each dynamic element in the template extracts any entered data or changed state (such as a check in a check box) associated with an attribute and assigns the value to the component variable bound to the attribute. Subclasses of WOComponent can override this method to replace or supplement the default behavior with custom logic.

Overrides:

takeValuesFromRequest in class WOElement

Parameters:

aRequest - the current request with the WOComponent object

aContext - context of a transaction

See Also:

WOComponent.appendToResponse(WOResponse aResponse, WOContext aContext), WOComponent.invokeAction(WORequest aRequest, WOContext aContext)

invokeAction

public WOActionResults invokeAction(WORequest aRequest,
                                    WOContext aContext)

Tells the component to execute any action specified in the request. It is systematically called during the middle phase of the component request handling. All WOComponent objects associated with a request page invoke this method. In this middle phase, the invokeAction method is propagated through the WOElement objects of the page. The dynamic element on which the user has acted (by, for example, clicking a button) responds by triggering the method in the request component that is bound to the action. WOComponent's default implementation of this method invokes invokeAction on the root WOElement object of the component template.

Overrides:

invokeAction in class WOElement

Parameters:

aRequest - the request

aContext - context of the transaction

Returns:

a WOActionResults containing the result of the request

See Also:

WOComponent.appendToResponse(WOResponse aResponse, WOContext aContext), WOComponent.takeValuesFromRequest(WORequest aRequest, WOContext aContext)

appendToResponse

public void appendToResponse(WOResponse aResponse,
                             WOContext aContext)

Forces the component to generate its interface and output it in the response's content. Component objects associated with a response receive this message during the last phase of the component request handling, or when returned by a direct action method. In the append-to-response phase, application objects (particularly the response page instance itself) generate the HTML content of the page. WOComponent's default implementation of this method invokes the appendToResponse method on the root WOElement object of the component template, which in turn invokes appendToResponse. Subclasses of WOComponent can override this method to replace or supplement the default behavior with custom logic.

Overrides:

appendToResponse in class WOElement

Parameters:

aResponse - the HTTP response that an application returns to a Web server to complete a cycle of the request-response loop

aContext - context of a transaction

See Also:

WOComponent.invokeAction(WORequest aRequest, WOContext aContext), WOComponent.takeValuesFromRequest(WORequest aRequest, WOContext aContext)

sleep

public void sleep()

Invoked at the conclusion of a request-handling cycle. It gives the component the opportunity for releasing references to objects created and initialized in its awake method. The default implementation does nothing.

See Also:

WOComponent.awake()

parent

public WOComponent parent()

Returns:

the component from which the component is generated (its parent component)

performParentAction

public WOActionResults performParentAction(String anActionName)

Allows a subcomponent to invoke an action method of its parent component bound to the child component. Parent and child components are "synchronized" when this method returns. The variables that are bound by a declaration of the child component in the parent component's declaration file have the same value.

An example best illustrates this mechanism. Let's say there is a Palette subcomponent, and this WOComponent is nested in a parent component with a displaySelection action method. When the user selects an item in the palette (perhaps a color), you want to invoke displaySelection to show the result of the new selection (perhaps a car in the new color). The declaration in the parent's .wod file would look like this:

        PALETTE: Palette {
          selection = number;
          callBack = "displaySelection";
        };
 

The "callBack" item is an arbitrary attribute of the child component bound in this declaration to the parent component's displaySelection method. The performParentAction method is used to activate this binding. Assuming the child component has an action method called click, the implementation would look like this:

 public WOActionResults click() { // this is the child's action
     selection = "xxxx"; // some value
     // now invoke the parent's action
     return performParentAction(callBack);
 }
 

Parameters:

anActionName - name of the current action method

Returns:

an action method same as its parent component

variableWithName

public WOComponentVariable variableWithName(String name)

variableValueForName

public Object variableValueForName(String name)

setVariableValueForName

public void setVariableValueForName(String name,
                                    Object value)

application

public WOApplication application()

Returns the WOApplication object for the current application.

Returns:

the WOApplication instance

See Also:

WOComponent.context(), WOComponent.session(), WOApplication

context

public WOContext context()

Returns the WOContext object for the current transaction (request-response loop)

Returns:

the context of the transaction

See Also:

WOComponent.application(), WOComponent.session(), WOContext

hasSession

public boolean hasSession()

Returns whether the component is already in a session. For example, in direct actions, sessions are lazily created and you can avoid creating one unnecessarily by calling hasSession before session.

Returns:

true if the component is in a session, false otherwise

See Also:

WOComponent.session()

session

public WOSession session()

Returns the current WOSession object. This method creates a new session if there isn't already one.

Returns:

the current session

See Also:

WOComponent.application(), WOComponent.context(), WOComponent.hasSession(), WOSession

pageWithName

public WOComponent pageWithName(String aName)

Returns a new page instance (a WOComponent object) identified by aName. If aName is null, the "Main" component is returned. If the method cannot create a valid page instance, it throws an exception.

Parameters:

aName - the name of the component to be returned

Returns:

the component if it exists

See Also:

WOSession.restorePageForContextID(String aContextID), WOSession.savePage(WOComponent aPage), WOApplication.pageWithName(String aName, WOContext aContext)

logString

@Deprecated
public static void logString(String string)

Deprecated. logString is no longer supported.

Use NSLog instead.

Parameters:

string -

See Also:

NSLog

debugString

@Deprecated
public static void debugString(String string)

Deprecated. debugString is no longer supported

Use NSLog instead.

Parameters:

string -

See Also:

NSLog

validationFailedWithException

public void validationFailedWithException(Throwable t,
                                          Object value,
                                          String keyPath)

Called when an Enterprise Object or formatter failed validation during an assignment. The default implementation ignores the error. Subclassers can override to record the error and possibly return a different page for the current action

Parameters:

t - the exception thrown during validation

value - the given value to be validated

keyPath - the key path associated with this value, identifies the property of an object

validateValueForKey

public Object validateValueForKey(Object value,
                                  String key)
                           throws NSValidation.ValidationException

Conformance to NSValidation.

Specified by:

validateValueForKey in interface NSValidation

Parameters:

value - the given value to be validated

key - the key path associated with this value, identifies the property of an object

Returns:

the validated value if it's legal

Throws:

NSValidation.ValidationException - when the key cannot be validated by validateValueForKey

See Also:

WOComponent.validateValueForKey(java.lang.Object, java.lang.String)

validateTakeValueForKeyPath

public Object validateTakeValueForKeyPath(Object value,
                                          String keyPath)
                                   throws NSValidation.ValidationException

Validates (and coerces) the given value, assigning it if it is different than the current value. Throws a validation exception if validateValueForKey returns an exception. Returns the coerced (assigned) value.

Specified by:

validateTakeValueForKeyPath in interface NSValidation

Parameters:

value - the given value to be validated

keyPath - the key path associated with this value, identifies the property of an object

Returns:

the coerced (assigned) value

Throws:

NSValidation.ValidationException - when the key cannot be validated by validateValueForKey

See Also:

WOComponent.validateValueForKey(Object value, String key)

templateWithHTMLString

@Deprecated
public static WOElement templateWithHTMLString(String anHTMLString,
                                                          String aDeclarationString,
                                                          NSArray aLanguageArray)

Deprecated. Use WOComponent.templateWithHTMLString(String, String, String, NSArray, WOAssociationFactory, WOMLNamespaceProvider) instead.

This method is the backwards-compatible version of WOComponent.templateWithHTMLString(String, String, String, NSArray, WOAssociationFactory, WOMLNamespaceProvider), which is the preferred API call.

Parameters:

anHTMLString - HTML string to create the template of the component

aDeclarationString - declaration on the template of the component

aLanguageArray - list of languages in specific order

Returns:

the template of the component.

templateWithHTMLString

@Deprecated
public static WOElement templateWithHTMLString(String referenceName,
                                                          String anHTMLString,
                                                          String aDeclarationString,
                                                          NSArray aLanguageArray,
                                                          WOAssociationFactory associationFactory,
                                                          WOMLNamespaceProvider namespaceProvider)

Deprecated. since 5.4

Programmatically creates a component's template. Using anHTMLString as the HTML template contents and aDeclarationString as the declarations file contents, returns (as a WOElement object) the graph of static and dynamic elements built by parsing the HTML and declaration Strings. You can then use the returned WOElement as a component's template. This method is not called by WebObjects.

Parameters:

referenceName - A name to use in reference to lend context to any exceptions thrown, or null if none is desired. For example, WOComponent would pass its name().

anHTMLString - HTML string to create the template of the component

aDeclarationString - declaration on the template of the component

aLanguageArray - list of languages in specific order

associationFactory - The association factory to use when parsing the template, pass WOApplication.application().associationFactory() for the default behavior.

namespaceProvider - The namespace provider to be used when parsing the template, pass WOApplication.application().namespaceProvider() for the default behavior.

Returns:

the template of the component

See Also:

WOComponent.templateWithName(String aName)

templateWithHTMLString

public static WOElement templateWithHTMLString(String frameworkName,
                                               String referenceName,
                                               String anHTMLString,
                                               String aDeclarationString,
                                               NSArray aLanguageArray,
                                               WOAssociationFactory associationFactory,
                                               WOMLNamespaceProvider namespaceProvider)

Programmatically creates a component's template. Using anHTMLString as the HTML template contents and aDeclarationString as the declarations file contents, returns (as a WOElement object) the graph of static and dynamic elements built by parsing the HTML and declaration Strings. You can then use the returned WOElement as a component's template. This method is not called by WebObjects.

Parameters:

frameworkName - framework name of the component to parse

referenceName - A name to use in reference to lend context to any exceptions thrown, or null if none is desired. For example, WOComponent would pass its name().

anHTMLString - HTML string to create the template of the component

aDeclarationString - declaration on the template of the component

aLanguageArray - list of languages in specific order

associationFactory - The association factory to use when parsing the template, pass WOApplication.application().associationFactory() for the default behavior.

namespaceProvider - The namespace provider to be used when parsing the template, pass WOApplication.application().namespaceProvider() for the default behavior.

Returns:

the template of the component

Since:

5.4

See Also:

WOComponent.templateWithName(String aName)

descriptionForResponse

public String descriptionForResponse(WOResponse aResponse,
                                     WOContext aContext)

Records information about the component, if it is the top-level component. The default implementation records the component's name. You might override this method if you want to record more information about the component. For example, you might want to record the values of some instance variables as well as the component name.

This method is invoked only on the top-level response component, that is, the one representing the entire page. Components nested inside of that top-level component do not receive this method.

If a CLFF log file is kept for this application, the string returned by this method is recorded in that log file. Thus, you must ensure that the string you return can be analyzed by a CLFF-analysis tool.

Parameters:

aResponse - the HTTP response that an application returns to a Web server to complete a cycle of the request-response loop

aContext - context of a transaction

Returns:

the information about the response component

See Also:

WOStatisticsStore

generateResponse

public WOResponse generateResponse()

Conformance to WOActionResults. Returns a newly-created WOResponse object. WOComponent's default implementation of this method translates the receiving component into a new WOResponse object by invoking appendToResponse on itself.

Specified by:

generateResponse in interface WOActionResults

Returns:

an HTTP response that the application will to a Web server to complete a cycle of the request-response loop

See Also:

WOComponent.appendToResponse(WOResponse, WOContext), WOResponse.generateResponse()

set_unroll

public void set_unroll(Object anObject)

Private - this method is used by the Direct to Web generation layer, and does nothing in WOComponent.

Parameters:

anObject - name of the current object

set_componentUnroll

public void set_componentUnroll(Object anObject)

Private. This method is used by the Direct to Web generation layer, and does nothing in WOComponent.

Parameters:

anObject - name of the current object

isEventLoggingEnabled

public boolean isEventLoggingEnabled()

Called to determine if a component wants event logging. This is not desirable, for example, for components which are associated with events as they would interfere with the actual event logging. The default implementation of this method returns true.

Returns:

true if the event logging is enabled for the component, false otherwise

See Also:

WOEvent

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

WOComponent's implementation of this static method returns true. It indicates that key-value coding is allowed to access fields in this object if an appropriate method is not present.

Returns:

true if key can access fields directly, otherwise false

valueForKey

public Object valueForKey(String key)

Conformance to NSKeyValueCoding.

Specified by:

valueForKey in interface NSKeyValueCoding

Parameters:

key - identifies the property of an object

Returns:

the receiver's value for the property identified by key

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleQueryWithUnboundKey(java.lang.String)

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

Conformance to NSKeyValueCoding.

Specified by:

takeValueForKey in interface NSKeyValueCoding

Parameters:

key - identifies the property to be set

value - the value to which the property specified by key should be set

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.valueForKey, NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleTakeValueForUnboundKey(java.lang.Object, java.lang.String)

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Conformance to NSKeyValueCoding.ErrorHandling.

Specified by:

handleQueryWithUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - one of the attributes of the receiver's request

Returns:

can return a value, in which case that value is returned by the corresponding valueForKey invocation

See Also:

NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.UnknownKeyException#TargetObjectUserInfoKey, NSKeyValueCoding.UnknownKeyException#UnknownUserInfoKey, NSKeyValueCoding.valueForKey(String key)

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)

Conformance to NSKeyValueCoding.ErrorHandling.

Specified by:

handleTakeValueForUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

value - receiver's property identified by key is set to this

key - one of the attributes of the receiver's request

See Also:

NSKeyValueCoding.UnknownKeyException#TargetObjectUserInfoKey, NSKeyValueCoding.UnknownKeyException#UnknownUserInfoKey, NSKeyValueCoding.takeValueForKey(Object value, String key)

unableToSetNullForKey

public void unableToSetNullForKey(String key)

Conformance to NSKeyValueCoding.ErrorHandling.

Specified by:

unableToSetNullForKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - identifies the property of an object

See Also:

NSKeyValueCoding.takeValueForKey, NSKeyValueCoding.DefaultImplementation

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Conformance to NSKeyValueCodingAdditions.

Specified by:

valueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - identifies the derived property of an object

Returns:

receiver's value for the derived property identified by keyPath

See Also:

NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCodingAdditions.takeValueForKeyPath(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)

Conformance to NSKeyValueCodingAdditions.

Specified by:

takeValueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - identifies a derived property of the receiver

value - value to which the derived property identified by keyPath will be set

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation