com.iplanet.jato.view
Class ContainerViewBase

java.lang.Object
  |
  +--com.iplanet.jato.view.ViewBase
        |
        +--com.iplanet.jato.view.ContainerViewBase
All Implemented Interfaces:
ContainerView, View
Direct Known Subclasses:
RequestHandlingViewBase, TiledViewBase

public abstract class ContainerViewBase
extends ViewBase
implements ContainerView

A default implementation of ContainerView. This implementation provides optimized initialization of child views; child views are not created unless they are referenced.

Version:
JATO/1.2.2 $Id: ContainerViewBase.java,v 1.35 2002/07/13 00:47:20 todd Exp $

Field Summary
static java.lang.String BEGIN_DISPLAY_EVENT_METHOD_PREFIX
           
static java.lang.String BEGIN_DISPLAY_EVENT_METHOD_SUFFIX
           
static java.lang.String END_DISPLAY_EVENT_METHOD_PREFIX
           
static java.lang.String END_DISPLAY_EVENT_METHOD_SUFFIX
           
protected static MethodRegistry eventMethodRegistry
           
protected static boolean OPTION_ENABLE_QUALIFIELD_CHILD_NAME_LOOKUPS
           
protected static boolean OPTION_USE_LEGACY_DISPLAY_EVENT_SIGNATURES
           
 
Fields inherited from interface com.iplanet.jato.view.View
QUALIFIED_VIEW_NAME_SEPARATOR
 
Constructor Summary
protected ContainerViewBase()
          Default constructor
  ContainerViewBase(View parent, java.lang.String name)
          Creates a ContainerViewBase with a parent and name
 
Method Summary
 void appMessage(java.lang.String message)
          Adds a message to the application message buffer that appears at the bottom of the rendered HTML page.
 boolean beginChildDisplay(ChildDisplayEvent event)
          Automatically called as notification that the JSP has begun its display processing on the named child.
protected  boolean beginChildDisplay(java.lang.String childName)
          Deprecated. Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.
protected  void beginDisplay()
          Deprecated. Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.
 void beginDisplay(DisplayEvent event)
          Automatically called as notification that the JSP has begun its display processing of this view.
protected  boolean childExists(java.lang.String name)
          This method can be used to determine if a child has been allocated, and thus whether a value has been assigned to it.
protected abstract  View createChild(java.lang.String name)
          Called to instantiate the named child.
 View createChildInternal(java.lang.String name)
          Required for framework support.
 java.lang.String endChildDisplay(ChildContentDisplayEvent event)
          Automatically called as notification that the JSP has completed its display processing on the named child.
protected  java.lang.String endChildDisplay(java.lang.String childName, java.lang.String html)
          Deprecated. Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.
protected  void endDisplay()
          Deprecated. Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.
 void endDisplay(DisplayEvent event)
          Automatically called as notification that the JSP has ended its display processing.
protected  View ensureChild(java.lang.String name)
          Ensures that the named child has been instantiated within this container.
 View getChild(java.lang.String name)
          Returns the named child view.
 java.lang.String[] getChildNames()
          Returns the names of all children registered with this view.
 java.lang.String[] getChildNames(java.lang.Class type)
           
 java.lang.Class getChildType(java.lang.String name)
          Returns the type of the named child, as previously registered via registerChild(...).
 java.lang.String[] getCommandChildNames()
          Returns the names of registered children that are of type Command .
 Model getDefaultModel()
          Returns this view's default model.
 DisplayField getDisplayField(java.lang.String name)
          Returns the named DisplayField child.
 boolean getDisplayFieldBooleanValue(java.lang.String name)
          Returns the value of the named DisplayField child as a boolean.
 double getDisplayFieldDoubleValue(java.lang.String name)
          Returns the value of the named DisplayField child as a double.
 int getDisplayFieldIntValue(java.lang.String name)
          Returns the value of the named DisplayField child as an int.
 java.lang.String getDisplayFieldStringValue(java.lang.String name)
          Returns the value of the named DisplayField child as a string.
 java.lang.Object getDisplayFieldValue(java.lang.String name)
          Returns the value of the named DisplayField child.
 int getNumChildren()
          Returns the number of registered children
 java.lang.String[] getQualifiedCommandChildNames()
          Returns the fully-qualified names of the children that are of type Command.
protected  void mapRequestParameter(DisplayField field, java.lang.Object[] childValues)
          Called by mapRequestParameters() to set the value of a request parameter on a specific display field.
 void mapRequestParameters(javax.servlet.http.HttpServletRequest request)
          Maps servlet request parameter values into subviews.
