maspack.properties
Class HostList

java.lang.Object
  extended by maspack.properties.HostList

public class HostList
extends java.lang.Object

Container class for a list of property hosts that can be queried for common values, backed-up, etc.

HostLists are used for setting or querying elements of a property hierarchy across multiple objects, mostly commonly through an EditingProperty. The property hierarchy itself is described by a hierarchy of PropTreeCells, which is separate from the HostList. The HostList contains a list of PropTreeData objects, one per host, each of which forms the root of a host-specific tree mirroring the hierarchy. This mirror hierarchy is formed using PropTreeData objects instead of PropTreeCells in order to save memory and boost efficiency (since there might in practice by a large number of hosts). The purpose of the mirror hierarchy is to (1) provide host-specific information needed to set or query property values on different objects, and (2) to store object-specific backup information.

Typically, the master property hierarchy is described by the PropTreeCells and looks like this:


                          ----------------
                          | PropTreeCell |
   ------------------------- firstChild  |
   |                      |--------------|
   |                      | PropTreeData |
   |                      |              |
   |                      | value = CompositeProperty.class
   |                      |              |
   |                      ----------------
   |
   |  ----------------    ----------------    ----------------
   |  | PropTreeCell |    | PropTreeCell |    | PropTreeCell |    
   +->|         next ---->|         next ---->|         next ---> null
      |--------------|    |--------------|    |--------------|
      | PropTreeData |    | PropTreeData |    | PropTreeData |
      |              |    |              |    |              |
      | value=xxx    |    | value=xxx    |    | value=xxx    |
      |              |    |              |    |              |
      ----------------    ----------------    ----------------
 
while each corresponding mirror hierarchy looks like this:

                          ----------------
                          | PropTreeData |
                          |              |
   -------------------------- subData    |
   |                      |              |
   |                      | value=backup |
   |                      |   host = current composite property value
   |                      ----------------
   |
   |  --------------------------------------------------------
   +->|              0  |               1  |              2  |
      --------------------------------------------------------
              |                   |                   |
              V                   V                   V
      ----------------    ----------------    ----------------
      | PropTreeData |    | PropTreeData |    | PropTreeData |
      |              |    |              |    |              |
      | info         |    | info         |    | info         |
      | value=backup |    | value=backup |    | value=backup |
      |              |    |              |    |              |
      ----------------    ----------------    ----------------
 
Within the master hierarchy, the value at non-leaf nodes is set to CompositeProperty.class to indicate the presence of a composite property; storing real value here makes little sense these vary among objects. Likewise, within the mirror hierarchy, value fields are used to store backup values. Since this is true for composite property nodes as well, local composite property fields (which are needed to set and query nodes below) are stored in the host field.

Since children within the mirror hierarchies are stored in arrays, a path to a particular property within the mirror can be efficiently described by a set of array indices. This set is determined by calling getIndexPath() on the corresponding PropTreeCell within the master hierarchy.


Constructor Summary
HostList(HasProperties[] hosts)
           
HostList(int initialSize)
           
