com.iplanet.jato.view
Class CommandFieldBase

java.lang.Object
  |
  +--com.iplanet.jato.view.ViewBase
        |
        +--com.iplanet.jato.view.DisplayFieldImpl
              |
              +--com.iplanet.jato.view.CommandFieldBase
All Implemented Interfaces:
CommandField, DisplayField, View
Direct Known Subclasses:
Button, HREF

public abstract class CommandFieldBase
extends DisplayFieldImpl
implements CommandField

Basic implementation of the CommandField interface. This class provides application developers with the ability to associate a Command object with the field via the field's descriptor (and instance of CommandFieldDescriptor). The runtime infrastructure will automatically invoke the associated command whenever the client activates the field. If no command is explicitly associated with the field, a default standard command will be invoked and the request dispatched to a request invocation event handler.

This class also provides the ability to pass values between sources and targets as defined in a list of CommandSourceTargetPairs. The CommandSourceTargetPairs which this object is responsible for supporting are specified in this object's descriptor. The manner in which the source values are mapped accross request boundaries is specific to derived classes.

This class also supports the ability to pass arbitrary name value pairs called "extra values" along with the standard display content of this field. These arbitrary name value pais need not be specified in the descriptor, nor are they formally affiliated with a designated target. These arbitrary extra values are simply included in the generated display content, and thereby made available for retrieval in the subsequent submit as ordinary request parameters.

Version:
JATO/1.2.2 $Id: CommandFieldBase.java,v 1.18 2002/03/16 03:26:39 todd Exp $

Fields inherited from interface com.iplanet.jato.view.View
QUALIFIED_VIEW_NAME_SEPARATOR
 
Constructor Summary
  CommandFieldBase(ContainerView parent, java.lang.String name, java.lang.Object value)
          Construct a display field with the specified properties.
  CommandFieldBase(ContainerView parent, java.lang.String name, java.lang.String boundName, java.lang.Object value)
          Construct a display field with the specified properties.
  CommandFieldBase(View parent, Model model, java.lang.String name, java.lang.Object value)
          Construct a display field with the specified properties
protected CommandFieldBase(View parent, Model model, java.lang.String name, java.lang.String boundName, CommandFieldDescriptor descriptor)
          Construct a display field with the specified properties
  CommandFieldBase(View parent, Model model, java.lang.String name, java.lang.String boundName, java.lang.Object value)
          Construct a display field with the specified properties
  CommandFieldBase(View parent, Model model, java.lang.String name, java.lang.String boundName, java.lang.Object value, CommandFieldDescriptor descriptor)
          Construct a display field with the specified properties
 
Method Summary
 void addExtraValue(java.lang.String name, java.lang.String value)
          Adds a name value pair to this object's extra value map.
 void beforeCommand(CommandEvent event)
          Invoked before the request handling command is invoked as notification that this field was activated.
 void clearExtraValues()
          Removes all name value pairs from this object's extra value map.
 CommandFieldDescriptor getCommandFieldDescriptor()
          Return the descriptor associate with this field.
