com.iplanet.jato.view
Class TiledViewBase

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

public abstract class TiledViewBase
extends ContainerViewBase
implements TiledView

A default implementation of TiledView. This implementation provides optimized initialization of child views; child views are not created unless they are referenced. Furthermore, it provides virtualization of children per tile--the same child instance is used to represent that child in each tile. Changes for TiledView/container fix: - ensureChild() would need to be overridden to create special children if one wasn't available for the current row - We'd need to cache a set of special views based on the max display size & display index - We'd need a clearcut way for a special child view to obtain a model instance that was unique to it (a no sharing option) - Do we allow the developer to tell us not to virtualize the field, or do we decide to do this on our own for all container views? - Do we need an event, like TileChangeEvent, that is propagated down to special children so that they can perform certain behavior?

Version:
JATO/1.2.2 $Id: TiledViewBase.java,v 1.23 2002/03/16 03:26:41 todd Exp $

Field Summary
protected static int UNDEFINED_ROW_INDEX
           
 
Fields inherited from class com.iplanet.jato.view.ContainerViewBase
BEGIN_DISPLAY_EVENT_METHOD_PREFIX, BEGIN_DISPLAY_EVENT_METHOD_SUFFIX, END_DISPLAY_EVENT_METHOD_PREFIX, END_DISPLAY_EVENT_METHOD_SUFFIX, eventMethodRegistry, OPTION_ENABLE_QUALIFIELD_CHILD_NAME_LOOKUPS, OPTION_USE_LEGACY_DISPLAY_EVENT_SIGNATURES
 
Fields inherited from interface com.iplanet.jato.view.View
QUALIFIED_VIEW_NAME_SEPARATOR
 
Constructor Summary
protected TiledViewBase()
          Default constructor
  TiledViewBase(View parent, java.lang.String name)
          Creates a ContainerViewBase with a parent and name
 
Method Summary
 void dumpChildValues(java.io.PrintStream out)
          Instructs the view to dump the values of its primary model using the names of its registered children to the specifid writer.
 void dumpChildValues(java.io.PrintWriter out)
          Instructs the view to dump the values of its primary model using the names of its registered children to the specifid writer.
 View getChild(java.lang.String name, int tile)
          Returns the named child in the specified tile.
static java.lang.String[][] getChildValues(javax.servlet.http.HttpServletRequest request, java.lang.String qualifiedParentName, java.lang.String childName)
          This method returns a set of values for a given field within a tiled parent.
 int getDisplayIndex()
          Returns the current display index during display of this container.
 int getMaxDisplayTiles()
          Returns the maximum number of tiles this view will display.
protected  java.lang.String getNonIndexedQualifiedName()
          Returns the default qualified name without a tile index qualfier.
 int getNumTiles()
          Returns the current number of tiles in this view's primary model.
 DatasetModel getPrimaryModel()
          Returns the primary model used by this model's iteration and navigation logic.
 java.lang.String getQualifiedName()
          Returns this view's qualified name.
 int getTileIndex()
          Returns the current location index of the view's primary model.
protected  int incrementDisplayIndex()
          Advances the display index by one.
protected  boolean isTileDisplayable(int index)
          Tests whether the tile specified by the provided index is displayable according to the max display tile limit.
 void mapRequestParameters(javax.servlet.http.HttpServletRequest request)
          Maps servlet request parameter values into subviews.
 boolean nextTile()
          Increments the current tile position to the next available tile position.
protected  boolean nextTileInternal()
          Increments the current tile position to the next available tile position.
protected  void resetDisplayIndex()
          Resets the display index to indicate that no rows have been displayed
 void resetTileIndex()
          Resets the primary model to the "before first" state and resets the display index.
protected  void setDisplayIndex(int value)
          Sets the current display index during display of this container.
 void setMaxDisplayTiles(int value)
          Sets the maximum number of tiles this view will display.
 void setPrimaryModel(DatasetModel value)
          Sets the primary model used by this model's iteration and navigation logic.
 void setPrimaryModel(Model value)
          Deprecated. Use the version of this method that takes a DatasetModel instead. The parameter must be of type DatasetModel or this method will throw a ClassCastException
 void setTileIndex(int value)
          Sets the current location index of the view's primary model.
 
