com.iplanet.jato.view
Interface ContainerView

All Superinterfaces:
View
All Known Subinterfaces:
TiledView, TreeView, ViewBean
All Known Implementing Classes:
ContainerViewBase

public interface ContainerView
extends View

This interface extends the View interface to include explicit support for contained child views, called subviews. A class implementing this interface is able to manage a group of subviews, normally including them as portions of its presentation during rendering. The responsibilities of a container viw may include "pushing" information down to or summarizing information from subviews.

This interface does not specify whether managed child views are directly dependent on their container; however, in general, we prefer subviews that can be combined arbitrarily and which do not require explicit support from their managing container.

Furthermore, this implementation does not specify the way in which child views are added to a container view. This technique is currently left to implementations of this interface. This may change in the future, but has currently been left unspecified in order to allow optimized access to child views as the implementation sees fit. For example, a container may choose to create child views lazily as needed, thereby avoiding creation costs of subviews that are not used in the current request or context (this happens to be the current implementation in this package).

Version:
JATO/1.2.2 $Id: ContainerView.java,v 1.13 2002/03/16 03:26:40 todd Exp $

Fields inherited from interface com.iplanet.jato.view.View
QUALIFIED_VIEW_NAME_SEPARATOR
 
Method Summary
 boolean beginChildDisplay(ChildDisplayEvent event)
          Automatically called as notification that the JSP has begun its display processing on the named child.
 void beginDisplay(DisplayEvent event)
          Automatically called as notification that the JSP has begun its display processing.
 java.lang.String endChildDisplay(ChildContentDisplayEvent event)
          Automatically called as notification that the JSP has ended its display processing on the named child.
 void endDisplay(DisplayEvent event)
          Automatically called as notification that the JSP has ended its display processing.
 View getChild(java.lang.String name)
          Returns a contained child view by name.
 java.lang.String[] getChildNames()
          Return the names of all contained subviews, in an order that is dependent on the container implementation.
 java.lang.Class getChildType(java.lang.String name)
          Returns the class of the specified child by name
 Model getDefaultModel()
          Returns this view's default model.
 DisplayField getDisplayField(java.lang.String name)
          Returns the named DisplayField child.
 java.lang.Object getDisplayFieldValue(java.lang.String name)
          Returns the value of the named DisplayField child.
 int getNumChildren()
          Returns the number of subviews directly contained by this container.
 void mapRequestParameters(javax.servlet.http.HttpServletRequest request)
          Maps servlet request parameter values into subviews.
 void resetChildren()
          Resets all children to a default state in a container-defined way.
 void setDisplayFieldValue(java.lang.String name, java.lang.Object value)
          Sets the value of the named DisplayField child.
 
Methods inherited from interface com.iplanet.jato.view.View
getName, getParent, getQualifiedName, setParent
 

Method Detail

getChildNames

public java.lang.String[] getChildNames()
Return the names of all contained subviews, in an order that is dependent on the container implementation. In general, one can expect that the ordering of child names is significant, though in what way is dependent on the implementation.
Returns:
An array of the names of all children contained by this view, or an array of zero length if this container is empty.

getNumChildren

public int getNumChildren()
Returns the number of subviews directly contained by this container. This number does not reflect the total number of subviews contained by this view and all of its child container views.
Returns:
The number of subviews contained or managed by this container

getChildType

public java.lang.Class getChildType(java.lang.String name)
Returns the class of the specified child by name
Parameters:
name - The logical, non-qualified name of the child
Returns:
The class of the specified child, or null if the child doesn't exist.

getChild

public View getChild(java.lang.String name)
Returns a contained child view by name. This method may throw an IllegalAccessException if the provided name is not the name of a child contained in this container.
Parameters:
name - The logical name of the child view
Returns:
The child specified by name, or null if the child does not exist

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.

getDisplayField

public DisplayField getDisplayField(java.lang.String name)
Returns the named DisplayField child.
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.
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.
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

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.

This method is currently required in this interface to support the intervention needed by the container to prepare its subviews. For example, subviews may have not know that they are contained by another view, and unbeknownst to it, that view's values may be represented in a way that is container dependent. Thus, the container must be able to intervene in the mapping of values to contained views.

Parameters:
request - The request object of the current servlet request
Throws:
ModelControlException - Thrown if manipulation of a model fails during mapping

beginDisplay

public void beginDisplay(DisplayEvent event)
                  throws ModelControlException
Automatically called as notification that the JSP has begun its display processing. This method can be used to execute any auto-executing models associated with this page, prime subviews with data, or take any other action necessary to properly display this page. If this method is overridden by a derived class, it should call the super version of this method after completing its display preparation.
Parameters:
event - The DisplayEvent.
Throws:
ModelControlException - Thrown if manipulation of a model fails during display preparation

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 can be used to prime subviews with data or take any other action necessary to properly display this page. If this method is overridden by a derived class, it should call the super version of this method after completing its display preparation unless it intends to replace the super's default handling.
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

endChildDisplay

public java.lang.String endChildDisplay(ChildContentDisplayEvent event)
                                 throws ModelControlException
Automatically called as notification that the JSP has ended 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.
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

endDisplay

public void endDisplay(DisplayEvent event)
Automatically called as notification that the JSP has ended its display processing. Developers can take advantage of this method to store last-minute session information, record statistics, or perform other tasks that do not affect the rendering of the output.
Parameters:
event - The DisplayEvent.

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 should always return a valid model instance. Note that the default model need not be an actual instance of DefaultModel, although this is usually the case.
Returns:
The default model instance. This instance is always valid and will never be null.