protected  DisplayField getDisplayField(ContainerView rootView, java.lang.String[] namePath)
          This method takes an arbitrarily deep namePath (e.g.
 java.util.Map getExtraValuesMap()
          Returns a Map object which specifies the Name Value Pairs that this object will automatically append to its generated content.
protected abstract  java.lang.Object getSourceValue(CommandSourceTargetPair pair, int position)
          Returns a source value for a given CommandSourceTargetPair.
 void mapSourceTargetNVPs()
          Deprecated. This method is no longer needed and it currently has no implementation. Developers can safely omit calls to this method.
protected  void mapSourceTargetValues()
          Iterates through the list of CommandSourceTargetPairs and sets each target member's value to its corresponding source value.
 void removeExtraValue(java.lang.String name)
          Removes a name value pair from this object's extra value map.
 void setExtraValuesMap(java.util.Map value)
          Sets this objects extra value map.
 
Methods inherited from class com.iplanet.jato.view.DisplayFieldImpl
getBoundName, getDescriptor, getModel, getValue, getValues, setBoundName, setDescriptor, setModel, setValue, setValue, setValues, setValues, stringValue
 
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.DisplayField
getDescriptor, getValue, getValues, setValue, setValues, stringValue
 
Methods inherited from interface com.iplanet.jato.view.View
getName, getParent, getQualifiedName, setParent
 

Constructor Detail

CommandFieldBase

public CommandFieldBase(ContainerView parent,
                        java.lang.String name,
                        java.lang.Object value)
Construct a display field with the specified properties. The field will be bound to the parent's default model.
Parameters:
parent - The parent view of this object
name - This view's name and model field bound name
value - This DiplayField's initial value.

CommandFieldBase

public CommandFieldBase(ContainerView parent,
                        java.lang.String name,
                        java.lang.String boundName,
                        java.lang.Object value)
Construct a display field with the specified properties. The field will be bound to the parent's default model.
Parameters:
parent - The parent view of this object
name - This view's name
boundName - The name of the model field to which this DisplayField is bound
value - This DiplayField's initial value.

CommandFieldBase

public CommandFieldBase(View parent,
                        Model model,
                        java.lang.String name,
                        java.lang.Object value)
Construct a display field with the specified properties
Parameters:
parent - The parent view of this object
model - The model to which this DisplayField is bound
name - This view's name and model field bound name
value - This DiplayField's initial value.

CommandFieldBase

protected CommandFieldBase(View parent,
                           Model model,
                           java.lang.String name,
                           java.lang.String boundName,
                           CommandFieldDescriptor descriptor)
Construct a display field with the specified properties
Parameters:
parent - The parent view of this object
model - The model to which this DisplayField is bound
name - This view's name.
boundName - The name of the model field to which this DisplayField is bound
value - This DiplayField's initial value.
descriptor - The CommandFieldDescriptor. This value may be null for those instances which do not which do not require the features enabled by the use of CommandFieldDescriptor.

CommandFieldBase

public CommandFieldBase(View parent,
                        Model model,
                        java.lang.String name,
                        java.lang.String boundName,
                        java.lang.Object value)
Construct a display field with the specified properties
Parameters:
parent - The parent view of this object
model - The model to which this DisplayField is bound
name - This view's name.
boundName - The name of the model field to which this DisplayField is bound
value - This DiplayField's initial value.

CommandFieldBase

public CommandFieldBase(View parent,
                        Model model,
                        java.lang.String name,
                        java.lang.String boundName,
                        java.lang.Object value,
                        CommandFieldDescriptor descriptor)
Construct a display field with the specified properties
Parameters:
parent - The parent view of this object
model - The model to which this DisplayField is bound
name - This view's name.
boundName - The name of the model field to which this DisplayField is bound
value - This DiplayField's initial value.
descriptor - The CommandFieldDescriptor. This value may be null for those instances which do not which do not require the features enabled by the use of CommandFieldDescriptor.
Method Detail

getCommandFieldDescriptor

public CommandFieldDescriptor getCommandFieldDescriptor()
Return the descriptor associate with this field. This descriptor should not be confused with the CommandDescriptor class, an instance of which may actually be contained by this descriptor.
Specified by:
getCommandFieldDescriptor in interface CommandField

beforeCommand

public void beforeCommand(CommandEvent event)
Invoked before the request handling command is invoked as notification that this field was activated. Developers creating their own subclasses of the existing CommandField implementations and who override this method should always call the superclass version of this event to ensure consistent behavior.
Specified by:
beforeCommand in interface CommandField

getExtraValuesMap

public java.util.Map getExtraValuesMap()
Returns a Map object which specifies the Name Value Pairs that this object will automatically append to its generated content.
Specified by:
getExtraValuesMap in interface CommandField
Returns:
The Command's extra values map.

setExtraValuesMap

public void setExtraValuesMap(java.util.Map value)
Sets this objects extra value map. The map should contain name value pairs that are intended for automatic inclusion in the HTML generated by this display field. Note - the values included in the Map should either be String objects or objects whose toString() method returns a value appropriate for inclusion as simple string information. The extra values map is not a vehicle for the transmission of arbitrarily complex objects.
Parameters:
value - The map that will be assigned to this object.

addExtraValue

public void addExtraValue(java.lang.String name,
                          java.lang.String value)
Adds a name value pair to this object's extra value map.
Parameters:
name - The name member of the name value pair
value - The value member of the name value pair

removeExtraValue

public void removeExtraValue(java.lang.String name)
Removes a name value pair from this object's extra value map.
Parameters:
name - The name member of the name value pair to be removed

clearExtraValues

public void clearExtraValues()
Removes all name value pairs from this object's extra value map.

mapSourceTargetNVPs

public void mapSourceTargetNVPs()
Deprecated. This method is no longer needed and it currently has no implementation. Developers can safely omit calls to this method.


mapSourceTargetValues

protected void mapSourceTargetValues()
Iterates through the list of CommandSourceTargetPairs and sets each target member's value to its corresponding source value. This method completes the behaviorial cycle of the CommandSourceTargetPairs .

getDisplayField

protected DisplayField getDisplayField(ContainerView rootView,
                                       java.lang.String[] namePath)
This method takes an arbitrarily deep namePath (e.g. "Page1.Repeated2.Foo") which describes the containment relationship of a given display field to its container views, and returns a reference to the display field itself.
Parameters:
rootView - The ConteinerView object which corresponds to the first object in the namePath (i.e. the outermost container view)
namePath - An arbitrarily deep namePath (e.g. "Page1.Repeated2.Foo" ) which describes the containment relationship of a display field to its container views
Returns:
the requested DisplayField

getSourceValue

protected abstract java.lang.Object getSourceValue(CommandSourceTargetPair pair,
                                                   int position)
Returns a source value for a given CommandSourceTargetPair. This method is automatically called as part of the submit cycle.
Parameters:
pair - The CommandSourceTargetPair whose source value is being retrieved
position - The position of the CommandSourceTargetPair within the list of CommandSourceTargetPairs.
Returns:
The value corresponding to the source member of the CommandSourceTargetPair