Methods inherited from class com.iplanet.jato.view.ContainerViewBase
appMessage, beginChildDisplay, beginChildDisplay, beginDisplay, beginDisplay, childExists, createChild, createChildInternal, endChildDisplay, endChildDisplay, endDisplay, endDisplay, ensureChild, getChild, getChildNames, getChildNames, getChildType, getCommandChildNames, getDefaultModel, getDisplayField, getDisplayFieldBooleanValue, getDisplayFieldDoubleValue, getDisplayFieldIntValue, getDisplayFieldStringValue, getDisplayFieldValue, getNumChildren, getQualifiedCommandChildNames, mapRequestParameter, onValidationException, registerChild, registerDisplayEventHandlers, removeAllChildren, removeChild, removeQualifiedNameIndices, resetChildren, setDefaultModel, setDisplayFieldValue, setDisplayFieldValue, setDisplayFieldValue, setDisplayFieldValue, unregisterChild
 
Methods inherited from class com.iplanet.jato.view.ViewBase
getName, getParent, getParentViewBean, 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.ContainerView
beginChildDisplay, beginDisplay, endChildDisplay, endDisplay, getChild, getChildNames, getChildType, getDefaultModel, getDisplayField, getDisplayFieldValue, getNumChildren, resetChildren, setDisplayFieldValue
 
Methods inherited from interface com.iplanet.jato.view.View
getName, getParent, setParent
 

Field Detail

UNDEFINED_ROW_INDEX

protected static final int UNDEFINED_ROW_INDEX
Constructor Detail

TiledViewBase

protected TiledViewBase()
Default constructor

TiledViewBase