protected  void onValidationException(DisplayField field, java.lang.Object[] values, java.lang.RuntimeException e)
          Called if the setValues(...) on a child DisplayField throws an exception during request parameter mapping.
 void registerChild(java.lang.String name, java.lang.Class type)
          Called to register each child instance and its type with the container.
protected static void registerDisplayEventHandlers(java.lang.Class clazz)
          Internal method used to register child field display handler methods.
 void removeAllChildren()
          Removes all instantiated children from this container.
 void removeChild(java.lang.String name)
          Removes the named child from the current list of instantiated children.
protected  java.lang.String removeQualifiedNameIndices(java.lang.String name)
          Given a name like this:
 void resetChildren()
          Resets all children to a default state in a container-defined way.
protected  void setDefaultModel(Model value)
          Sets the default model instance that will be used by this view.
 void setDisplayFieldValue(java.lang.String name, boolean value)
          Sets the value of the named DisplayField child to a boolean value.
 void setDisplayFieldValue(java.lang.String name, double value)
          Sets the value of the named DisplayField child to a double value.
 void setDisplayFieldValue(java.lang.String name, int value)
          Sets the value of the named DisplayField child to an int value.
 void setDisplayFieldValue(java.lang.String name, java.lang.Object value)
          Sets the value of the named DisplayField child.
 void unregisterChild(java.lang.String name)
          Removes the named child from the current list of instantiated and registered children
 
Methods inherited from class com.iplanet.jato.view.ViewBase
getName, getParent, getParentViewBean, getQualifiedName, getRootView, getRootView, setName, setParent
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.iplanet.jato.view.View
getName, getParent, getQualifiedName, setParent
 

Field Detail

BEGIN_DISPLAY_EVENT_METHOD_PREFIX

public static final java.lang.String BEGIN_DISPLAY_EVENT_METHOD_PREFIX

BEGIN_DISPLAY_EVENT_METHOD_SUFFIX

public static final java.lang.String BEGIN_DISPLAY_EVENT_METHOD_SUFFIX

END_DISPLAY_EVENT_METHOD_PREFIX

public static final java.lang.String END_DISPLAY_EVENT_METHOD_PREFIX

END_DISPLAY_EVENT_METHOD_SUFFIX

public static final java.lang.String END_DISPLAY_EVENT_METHOD_SUFFIX

eventMethodRegistry

protected static final MethodRegistry eventMethodRegistry

OPTION_ENABLE_QUALIFIELD_CHILD_NAME_LOOKUPS

protected static final boolean OPTION_ENABLE_QUALIFIELD_CHILD_NAME_LOOKUPS

OPTION_USE_LEGACY_DISPLAY_EVENT_SIGNATURES

protected static final boolean OPTION_USE_LEGACY_DISPLAY_EVENT_SIGNATURES
Constructor Detail

ContainerViewBase

protected ContainerViewBase()
Default constructor

ContainerViewBase

public ContainerViewBase(View parent,
                         java.lang.String name)
Creates a ContainerViewBase with a parent and name
Parameters:
parent - The parent view or null if this view has no parent
name - The logical name of this view
Method Detail

getDefaultModel

public Model getDefaultModel()
Returns this view's default model. The default model is typically used by DisplayField children for default value storage (if they are not bound to any other model). This method returns a DefaultModel instance if a default model hasn't already been set in this instance. Note that the default model need not be an actual instance of DefaultModel, although this is usually the case.
Specified by:
getDefaultModel in interface ContainerView
Returns:
The default model instance. This instance is always valid and will never be null.

setDefaultModel

protected void setDefaultModel(Model value)
Sets the default model instance that will be used by this view. Note that the default model need not be an actual instance of DefaultModel, although this is usually the case.
Parameters:
value - The default model to be used

registerChild

public void registerChild(java.lang.String name,
                          java.lang.Class type)
Called to register each child instance and its type with the container. This method should be called from during the construction of this view or before any other operations involving children are invoked on this object.

This method provides to the container the information necessary to manage the specified child views. This information is needed separately from the actual creation of the child views, and is used to manage them efficiently without instantiating them.

Parameters:
name - The logical name of the child view
type - The class name of the child view

unregisterChild

public void unregisterChild(java.lang.String name)
Removes the named child from the current list of instantiated and registered children
Parameters:
name - The logical name of the child to unregister

ensureChild

protected View ensureChild(java.lang.String name)
Ensures that the named child has been instantiated within this container.
Parameters:
name - The name of the child within this container
Returns:
The specified child view
Throws:
java.lang.IllegalArgumentException - Thrown if the child name does not correspond to a child in this container

