maspack.properties

Class HostList

java.lang.Object

maspack.properties.HostList

All Implemented Interfaces:

java.lang.Iterable<HasProperties>

public class HostList
extends java.lang.Object
implements java.lang.Iterable<HasProperties>

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

Constructors

Constructor and Description
HostList(HasProperties[] hosts)
HostList(int initialSize)
HostList(java.lang.Iterable<? extends HasProperties> hosts)

Method Summary

Modifier and Type	Method and Description
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.
PropTreeCell	commonProperty(java.lang.String propName, boolean allowReadonly) Returns a PropTreeCell with a single child representing a specified property that is common to all hosts.
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()
java.util.Iterator<HasProperties>	iterator()
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)
int	size()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

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()

size

public int size()

set

public void set(HasProperties[] hosts)

set

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

getHosts

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

iterator

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

Specified by:

iterator in interface java.lang.Iterable<HasProperties>

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.

commonProperty

public PropTreeCell commonProperty(java.lang.String propName,
                                   boolean allowReadonly)

Returns a PropTreeCell with a single child representing a specified property that is common to all hosts. If the specified property is not common to all hosts, null is returned.

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()