com.arsdigita.kernel.ui
Class ACSObjectSelectionModel

java.lang.Object
  com.arsdigita.kernel.ui.ACSObjectSelectionModel

All Implemented Interfaces:

DomainObjectSelectionModel, SingleSelectionModel

Direct Known Subclasses:

ACSObjectSelectionModel, PortletSelectionModel

public class ACSObjectSelectionModel

extends Object

implements DomainObjectSelectionModel

Loads a subclass of an ACSObject from the database. By default, uses a BigDecimal state parameter in order to store and retrieve the item id.

The getSelectedKey(PageState state) method will return the BigDecimal id of the currently selected object. This method will return the id even if the object with this id does not actually exist.

The getSelectedObject(PageState state) method will return the object whose id is getSelectedKey(PageState state). If the object does not actually exist, the method will return null

Thus, it is possible to implement the following pattern:

class MyComponent extends SimpleComponent {
  ACSObjectSelectionModel m_model;

  public MyComponent() {
    super();
    m_model = new ACSObjectSelectionModel("item_id");
  }

  public void register(Page p) {
    super.register(p);
    p.addComponentStateParam(this, p.getStateParameter());
  }

  public void doSomethingUseful(PageState s) {
    if (m_model.isSelected(s)) {
      CusomACSObject obj = (CustomACSObject)m_model.getSelectedObject(state);
      // Do something with obj..
    }
  }
}

Naturally, the ACSObjectSelectionModel could also be passed in as a parameter in the MyComponent constructor. In this case, it should be up to the parent of MyComponent to register the model's state parameter.

Advanced Usage: The ACSObjectSelectionModel is actually just a wrapper for a SingleSelectionModel which maintains the currently selected object's ID as a BigDecimal. By default, a new ParameterSingleSelectionModel is wrapped in this way; however, any SingleSelectionModel may be wrapped. Thus, it becomes possible to use the ACSObjectSelectionModel even if the currently selected ID is not stored in a state parameter.

Persistence Details: The default constructor of ACSObjectSelectionModel will attempt to use the DomainObjectFactory to automatically instantiate the correct Java subclass of ACSObject. However, it is also possible to use an alternate constructor in order to force the ACSObjectSelectionModel to manually instantiate the objects:

ACSObjectSelectionModel model = new ACSObjectSelectionModel("com.arsdigita.cms.Article", "com.arsdigita.cms.Article", "item_id");

In this case, the model will attempt to use reflection to instantiate the correct subclass of ACSObject. In addition, the supplementary constructor makes it possible to create new objects in the database using the createACSObject(BigDecimal) method.

Version:

$Id: //core-platform/dev/src/com/arsdigita/kernel/ui/ACSObjectSelectionModel.java#17 $

Author:

Stanislav Freidin

See Also:

SingleSelectionModel, ParameterSingleSelectionModel

Field Summary

Fields inherited from interface com.arsdigita.kernel.ui.DomainObjectSelectionModel

versionId

Constructor Summary

ACSObjectSelectionModel(BigDecimalParameter parameter)
Construct a new ACSObjectSelectionModel.

ACSObjectSelectionModel(SingleSelectionModel model)
Construct a new ACSObjectSelectionModel.

ACSObjectSelectionModel(String parameterName)
Construct a new ACSObjectSelectionModel.

ACSObjectSelectionModel(String javaClass, String objectType, BigDecimalParameter parameter)
Construct a new ACSObjectSelectionModel

ACSObjectSelectionModel(String javaClass, String objectType, SingleSelectionModel model)
Construct a new ACSObjectSelectionModel

ACSObjectSelectionModel(String javaClass, String objectType, String parameterName)
Construct a new ACSObjectSelectionModel

Method Summary