resetChildren

public void resetChildren()
Resets all children to a default state in a container-defined way. For example, if the contained children are instances of DisplayField , these children may be set to contain default values. This implementation does nothing, leaving the appropriate action to derived classes.
Specified by:
resetChildren in interface ContainerView

createChild

protected abstract View createChild(java.lang.String name)
Called to instantiate the named child. This method will typically be called only when access to a child is required, for example, as the result of a getChild(...) method call.
Parameters:
name - The name of the child to instantiate. This method may throw an IllegalArgumentException to indicate an improper child name.
Returns:
The named child view or null if this name does not correspond to a child associated with this container.

createChildInternal

public final View createChildInternal(java.lang.String name)
Required for framework support. This method is an internal method that should not be used by application developers.

removeChild

public void removeChild(java.lang.String name)
Removes the named child from the current list of instantiated children. However, the child will still be registered and may be instantiated again by a call to getChild().
Parameters:
name - The logical name of the child to remove from the current list of instantiated children

removeAllChildren

public void removeAllChildren()
Removes all instantiated children from this container. However, the children will still be registered and may be instantiated again by a call to getChild().

getChildNames

public java.lang.String[] getChildNames()
Returns the names of all children registered with this view. This method does not result in the instantiation of any children.
Specified by:
getChildNames in interface ContainerView
Following copied from interface: com.iplanet.jato.view.ContainerView
Returns:
An array of the names of all children contained by this view, or an array of zero length if this container is empty.

getChildNames

public java.lang.String[] getChildNames(java.lang.Class type)

getChildType

public java.lang.Class getChildType(java.lang.String name)
Returns the type of the named child, as previously registered via registerChild(...). This method does not result in the instantiation of the specified child.
Specified by:
getChildType in interface ContainerView
Parameters:
name - The name of the child contained by this view
Returns:
The specified child's class, or null if the child is not registered with this container.

getNumChildren

public int getNumChildren()
Returns the number of registered children
Specified by:
getNumChildren in interface ContainerView
Following copied from interface: com.iplanet.jato.view.ContainerView
Returns:
The number of subviews contained or managed by this container

getChild

public View getChild(java.lang.String name)
Returns the named child view. Calling this method will result in a call to createChild(...) if the child does not currently exist within this container.

The provided child name may also be a qualified view path to the ContainerView.getChild(String name) method, using forward slashes ("/") as delimiters. All components in the path except the last must refer to a ContainerView or a derivative of ContainerView (such as TiledView). Both relative and absolute paths are possible. If a name path begins with a forward slash, the name is assumed to be relative to the root view (the view bean). If the path does not begin with a forward slash, the name is assumed to refer to a child relative to the current container. Two dots ("..") may be used to refer to the container that is the parent of the current container.

In the case of referencing children within a TiledView, developers can also specify the specific tile on which the following child appears. The syntax for this type of reference is .../<tiled view>[<index>]/..., where <index> is the zero-based tiled index.

WARNING: Referencing a specific tile in this manner has side effects. The current tile location will be set to the referenced index; subsequent access to fields in the tiled view that do not specify a tile index will refer to the children of the last-referenced tile. These side effects may also affect tiled view iteration. Therefore, we generally recommend that developers avoid this style of reference when normal tiled view behavior (use of a current location) is sufficient.

Specified by:
getChild in interface ContainerView
Parameters:
name - The name of the child to retrieve
Returns:
The named child instance, or null if the child could not be ensured

childExists

protected boolean childExists(java.lang.String name)
This method can be used to determine if a child has been allocated, and thus whether a value has been assigned to it. This may be useful in avoiding allocation of a field merely to check whether it has been assigned a value.
Parameters:
name - The non-qualified name of the child return True if the child has been allocated

getCommandChildNames

public java.lang.String[] getCommandChildNames()
Returns the names of registered children that are of type Command .
See Also:
CommandField

getQualifiedCommandChildNames

public java.lang.String[] getQualifiedCommandChildNames()
Returns the fully-qualified names of the children that are of type Command.
See Also:
CommandField

removeQualifiedNameIndices

protected java.lang.String removeQualifiedNameIndices(java.lang.String name)
Given a name like this:
	Page1.Repeated1[x].Repeated2[y].Field1
 
we need to remove the indices:
	Page1.Repeated1.Repeated2.Field1
 

beginDisplay

protected final void beginDisplay()
                           throws ModelControlException
Deprecated. Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.

Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.

beginChildDisplay

