public class MasterDetailsComponent extends ICEObject implements Component
This class provides a data structure that orders key values and DataComponents in a way that is consistent with the Master/Details pattern. Each master is represented by a string and the associated details are represented by a DataComponent. Clients may configure the component, which is configured based on a template, to have any number of instances of the allowed masters. This class manages a collection of "masters" and a collection of "details," one per master, the members of both being instantiated based on their respective templates.
The set of masters that may be created and the set of details that may be modified for instances of those masters are provided to the component by calling the setTemplates() operation. The list of strings that is passed to this operation represents the allowed types of instances of a master and the list of DataComponents should be ordered exactly like the list of master types such that the first allowed master type in the string list corresponds to the first DataComponent in the details list. A null value may not be passed for the list of DataComponents, but a null value is allowed for the list that represents the master. If null is passed for the master, the MasterDetailsComponent will create masters with undefined or null types and the client will be expected to supply a name.
Clients should call addMaster() to add a master to the block and then retrieve the new master from getMaster() using the integer id that was returned from addMaster(). The value of the master can be changed and the details retrieved using one of the getMasters() operations. All masters are created equal, but each instance may have its value set to one of its other allowed values. Changing the value of the master value will change the type of details that are returned by any of the getDetails() operations (which is why they are "locked" together during creation). Details may be retrieved in three ways: by the name, id or reference to the master itself.
The MasterDetailsComponent is an ICEObject and is both uniquely identifiable and persistent to either XML or SQL. It implements the Component interface and can be visited and observed.
The MasterDetailsComponent can be configured with a "header component." The header is a DataComponent that contains Entries whose values apply to the master-details pairs globally. For example, in the ICE MultiLauncher the header contains an Entry to determine whether or not the jobs should be launched sequentially or in parallel. This header is retrieved and set by calling get/setGlobalsComponent and it is referred to interchangeably as "the header" or "the globals" component.
It is possible to generate a unique value for a particular master by calling getUniqueMasterValue() to handle the case where there are degenerate master values. The MasterDetailsComponent will create a unique value equal to the id of the master plus its value.
Internally, the MasterDetailsComponent stores a master and its details in a list of MasterDetailsPairs. This is primarily motivated by the requirements that the masters and details values should be stored next to each other when they are persisted and that storing them in two separate arrays can cause book keeping errors (which is a common procedural anti-pattern).
iComponentVisitor
iComponentListener
Constructor and Description |
---|
MasterDetailsComponent()
The constructor.
|
Modifier and Type | Method and Description |
---|---|
void |
accept(IComponentVisitor visitor)
(non-Javadoc)
|
int |
addMaster()
This operation adds a instantiates a new master.
|
boolean |
canAddRemoveButton()
Returns true if the MasterDetailsComponent's buttons should be enabled.
|
java.lang.Object |
clone()
This operation provides a deep copy of the MasterDetailsComponent.
|
void |
copy(MasterDetailsComponent otherMasterDetailsComponent)
This operation performs a deep copy of the attributes of another
MasterDetailsComponent into the current MasterDetailsComponent.
|
boolean |
deleteMaster(int id)
This operation deletes a master from the MasterDetailsComponent.
|
boolean |
deleteMasterAtIndex(int index)
An operation that deletes a master at an index.
|
boolean |
equals(java.lang.Object otherMasterDetailsComponent)
This operation is used to check equality between the
MasterDetailsComponent and another MasterDetailsComponent.
|
java.util.ArrayList<java.lang.String> |
getAllowedMasterValues()
This operation returns the list of allowed values that may be assigned to
masters when setMasterInstanceValue() is called.
|
DataComponent |
getDetails(int masterId)
This operation returns the details block (a DataComponent) associated
with the master who has the specified id.
|
DataComponent |
getDetailsAtIndex(int index)
An operation that returns the details DataComponent at index in the
masterDetailsPairs list.
|
DataComponent |
getGlobalsComponent()
An operation that gets the globals variable.
|
java.lang.String |
getMasterAtIndex(int index)
An operation that returns the master at index in the masterDetailsPairs
list.
|
java.lang.String |
getMasterValue(int id)
This operation returns the value of the master with the specified id.
|
java.lang.String |
getUniqueMasterValue(int id)
An operation that returns the unique masterDetailsPairId plus Master
String keyed on the unique id (masterDetailsPairId) in the list of
masterDetailsPairs.
|
java.lang.String |
getUniqueMasterValueAtIndex(int index)
An operation that returns the unique masterDetailsPairId plus Master
String keyed on the index in the list of masterDetailsPairs.
|
int |
hashCode()
This operation returns the hashcode value of the MasterDetailsComponent.
|
int |
numberOfMasters()
Returns the number of MasterDetailsPairs in masterDetailsPairs list.
|
void |
setGlobalsComponent(DataComponent globals)
An operation that sets the globals attribute.
|
boolean |
setMasterInstanceValue(int id,
java.lang.String value)
This operation sets the value of an instance of a master with the
specified id.
|
void |
setTemplates(java.util.ArrayList<MasterDetailsPair> pairs)
This operation sets up the templates for the MasterDetailsComponent using
a list of MasterDetailsPairs.
|
void |
setTemplates(java.util.ArrayList<java.lang.String> masterTypeList,
java.util.ArrayList<DataComponent> detailList)
This operation sets the Master/Details template that is required for to
initialize the component.
|
void |
toggleAddRemoveButton(boolean toggle)
Sets the toggle for the add and remove button.
|
void |
update(java.lang.String updatedKey,
java.lang.String newValue)
(non-Javadoc)
|
copy, getDescription, getId, getName, register, setDescription, setId, setName, unregister
getClass, notify, notifyAll, toString, wait, wait, wait
register, unregister
getDescription, getId, getName, setDescription, setId, setName
public void setTemplates(java.util.ArrayList<java.lang.String> masterTypeList, java.util.ArrayList<DataComponent> detailList)
This operation sets the Master/Details template that is required for to initialize the component. It may only be called once per MasterDetailsComponent.
masterTypeList
- The list of strings that should be used as the template for all master instances that will be created in this component.
detailList
- The ordered list of DataComponents that should be used as the base set of details for the masters. The DataComponents in this list should be ordered such that the first DataComponent is the details block for the first master, the second for the second, and so on.
public void setTemplates(java.util.ArrayList<MasterDetailsPair> pairs)
This operation sets up the templates for the MasterDetailsComponent using a list of MasterDetailsPairs. It is provided as an alternative to the other setTemplates() operation for both brevity and better memory management.
pairs
- The list of MasterDetailsPairs that should be used as the template for this component.
public DataComponent getDetails(int masterId)
This operation returns the details block (a DataComponent) associated with the master who has the specified id. If there are two masters with the same id in the component, it only returns the first.
masterId
- The id of the master whose details should be retrieved.
The details block for the master with the specified id.
public int addMaster()
This operation adds a instantiates a new master. The value of the new master is set to the first value in the masterTemplate list. It returns the integer id that the MasterDetailsComponent assigns to that master and the master may be retrieved later by calling getMaster().
The id of the new master instance.
public boolean deleteMaster(int id)
This operation deletes a master from the MasterDetailsComponent. It returns true if the id is valid and it is able to delete the master and its details and it returns false otherwise. Deleting a master will not change the ids of the other masters.
id
- The id of the master that should be deleted.
True if the master was deleted, false otherwise.
public java.lang.String getMasterValue(int id)
This operation returns the value of the master with the specified id.
id
- The id of the master that should be retrieved.
The value of the instance of the master with the given id.
public boolean setMasterInstanceValue(int id, java.lang.String value)
This operation sets the value of an instance of a master with the specified id. If the value is not one of the values in the list returned from getAllowedMasterValues(), this operation returns false and does not set the value.
id
- The id of the master that should be set.
value
- The new value of the master.
True if setting the value was successful, false otherwise.
public java.util.ArrayList<java.lang.String> getAllowedMasterValues()
This operation returns the list of allowed values that may be assigned to masters when setMasterInstanceValue() is called.
The list of values that may be assigned to masters.
public boolean equals(java.lang.Object otherMasterDetailsComponent)
This operation is used to check equality between the MasterDetailsComponent and another MasterDetailsComponent. It returns true if the MasterDetailsComponents are equal and false if they are not.
equals
in interface Identifiable
equals
in class ICEObject
otherMasterDetailsComponent
- The other MasterDetailsComponent to which this component should be compared.
True if the MasterDetailsComponents are equal, false otherwise.
Identifiable.equals(Object otherObject)
public int hashCode()
This operation returns the hashcode value of the MasterDetailsComponent.
hashCode
in interface Identifiable
hashCode
in class ICEObject
The hashcode.
Identifiable.hashCode()
public void copy(MasterDetailsComponent otherMasterDetailsComponent)
This operation performs a deep copy of the attributes of another MasterDetailsComponent into the current MasterDetailsComponent.
otherMasterDetailsComponent
- The other MasterDetailsComponent from which information should be copied.
public java.lang.Object clone()
This operation provides a deep copy of the MasterDetailsComponent.
clone
in interface Identifiable
clone
in class ICEObject
The deep-copy clone of this MasterDetailsComponent.
public int numberOfMasters()
Returns the number of MasterDetailsPairs in masterDetailsPairs list.
Number of masters.
public DataComponent getGlobalsComponent()
An operation that gets the globals variable. Returns null if it has not been set. This should be reviewed by clients if it is not null.
A returned DataComponent globals value.
public void setGlobalsComponent(DataComponent globals)
An operation that sets the globals attribute. If the global's operation has been set and is passed null, globals is set to null.
globals
- The DataComponent global to be set.
public java.lang.String getMasterAtIndex(int index)
An operation that returns the master at index in the masterDetailsPairs list. Returns null if it does not exist.
index
- List index.
A string value in masterDetailsPairs list.
public DataComponent getDetailsAtIndex(int index)
An operation that returns the details DataComponent at index in the masterDetailsPairs list. Returns null if it does not exist.
index
- The index in the list.
The returned DataComponent.
public java.lang.String getUniqueMasterValue(int id)
An operation that returns the unique masterDetailsPairId plus Master String keyed on the unique id (masterDetailsPairId) in the list of masterDetailsPairs. Returns null if it does not exist.
id
- The unique masterDetailsPairId.
The unique master value, equal to 'id + " " + value'.
public java.lang.String getUniqueMasterValueAtIndex(int index)
An operation that returns the unique masterDetailsPairId plus Master String keyed on the index in the list of masterDetailsPairs. Returns null if it does not exist.
index
- The index in the list.
The unique master value, equal to 'id + " " + value'.
public boolean deleteMasterAtIndex(int index)
An operation that deletes a master at an index. Returns true if the operation was successful. False otherwise.
index
- The index to be deleted.
Status of deletion.
public boolean canAddRemoveButton()
Returns true if the MasterDetailsComponent's buttons should be enabled. If false, the buttons should be disabled.
The status
public void toggleAddRemoveButton(boolean toggle)
Sets the toggle for the add and remove button.
toggle
- Toggle for the add or remove button.
public void update(java.lang.String updatedKey, java.lang.String newValue)
ICEObject
update
in interface IUpdateable
update
in class ICEObject
updatedKey
- A unique key that describes the value that to be updated.
newValue
- The updated value of the key.
IUpdateable.update(String updatedKey, String newValue)
public void accept(IComponentVisitor visitor)
accept
in interface Component
visitor
- The visitor
Component.accept(IComponentVisitor visitor)