void	addChangeListener(ChangeListener l) Add a change listener to the model.
void	clearSelection(PageState state) Clear the selection.
ACSObject	createACSObject() A utility function which creates a new object with the given ID.
ACSObject	createACSObject(BigDecimal id) Deprecated. This ignores the ID since ACSObject.setID is a no-op
Class	getJavaClass()
String	getObjectType()
Object	getSelectedKey(PageState state) Return the key that identifies the selected object.
DomainObject	getSelectedObject(PageState state) Return the object which was selected and loaded from the database, using the values supplied in the page state.
SingleSelectionModel	getSingleSelectionModel()
ParameterModel	getStateParameter() Return the state parameter which will be used to keep track of the currently selected key.
boolean	isInitialized(PageState state) Determine if the attempt to load the selected object has been made yet.
boolean	isSelected(PageState state) Return true if there is a selected object.
protected ACSObject	loadACSObject(PageState state, Object key) Load the selected object for the first time.
void	removeChangeListener(ChangeListener l) Remove a change listener from the model.
void	setSelectedKey(PageState state, Object key) Set the ID of the current object.
void	setSelectedObject(PageState state, DomainObject object) Select the specified object.

Methods inherited from class java.lang.Object

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

Constructor Detail

ACSObjectSelectionModel

public ACSObjectSelectionModel(BigDecimalParameter parameter)

Construct a new ACSObjectSelectionModel. This model will produce instances of ACSObject by automatically instantiating the correct Java subclass using the DomainObjectFactory.

Parameters:

parameter - The state parameter which should be used to store the object ID

ACSObjectSelectionModel

public ACSObjectSelectionModel(String parameterName)

Construct a new ACSObjectSelectionModel. This model will produce instances of ACSObject by automatically instantiating the correct Java subclass using the DomainObjectFactory.

Parameters:

parameterName - The name of the state parameter which will be used to store the object ID.

ACSObjectSelectionModel

public ACSObjectSelectionModel(SingleSelectionModel model)

Construct a new ACSObjectSelectionModel. This model will produce instances of ACSObject by automatically instantiating the correct Java subclass using the DomainObjectFactory.

Parameters:

model - The SingleSelectionModel which will supply a BigDecimal ID of the currently selected object

ACSObjectSelectionModel

public ACSObjectSelectionModel(String javaClass,
                               String objectType,
                               String parameterName)

Construct a new ACSObjectSelectionModel

Parameters:

javaClass - The name of the Java class which represents the object. Must be a subclass of ACSObject. In addition, the class must have a constructor with a single OID parameter.

objectType - The name of the persistence metadata object type which represents the ACS object. In practice, will often be the same as the javaClass.

parameterName - The name of the state parameter which will be used to store the object ID.

ACSObjectSelectionModel

public ACSObjectSelectionModel(String javaClass,
                               String objectType,
                               BigDecimalParameter parameter)

Construct a new ACSObjectSelectionModel

Parameters:

javaClass - The name of the Java class which represents the object. Must be a subclass of ACSObject. In addition, the class must have a constructor with a single OID parameter.

objectType - The name of the persistence metadata object type which represents the ACS object. In practice, will often be the same as the javaClass.

parameter - The state parameter which should be used to store the object ID

ACSObjectSelectionModel

public ACSObjectSelectionModel(String javaClass,
                               String objectType,
                               SingleSelectionModel model)

Construct a new ACSObjectSelectionModel

Parameters:

javaClass - The name of the Java class which represents the object. Must be a subclass of ACSObject. In addition, the class must have a constructor with a single OID parameter.

objectType - The name of the persistence metadata object type which represents the ACS object. In practice, will often be the same as the javaClass.

model - The SingleSelectionModel which will supply a BigDecimal ID of the currently selected object

Method Detail

setSelectedKey

public void setSelectedKey(PageState state,
                           Object key)

Set the ID of the current object. The next time getSelectedObject(PageState) is called, the object with the specified ID will be loaded from the database.

Specified by:

setSelectedKey in interface SingleSelectionModel

Parameters:

state - The page state

key - A BigDecimal primary key for the object, or a String representation of a BigDecimal, such as "42".

getSelectedObject