protected final boolean beginChildDisplay(java.lang.String childName)
                                   throws ModelControlException
Deprecated. Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.

Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.

endChildDisplay

protected final java.lang.String endChildDisplay(java.lang.String childName,
                                                 java.lang.String html)
                                          throws ModelControlException
Deprecated. Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.

Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.

endDisplay

protected final void endDisplay()
Deprecated. Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.

Since JATO/1.2, the signature of this method has changed. This version of the method is marked final to prevent earler implementations from accidentally overriding it.

beginDisplay

public void beginDisplay(DisplayEvent event)
                  throws ModelControlException
Automatically called as notification that the JSP has begun its display processing of this view. This implementation does nothing, leaving any action to derived classes.
Specified by:
beginDisplay in interface ContainerView
Parameters:
event - The DisplayEvent.
Throws:
ModelControlException - Thrown if manipulation of a model fails during display preparation.
Since:
JATO/1.2

beginChildDisplay

public boolean beginChildDisplay(ChildDisplayEvent event)
                          throws ModelControlException
Automatically called as notification that the JSP has begun its display processing on the named child. This method dispatches an event to a method of the following form:
  public boolean begin<child name>Display(ChildDisplayEvent event)
		throws ModelControlException
 
If no such method exists for a given child, the call is ignored and this method returns true.
Specified by:
beginChildDisplay in interface ContainerView
Parameters:
event - The ChildDisplayEvent
Returns:
True if the child should be displayed, false if it should be skipped
Throws:
ModelControlException - Thrown if manipulation of a model fails during display preparation
Since:
JATO/1.2

endChildDisplay

public java.lang.String endChildDisplay(ChildContentDisplayEvent event)
                                 throws ModelControlException
Automatically called as notification that the JSP has completed its display processing on the named child. This method can be used to directly manipulate the HTML generated for this child view before it is sent to the client. This method dispatches an event to a method of the following form:
  public String end<child name>Display(ChildContentDisplayEvent event)
		throws ModelControlException
 
If no such method exists for a given child, the call is ignored and this method returns the provided string.
Specified by:
endChildDisplay in interface ContainerView
Parameters:
event - The ChildContentDisplayEvent.
Returns:
The HTML to be displayed for this child. Generally, if this method returns null, no HTML will be displayed for the child.
Throws:
ModelControlException - Thrown if manipulation of a model fails during display preparation
Since:
JATO/1.2

endDisplay

public void endDisplay(DisplayEvent event)
Automatically called as notification that the JSP has ended its display processing. This implementation does nothing, leaving any action to derived classes.
Specified by:
endDisplay in interface ContainerView
Parameters:
event - The DisplayEvent.
Since:
JATO/1.2

mapRequestParameters

public void mapRequestParameters(javax.servlet.http.HttpServletRequest request)
                          throws ModelControlException
Maps servlet request parameter values into subviews. Normally, this method is used to push values from the request into contained value-based views (DisplayFields) or models. This method typically delegates parameter mapping of child container views to those views by calling this method recursively on those children.

This method is called at the beginning of a servlet request in order to initialize this container and its children with values appropriate to the current request.

Specified by:
mapRequestParameters in interface ContainerView
Parameters:
request - The request object of the current servlet request

mapRequestParameter

protected void mapRequestParameter(DisplayField field,
                                   java.lang.Object[] childValues)
Called by mapRequestParameters() to set the value of a request parameter on a specific display field. Developers can override this method to validate or change the values being set.
Parameters:
field - The target display field child
childValues - The values to be set on the display field child
Since:
JATO/1.2

onValidationException

protected void onValidationException(DisplayField field,
                                     java.lang.Object[] values,
                                     java.lang.RuntimeException e)
Called if the setValues(...) on a child DisplayField throws an exception during request parameter mapping. Normally such an exception would indicate a problem setting the value on the child view's bound model. This method is only called during the servlet's call to mapRequestParameters(...) at the beginning of a submitted request.

The implemtantion of this method in this class throws a ValidationException by default. Developers should override this method and take any appropriate action to set the provided values on the child view.

Parameters:
field - The child view throwing the provided exception
values - The values that the mapRequestParameters(...) method attempted to set on the child view
e - The original exception thrown by the provided child view

getDisplayField

public DisplayField getDisplayField(java.lang.String name)
Returns the named DisplayField child.
Specified by:
getDisplayField in interface ContainerView
Parameters:
name - The name of the DisplayField child. This child must implement the DisplayField interface or this method throws an IllegalArgumentException .
Returns:
The requested DisplayField child. This value will never be null.
See Also:
DisplayField