public TiledViewBase(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

getNonIndexedQualifiedName

protected java.lang.String getNonIndexedQualifiedName()
Returns the default qualified name without a tile index qualfier. This method is equivalent to a regular view's getQualifiedName() method, and is needed because the default behavior for that method must be slightly different for a tiled view.
Returns:
The standard qualified name of this view

getQualifiedName

public java.lang.String getQualifiedName()
Returns this view's qualified name. This name will differ from the typical qualified name by the addition of a tile index to the end of the name. This index allows consumers of this name, such as child views, to embed positional tile information in their names. This capability is crucial to proper request handling behavior of children contained in tiled views.
Specified by:
getQualifiedName in interface View
Overrides:
getQualifiedName in class ViewBase
Returns:
The qualified name of this view, including a tile index qualifier

dumpChildValues

public void dumpChildValues(java.io.PrintStream out)
                     throws ModelControlException
Instructs the view to dump the values of its primary model using the names of its registered children to the specifid writer. This method is for diagnostic purposes only, and does not result in the invocation of any display event logic. After invocation of this method, the tile index will be reset.
Parameters:
out - The PrintStream to which to print the diagnostic information

dumpChildValues

public void dumpChildValues(java.io.PrintWriter out)
                     throws ModelControlException
Instructs the view to dump the values of its primary model using the names of its registered children to the specifid writer. This method is for diagnostic purposes only, and does not result in the invocation of any display event logic. After invocation of this method, the tile index will be reset.
Parameters:
out - The PrintWriter to which to print the diagnostic information

getPrimaryModel

public DatasetModel getPrimaryModel()
Returns the primary model used by this model's iteration and navigation logic. The primary model is the only model used by this logic, regardless of the models bound to child views. Child views must be bound to the primary model to experience the effect of tile iteration. The primary model must be specified before iteration through this view's tiles can occur.
Returns:
This view's primary model, used for iteration through tiles

setPrimaryModel

public void setPrimaryModel(DatasetModel value)
Sets the primary model used by this model's iteration and navigation logic. The primary model is the only model used by this logic, regardless of the models bound to child views. Child views must be bound to the primary model to experience the effect of tile iteration. The primary model must be specified before iteration through this view's tiles can occur.
Parameters:
value - This view's primary model, used for iteration through tiles
See Also:
DatasetModel

setPrimaryModel

public void setPrimaryModel(Model value)
Deprecated. Use the version of this method that takes a DatasetModel instead. The parameter must be of type DatasetModel or this method will throw a ClassCastException


getChild

public View getChild(java.lang.String name,
                     int tile)
              throws ModelControlException
Returns the named child in the specified tile. Because this implementation uses the same child instance for every tile, this method first obtains the name child and then positions the primary model to the specified tile. This may result in a ModelControlException, which will be caught and an IllegalArgumentException thrown in its place.

The named child must be bound to the primary model in order for this method to have the effect of returning the child in the specified tile. Children not bound to the primary model will be returned as usual, though their values will not generally correspond to the current row of the primary model. The primary model's current position will still be set to the specified tile, however.

Specified by:
getChild in interface TiledView
Parameters:
name - The logical name of the child to return
tile - The new tile index. The child will effectively be positioned on this tile if it is bound to the primary model.
Throws:
ModelControlException - Thrown if the positioning of the primary model to the specified tile throws a ModelControlException

getNumTiles

public int getNumTiles()
Returns the current number of tiles in this view's primary model.
Specified by:
getNumTiles in interface TiledView
Returns:
The current number of tiles, or -1 if no primary model has been set for this view

getTileIndex

public int getTileIndex()
                 throws ModelControlException
Returns the current location index of the view's primary model.
Specified by:
getTileIndex in interface TiledView
Returns:
The current tile index, or -1 if no primary model has been set for this view
Throws:
ModelControlException - Thrown if manipulation of the primary model fails during this operation

setTileIndex

public void setTileIndex(int value)
                  throws ModelControlException
Sets the current location index of the view's primary model. This method may throw an exception if the target primary model doesn't support this operation (as is the case with some of the models in the com.iplanet.jato.model.sql package).
Specified by:
setTileIndex in interface TiledView
Parameters:
value - The new tile index
Throws:
ModelControlException - Thrown if manipulation of the primary model fails during this operation

getMaxDisplayTiles

public int getMaxDisplayTiles()
Returns the maximum number of tiles this view will display. This value is independent of the maximum tiles supported by the primary model.
Specified by:
getMaxDisplayTiles in interface TiledView
Returns:
The number of maximum display tiles or -1 if no maximum is set

setMaxDisplayTiles

public void setMaxDisplayTiles(int value)
Sets the maximum number of tiles this view will display. This value is independent of the maximum tiles supported by the primary model.
Specified by:
setMaxDisplayTiles in interface TiledView
Parameters:
value - The number of maximum display tiles or -1 to specify no maximum

getDisplayIndex

public int getDisplayIndex()
Returns the current display index during display of this container. This method can and should be used to determine which tile the view is displaying during child display handling.
Returns:
The current tile display index, or -1 if the view is not currently displaying

setDisplayIndex

protected void setDisplayIndex(int value)
Sets the current display index during display of this container. This method should generally not be used by developers during display handling.
Parameters:
value - The new tile display index

resetDisplayIndex

protected void resetDisplayIndex()
Resets the display index to indicate that no rows have been displayed

incrementDisplayIndex

protected int incrementDisplayIndex()
Advances the display index by one. Used internally to increment the current display index.
Returns:
The new display index

isTileDisplayable

protected boolean isTileDisplayable(int index)
Tests whether the tile specified by the provided index is displayable according to the max display tile limit.
Parameters:
index - The yet-to-be-displayed tile index
Returns:
True if the tile at the provided index can be displayed

resetTileIndex

public void resetTileIndex()
                    throws ModelControlException
Resets the primary model to the "before first" state and resets the display index. After this method is called, this view is ready to be fully displayed. This method should be called after manipulating this view before it is displayed.
Specified by:
resetTileIndex in interface TiledView
Throws:
ModelControlException - Thrown if manipulation of the primary model fails during this operation

nextTile

public boolean nextTile()
                 throws ModelControlException
Increments the current tile position to the next available tile position.
Specified by:
nextTile in interface TiledView
Returns:
True if the tile position was changed, or false if no more tiles were available to display

nextTileInternal

protected final boolean nextTileInternal()
                                  throws ModelControlException
Increments the current tile position to the next available tile position. This method ensures that the standard tile iteration mechanism remains available to subclasses, regardless of overidden versions of nextTile().
Returns:
True if the tile position was changed, or false if no more tiles were available to display

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
Overrides:
mapRequestParameters in class ContainerViewBase
Parameters:
request - The request object of the current servlet request

getChildValues

public static java.lang.String[][] getChildValues(javax.servlet.http.HttpServletRequest request,
                                                  java.lang.String qualifiedParentName,
                                                  java.lang.String childName)
This method returns a set of values for a given field within a tiled parent. Given a set of values like this:
	<repeated>[0].<child>
	<repeated>[1].<child>
	<repeated>[2].<child>
	...

 or

	<repeated1>[0].<repeated2>[0].<child>
	<repeated1>[0].<repeated2>[1].<child>
	<repeated1>[0].<repeated2>[2].<child>
	<repeated1>[1].<repeated2>[0].<child>
 ...
 
we need to find the child values that are appropriate to the supplied parent base name.

Parameters:
request - The current servlet request object
qualifiedParentName - The qualified name of the parent. Used to resolve parameter names relative to only the named parent.
childName - The name of the child for which to obtain values