HostList(java.lang.Iterable<? extends HasProperties> hosts)
           
 
Method Summary
 void addHost(HasProperties host)
           
 void addSubHostsIfNecessary(PropTreeCell cell)
           
 void clear()
           
 PropTreeCell commonProperties(PropTreeCell cell, boolean allowReadonly)
           
 PropTreeCell commonProperties(PropTreeCell cell, boolean allowReadonly, java.lang.String[] restricted, java.lang.String[] excluded)
          Returns a PropTreeCell whose children represent the first level of properties common to all hosts, starting from the position in the property tree indicated by cell.
 PropertyInfo[] getAllInfos(PropTreeCell cell)
          Returns an array containing the PropertyInfo structures corresponding to cellfor each host.
 java.lang.Object[] getAllValues(PropTreeCell cell)
          Returns an array containing the values corresponding to cell for each host.
 PropertyMode getCommonMode(PropTreeCell cell)
           
 Range getCommonRange(PropTreeCell cell)
           
 java.lang.Object getCommonValue(PropTreeCell cell)
           
 void getCommonValues(PropTreeCell cell, boolean live)
          Gets the common values of the properties represented by the children of a specified host node.
 HasProperties getHost(int idx)
           
 java.util.Iterator<HasProperties> getHosts()
           
 int numHosts()
           
 void replaceSubHostsIfNecessary(PropTreeCell cell)
           
 void restoreBackupForHost(PropTreeData parentData)
           
 void restoreBackupValues()
           
 void saveBackupForHost(HasProperties host, PropTreeData data, PropTreeCell cell)
          Save backup property values
 void saveBackupValues(PropTreeCell cell)
          Save backup property values corresponding to the children of a particular cell.
 void set(HasProperties[] hosts)
           
 void set(java.lang.Iterable<? extends HasProperties> hosts)
           
 void setMode(PropTreeCell cell, PropertyMode mode)
           
 void setSubHostsFromValue(PropTreeCell cell)
           
 void setValue(PropTreeCell cell, java.lang.Object value)
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HostList

public HostList(int initialSize)

HostList

public HostList(HasProperties[] hosts)

HostList

public HostList(java.lang.Iterable<? extends HasProperties> hosts)
Method Detail

addHost

public void addHost(HasProperties host)

getHost

public HasProperties getHost(int idx)

numHosts

public int numHosts()

set

public void set(HasProperties[] hosts)

set

public void set(java.lang.Iterable<? extends HasProperties> hosts)

getHosts

public java.util.Iterator<HasProperties> getHosts()

getAllValues

public java.lang.Object[] getAllValues(PropTreeCell cell)
Returns an array containing the values corresponding to cell for each host. The corresponding property must exist for each host.


getAllInfos

public PropertyInfo[] getAllInfos(PropTreeCell cell)
Returns an array containing the PropertyInfo structures corresponding to cellfor each host. The corresponding property must exist for each host.


saveBackupValues

public void saveBackupValues(PropTreeCell cell)
Save backup property values corresponding to the children of a particular cell. For every host in this list, we find the data entry that corresponds to cell, and then create for that an array of data entries containing the current values of the child properties. This array is then assigned to the sub-data field of the data entry.


saveBackupForHost

public void saveBackupForHost(HasProperties host,
                              PropTreeData data,
                              PropTreeCell cell)
Save backup property values


restoreBackupValues

public void restoreBackupValues()

restoreBackupForHost

public void restoreBackupForHost(PropTreeData parentData)

commonProperties

public PropTreeCell commonProperties(PropTreeCell cell,
                                     boolean allowReadonly)

commonProperties

public PropTreeCell commonProperties(PropTreeCell cell,
                                     boolean allowReadonly,
                                     java.lang.String[] restricted,
                                     java.lang.String[] excluded)
Returns a PropTreeCell whose children represent the first level of properties common to all hosts, starting from the position in the property tree indicated by cell. If cell is null, then the position is assumed to be the hosts themselves. We can restrict the properties chosen by providing names of restricted and excluded properties.


getCommonValues

public void getCommonValues(PropTreeCell cell,
                            boolean live)
Gets the common values of the properties represented by the children of a specified host node.


setValue

public void setValue(PropTreeCell cell,
                     java.lang.Object value)

getCommonValue

public java.lang.Object getCommonValue(PropTreeCell cell)

getCommonRange

public Range getCommonRange(PropTreeCell cell)

getCommonMode

public PropertyMode getCommonMode(PropTreeCell cell)

setMode

public void setMode(PropTreeCell cell,
                    PropertyMode mode)

addSubHostsIfNecessary

public void addSubHostsIfNecessary(PropTreeCell cell)

setSubHostsFromValue

public void setSubHostsFromValue(PropTreeCell cell)

replaceSubHostsIfNecessary

public void replaceSubHostsIfNecessary(PropTreeCell cell)

clear

public void clear()