public DomainObject getSelectedObject(PageState state)

Return the object which was selected and loaded from the database, using the values supplied in the page state. May return null if isSelected(state) == false, or if the object was not found.

Specified by:

getSelectedObject in interface DomainObjectSelectionModel

Parameters:

state - The page state

Returns:

The currently selected domain object, or null if no object is selected.

loadACSObject

protected ACSObject loadACSObject(PageState state,
                                  Object key)

Load the selected object for the first time. Child classes may choose to override this method in order to load the object in nonstandard ways. The default implementation merely instantiates an ACSObject whose ID is the passed-in key.

Parameters:

state - the current page state

key - the currently selected key; guaranteed to be non-null

Returns:

the object identified by the specified key

setSelectedObject

public void setSelectedObject(PageState state,
                              DomainObject object)

Select the specified object.

Specified by:

setSelectedObject in interface DomainObjectSelectionModel

Parameters:

state - The page state

object - The content item to set

isInitialized

public boolean isInitialized(PageState state)

Determine if the attempt to load the selected object has been made yet. Child classes may use this method to perform request-local initialization.

Parameters:

state - the page state

Returns:

true if the attempt to load the selected object has already been made, false otherwise

createACSObject

public ACSObject createACSObject(BigDecimal id)
                          throws javax.servlet.ServletException

Deprecated. This ignores the ID since ACSObject.setID is a no-op

A utility function which creates a new object with the given ID. Uses reflection to create the instance of the class supplied in the constructor to this ACSObjectSelectionModel. If no classname was supplied in the constructor, an assertion failure will occur.

Parameters:

id - The id of the new item - this is ignored and the object will have a different id

Returns:

The newly created item

Throws:

javax.servlet.ServletException

createACSObject

public ACSObject createACSObject()
                          throws javax.servlet.ServletException

A utility function which creates a new object with the given ID. Uses reflection to create the instance of the class supplied in the constructor to this ACSObjectSelectionModel. If no classname was supplied in the constructor, an assertion failure will occur.

Returns:

The newly created item

Throws:

javax.servlet.ServletException

getJavaClass

public Class getJavaClass()

Returns:

the Class of the content items which are produced by this model

getObjectType

public String getObjectType()

Returns:

The name of the object type of the content items which are produced by this model

getSingleSelectionModel

public SingleSelectionModel getSingleSelectionModel()

Returns:

the underlying SingleSelectionModel which maintains the ID of the selected object

isSelected

public boolean isSelected(PageState state)

Return true if there is a selected object.

Specified by:

isSelected in interface SingleSelectionModel

Parameters:

state - represents the state of the current request

Returns:

true if there is a selected component.

getSelectedKey

public Object getSelectedKey(PageState state)

Return the key that identifies the selected object.

Specified by:

getSelectedKey in interface SingleSelectionModel

Parameters:

state - the current page state

Returns:

the BigDecimal ID of the currently selected object, or null if no object is selected.

clearSelection

public void clearSelection(PageState state)

Clear the selection.

Specified by:

clearSelection in interface SingleSelectionModel

Parameters:

state - the current page state.

addChangeListener

public void addChangeListener(ChangeListener l)

Add a change listener to the model. The listener's stateChanged is called whenever the selected key changes.

Specified by:

addChangeListener in interface SingleSelectionModel

Parameters:

l - a listener to notify when the selected key changes

removeChangeListener

public void removeChangeListener(ChangeListener l)

Remove a change listener from the model.

Specified by:

removeChangeListener in interface SingleSelectionModel

Parameters:

l - the listener to remove.

getStateParameter

public ParameterModel getStateParameter()

Return the state parameter which will be used to keep track of the currently selected key. Most likely, the parameter will be a BigDecimalParameter.

Specified by:

getStateParameter in interface SingleSelectionModel

Returns:

The state parameter which should be used to keep track of the ID of the currently selected object, or null if the ID is computed in some other way

See Also:

SingleSelectionModel.getStateParameter()