getDisplayFieldValue

public java.lang.Object getDisplayFieldValue(java.lang.String name)
Returns the value of the named DisplayField child.
Specified by:
getDisplayFieldValue in interface ContainerView
Parameters:
name - The name of the DisplayField child. This child must implement the DisplayField interface or this method throws an IllegalArgumentException .
Returns:
The requested DisplayField child value. This value may be null.
See Also:
DisplayField

setDisplayFieldValue

public void setDisplayFieldValue(java.lang.String name,
                                 java.lang.Object value)
Sets the value of the named DisplayField child.
Specified by:
setDisplayFieldValue in interface ContainerView
Parameters:
name - The name of the DisplayField child. This child must implement the DisplayField interface or this method throws an IllegalArgumentException .
value - The new DisplayField child value
See Also:
DisplayField

getDisplayFieldStringValue

public java.lang.String getDisplayFieldStringValue(java.lang.String name)
Returns the value of the named DisplayField child as a string. The field's original value is converted to the desired type using the methods in com.iplanet.jato.util.TypeConverter.
Parameters:
name - The name of the DisplayField child. This child must implement the DisplayField interface or this method throws an IllegalArgumentException .
Returns:
The requested DisplayField child value. This value may be null.
See Also:
DisplayField, TypeConverter

getDisplayFieldIntValue

public int getDisplayFieldIntValue(java.lang.String name)
Returns the value of the named DisplayField child as an int. The field's original value is converted to the desired type using the methods in com.iplanet.jato.util.TypeConverter.
Parameters:
name - The name of the DisplayField child. This child must implement the DisplayField interface or this method throws an IllegalArgumentException .
Returns:
The requested DisplayField child value. If the original value is null, this method returns zero.
See Also:
DisplayField, TypeConverter

setDisplayFieldValue

public void setDisplayFieldValue(java.lang.String name,
                                 int value)
Sets the value of the named DisplayField child to an int value. The primitive value is converted to the object equivalent before being set.
Parameters:
name - The name of the DisplayField child. This child must implement the DisplayField interface or this method throws an IllegalArgumentException .
value - The new DisplayField child value
See Also:
DisplayField

getDisplayFieldDoubleValue

public double getDisplayFieldDoubleValue(java.lang.String name)
Returns the value of the named DisplayField child as a double. The field's original value is converted to the desired type using the methods in com.iplanet.jato.util.TypeConverter.
Parameters:
name - The name of the DisplayField child. This child must implement the DisplayField interface or this method throws an IllegalArgumentException .
Returns:
The requested DisplayField child value. If the original value is null, this method returns zero.
See Also:
DisplayField, TypeConverter

setDisplayFieldValue

public void setDisplayFieldValue(java.lang.String name,
                                 double value)
Sets the value of the named DisplayField child to a double value. The primitive value is converted to the object equivalent before being set.
Parameters:
name - The name of the DisplayField child. This child must implement the DisplayField interface or this method throws an IllegalArgumentException .
value - The new DisplayField child value
See Also:
DisplayField

getDisplayFieldBooleanValue

public boolean getDisplayFieldBooleanValue(java.lang.String name)
Returns the value of the named DisplayField child as a boolean. The field's original value is converted to the desired type using the methods in com.iplanet.jato.util.TypeConverter.
Parameters:
name - The name of the DisplayField child. This child must implement the DisplayField interface or this method throws an IllegalArgumentException .
Returns:
The requested DisplayField child value. If the original value is null, this method returns false.
See Also:
DisplayField, TypeConverter

setDisplayFieldValue

public void setDisplayFieldValue(java.lang.String name,
                                 boolean value)
Sets the value of the named DisplayField child to a boolean value. The primitive value is converted to the object equivalent before being set.
Parameters:
name - The name of the DisplayField child. This child must implement the DisplayField interface or this method throws an IllegalArgumentException .
value - The new DisplayField child value
See Also:
DisplayField

appMessage

public void appMessage(java.lang.String message)
Adds a message to the application message buffer that appears at the bottom of the rendered HTML page. This method is very useful for debugging purposes, as the output is shown on the page that resulted from the request that generated the messages. This method is short for the following:
	getParentViewBean().getRequestContext().getMessageWriter().println(message);
 
Parameters:
message - The message to be added to the application message buffer

registerDisplayEventHandlers

protected static void registerDisplayEventHandlers(java.lang.Class clazz)
Internal method used to register child field display handler methods. Developers should generally not need to use this method.
Parameters:
clazz - The class to search for display handler methods