Field Detail

• EMPTY

  public static final GProp<?>[] EMPTY

  Empty array of properties.

• EMPTY_CNRS

  public static final PropCnr[] EMPTY_CNRS

  Empty array of property containers.

• EMPTY_CLASSES

  public static final java.lang.Class<?>[] EMPTY_CLASSES

  Empty array of classes.

• EXTENDS_FRAMEWORK_ERROR_ID

  public static final java.lang.String EXTENDS_FRAMEWORK_ERROR_ID

  The String ID for errors in the Extends Framework for PropErrorInput.

  See Also:

  Constant Field Values

Constructor Detail

• PropCnr

  public PropCnr()

  Creates a property container without name.

• PropCnr

  public PropCnr​(Atom propertyAtom)

  Creates a property container with the specified name.

  Parameters:

  propertyAtom - the property atom.

• PropCnr

  public PropCnr​(Atom propertyAtom,
                 GProp<?>[] properties)
          throws PropException

  Creates a property container with the specified name and properties.

  Parameters:

  propertyAtom - the property atom.

  properties - the property array value for the property.

  Throws:

  PropException - as structural changes in containers on client is prohibited.

Method Detail

• onPropDispose

  protected void onPropDispose()

  Called when a property is disposed of by delete/remove in a container, or by the dispose method.

  The Property Container clears the structure of unsent communication requests to clear memory.

  This call is done just at the end of the delete/remove routine in the container, without synchronization.

  During this call, whatever components that e.g. the client needs to disposed of is done.

  Subclasses needing to perform some intelligent operations upon deletion should do it by overloading this method and always call the super.onPropDispose() method.

  Overrides:

  onPropDispose in class GProp<GProp<?>[]>

• getPropCnr

  public final PropCnr getPropCnr()

  Gets the property container instance.

  Specified by:

  getPropCnr in interface IPropCnr

  Returns:

  The PropCnr instance.

• usesPropIndex

  public boolean usesPropIndex()

  Checks if index is relevant for this container, e.g. to keep the Z-ordering of components.

  Specified by:

  usesPropIndex in interface IPropCnr

  Returns:

  true if index is used, false for non-index based container.

• enablePropCommunication

  public final boolean enablePropCommunication​(boolean on)

  Enables communication of this container. When communicating mode is turned on, adding and removing, as well as renaming properties causes the affected properties to be queued up in a later transaction update of the remote party. This requires quite some overhead in memory and processing, so this mode is only used when required.

  Note: this method is recursing down in the tree and is NOT synchronized for for performance reasons.

  Specified by:

  enablePropCommunication in interface IPropCnr

  Parameters:

  on - flag to turn enable or disable communication mode.

  Returns:

  true if successful, false otherwise.

• isPropCommunicating

  public final boolean isPropCommunicating()

  Checks if this property container is used with the communication framework.

  Specified by:

  isPropCommunicating in interface IGProp<GProp<?>[]>

  Overrides:

  isPropCommunicating in class GProp<GProp<?>[]>

  Returns:

  true if property is attached to a container that is communicating with a client, false otherwise.

• isPropAddRemoveAllowed

  public final boolean isPropAddRemoveAllowed​(PropMgr propertyManager)

  For property containers that are index-based, the creator of the container is the only one who is allowed to add/remove properties. A PropertyException is otherwise thrown. This method checks if a call to add/remove is allowed.

  Specified by:

  isPropAddRemoveAllowed in interface IPropCnr

  Parameters:

  propertyManager - The property manager.

  Returns:

  true if the property container is not using index-based ordering of its properties, or the property container is created at the same side (i.e. server created and server is calling this function or client created and client is calling this function), false otherwise.

• enablePropHashMap

  public final boolean enablePropHashMap()

  Enables usage of string hash map to property for fast access. This is generally only required when the container contains many properties. This is a once-in-a-lifetime call and can only be done when the container is empty. It is recommended to call this method in the constructor(s) or the properties extending this container class.

  Specified by:

  enablePropHashMap in interface IPropCnr

  Returns:

  true for success (if the name table was allocated and defined), false for failure, i.e. existing properties are already defined.

• usePropHashMap

  public final boolean usePropHashMap()

  Checks if a hash map is used for looking up properties by name/atom for fast access.

  Specified by:

  usePropHashMap in interface IPropCnr

  Returns:

  true if enabled, false if disabled or not yet set.

• isPropExtended

  public boolean isPropExtended​(IGProp<?> property)

  Checks if a property is extended from another or if it is a child to this container.

  Specified by:

  isPropExtended in interface IPropCnr

  Parameters:

  property - The property to verify.

  Returns:

  true if it is extended, false otherwise.

• getValueClasses

  public java.lang.Class<?>[] getValueClasses()

  Gets the list of possible native Java classes that can be used to set a value using setPropertyValue, in order of importance. Note that loss of precision in data if e.g. an Float property accepts a Double. However, the setPropertyValue throws IllegalArgumentException if the range in invalid, e.g. conversion of a Integer to a Byte, and the value is not -127 to 128.

  Specified by:

  getValueClasses in interface IGProp<GProp<?>[]>

  Specified by:

  getValueClasses in class GProp<GProp<?>[]>

  Returns:

  The array of Java classes that can be accepted in the setPropertyValue method. The first type is the "native" or most preferred type. The array is at least one item in length and never null.

• clone

  public PropCnr clone()
                throws java.lang.CloneNotSupportedException

  Creates a clone out of this property. The cloning is overridden by the subclasses in order to handle cloning of its class variables appropriately.

  Cloning is used for "virtualization" of a property tree in the server. Client property classes will therefore throw CloneNotSupportedException.

  Once a tree has been cloned, the change-flag is reset, and the create-flag is set. All listeners are also removed! The new cloned property is an orphan, i.e. has no parent set. All children properties are also (deep) cloned.

  Note that the cloning process is done WITHOUT thread synchronization for performance reasons, thus no modifications should be done to the tree!

  Overrides:

  clone in class GProp<GProp<?>[]>

  Throws:

  java.lang.CloneNotSupportedException - If a subclass doesn't allow cloning, e.g. the client properties.

• onReferenceEvent

  protected void onReferenceEvent​(ResolveReferencesEvent event)

  Called to perform reference resolving. A property should override this method if it needs to perform reference resolving and validation.

  Subclasses override this method and only subclasses extending PropCnr needs to call super.onReferenceEvent(ResolveReferenceEvent event).

  Overrides:

  onReferenceEvent in class GProp<GProp<?>[]>

  Parameters:

  event - The resolve references event.

• virtualize

  protected GProp<?> virtualize​(IAppSessionGyro appGyro,
                                IClientSessionGyro clientGyro,
                                VirtualSpace virtualSpace,
                                PropCnr virtualizedProp)
                         throws java.lang.CloneNotSupportedException,
                                PropException

  Call this method to "virtualize" a property tree. This method is used at runtime in the Server for the application session of virtual instances of VirtualSpace, but also virtual instances of panels, for the individual client session. The VirtualSpace is virtualized once for the application session and is shared for parallel client sessions.

  This method is similar to cloning, but enables references that are already resolved to remain if they point to a shared instance, e.g. the VirtualSpace pointing to its participants in the application property container shared instance, or a panel with references to text IDs, assets, etc.

  It is up to the property class to handle this by overriding this method.

  Overrides:

  virtualize in class GProp<GProp<?>[]>

  Parameters:

  appGyro - The application gyro instance performing the virtualization.

  clientGyro - The client gyro session, can be null if not initialized from the client gyro.

  virtualSpace - The virtualized VirtualSpace.

  virtualizedProp - The property being virtualized.

  Returns:

  The virtualized property.

  Throws:

  java.lang.CloneNotSupportedException - If a subclass doesn't allow cloning, e.g. the client properties.

  PropException - For property errors during the virtualization.

• doVirtualizePropCnr

  protected void doVirtualizePropCnr​(IAppSessionGyro appGyro,
                                     IClientSessionGyro clientGyro,
                                     GProp<?>[] props,
                                     java.lang.String extendsName,
                                     VirtualSpace virtualSpace,
                                     PropCnr virtualizedProp,
                                     PropCnr clonedProp)
                              throws java.lang.CloneNotSupportedException,
                                     PropException

  The rest of the virtualization is done using the correct "this" for inner classes.

  Do not call this method! The method is intended for classes that are virtualized and needs to set-up the AppSessionGyro, ClientSessionGyro and VirtualSpace very early in the virtualizing process.

  Parameters:

  appGyro - The application gyro instance performing the virtualization.

  clientGyro - The client gyro session, can be null if not initialized from the client gyro.

  props - The children properties to virtualize.

  extendsName - The name in extends to virtualize.

  virtualSpace - The virtualized or virtualizing VirtualSpace.

  virtualizedProp - The property being virtualized.

  clonedProp - The property that is cloned to produce this virtualized property.

  Throws:

  java.lang.CloneNotSupportedException - If a subclass doesn't allow cloning, e.g. the client properties.

  PropException - For property errors during the virtualization.

• completeVirtualize

  public final void completeVirtualize​(IAppSessionGyro appGyro,
                                       IClientSessionGyro clientGyro,
                                       VirtualSpace virtualSpace,
                                       PropCnr virtualizedProp)

  Once the property container has been virtualized and added into a virtualized container, a call to this routine should be done. This method should only be called by the framework and not by client code.

  The following is done:

  1. resolves all references,
  2. if there are property errors, this will be output as a Warning event in the log,
  3. notification of virtualization completed.

  Parameters:

  appGyro - The Application Session Gyro causing the virtualization.

  clientGyro - The client gyro session, can be null if not initialized from the client gyro.

  virtualSpace - The virtualized or virtualizing VirtualSpace.

  virtualizedProp - The property being virtualized.

  Throws:

  java.lang.IllegalStateException - If the property container is not virtualized or added into a virtual container.

• prepare

  public final java.util.List<java.lang.Throwable> prepare​(IAppOwner appOwner)
                                                    throws PropException

  Prepares the property tree for application use by initializing and loading classes, etc. This method calls all properties in the tree.

  Parameters:

  appOwner - The application owner.

  Returns:

  A list of errors that occurred but did not cause an abort.

  Throws:

  PropException - For property errors during the application preparation.

• resolveReferences

  public void resolveReferences​(boolean doReCheck)

  Resolves references for this container and its children by sending resolve references events.

  Parameters:

  doReCheck - Recheck flag, avoid true unless really required.

• setCreateRequiredProp

  protected final boolean setCreateRequiredProp()

  Sets the flag indicating property requires a "create transaction" when sent to the other party (server to client or vice versa).

  The property container overrides this method by first calling super.setCreateRequiredProp() then setCreateRequiredProp to all its children.

  Overrides:

  setCreateRequiredProp in class GProp<GProp<?>[]>

  Returns:

  true for change, false for no change.

• initPropCnr

  protected void initPropCnr()

  Method called at the earliest possible stage in the constructor of a container property or it's extending classes, before possible initialization of other properties, etc. The implementation of PropCnr doesn't do anything, so direct subclasses of PropCnr doesn't have to call the super.initPropCnr() method, but lower down the extension change of classes, this is the first piece of code that should be executed.

• addPredefinedProps

  protected void addPredefinedProps()
                             throws PropException

  Adds the predefined properties for this container. This method is called once just after construction of the property container and sometimes population of it.

  The method should add properties to create or get reference to using the maybeAddProp method. When the PropCnr instance is cloned, the method getPredefinedProps() is called in order for the subclass to be able to retrieve the new instances to these properties, if stored in instance variables.

  Subclasses must override this method to do the appropriate initialization, as this method does nothing for the PropCnr class implementation.

  Throws:

  PropException - for property exceptions.

• getPredefinedProps

  protected void getPredefinedProps()

  Gets potential references to predefined properties for this container. This method is called once just after cloning of the property container.

  The method should get reference to using the getProp(...) methods. This allows the subclass to be able to retrieve the new instances to the properties created during addPredefinedProps() if stored in instance variables.

  Subclasses must override this method to do the appropriate initialization, as this method does nothing for the PropCnr class implementation.

• maybeAddProp

  protected <GP extends IGProp<?>> GP maybeAddProp​(GP newlyCreated)
                                            throws PropException

  Adds the newly created predefined property instance or returns the existing one.

  Parameters:

  newlyCreated - The newly created property to add if it is not existing.

  Returns:

  The newlyCreated instance if the property did not exist, otherwise the existing instance. The newlyCreated property is disposed of. The property instance can safely be cast to the requested type (as the one of newlyCreated).

  Throws:

  PropException - If the property cannot be added or there is a property type error.

• __transferChildProps

  public void __transferChildProps​(PropCnr pc)
                            throws java.lang.CloneNotSupportedException,
                                   java.lang.IllegalStateException

  Transfers all properties from another container to this container. This container is cleared of all its properties.

  Note: this method is intended to be used by the framework and not by user code.

  Parameters:

  pc - The property container.

  Throws:

  java.lang.CloneNotSupportedException - If a property fails cloning.

  java.lang.IllegalStateException - If called outside of the Designer.

• validatePropType

  public void validatePropType​(java.lang.Object newValue)
                        throws PropTypeException

  Validates the newValue against the property object type. Subclasses must override this method to perform optional value type validation.

  Note: When this method is called, synchronization is done at the property itself, so no synchronization on the tree should be done.

  Specified by:

  validatePropType in interface IGProp<GProp<?>[]>

  Specified by:

  validatePropType in class GProp<GProp<?>[]>

  Parameters:

  newValue - The new value to set.

  Throws:

  PropTypeException - when the new value isn't of the correct class.

• validatePropValue

  public void validatePropValue​(java.lang.Object newValue)
                         throws PropException

  Validates the value to set. The value must be an array where all the indexes are non-null and no property name is allowed to be duplicated.

  Note: When this method is called, synchronization is done at the property itself, so no synchronization on the tree should be done.

  Specified by:

  validatePropValue in interface IGProp<GProp<?>[]>

  Overrides:

  validatePropValue in class GProp<GProp<?>[]>

  Parameters:

  newValue - The new value to set.

  Throws:

  PropException - when the new value doesn't validate correctly or as structural changes in containers on client is prohibited.

• validateChildPropInValue

  protected void validateChildPropInValue​(GProp<?> child)
                                   throws PropException

  Validates a single child property instance during the call to validatePropValue(Object newValue). This method does nothing and subclasses may use it to validate e.g. the instance type.

  Parameters:

  child - The child property to validate.

  Throws:

  PropException - For validation errors.

• setPropValue

  public final boolean setPropValue​(GProp<?>[] newProps)
                             throws PropException

  Sets a new properties array as the value. If any listener is present and the value has changed compare to the last value, the listener is informed with a PropValueEvent. Note: The event PropCnrEvent is not fired.

  Specified by:

  setPropValue in interface IPropCnr

  Parameters:

  newProps - the new array.

  Returns:

  boolean true for value has changed, false for no change or when at least one value couldn't be set.

  Throws:

  PropException - if read only or structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• setPropValue

  public boolean setPropValue​(Atom atom,
                              java.lang.Object newValue)
                       throws PropException

  Sets the property with the atom name to newValue.

  Specified by:

  setPropValue in interface IPropCnr

  Parameters:

  atom - the property atom.

  newValue - the new value to set for the property

  Returns:

  boolean true for value has changed, false for same value as current value for the property.

  Throws:

  PropException - when the new value doesn't validate correctly or the property with specified name is not found.

• setPropValue

  public boolean setPropValue​(java.lang.String name,
                              java.lang.Object newValue)
                       throws PropException

  Sets the property with the name to newValue.

  Specified by:

  setPropValue in interface IPropCnr

  Parameters:

  name - the name of the properties.

  newValue - the new value to set for the property

  Returns:

  boolean true for value has changed, false for same value as current value for the property.

  Throws:

  PropException - when the new value doesn't validate correctly or the property with specified name is not found.

• setPropValue

  public boolean setPropValue​(int index,
                              java.lang.Object newValue)
                       throws PropException

  Sets the property at index to newValue.

  Specified by:

  setPropValue in interface IPropCnr

  Parameters:

  index - the index in the properties array.

  newValue - the new value to set for the property

  Returns:

  boolean true for value has changed, false for same value as current value for the property.

  Throws:

  PropException - when the new value doesn't validate correctly.

• getPropCount

  public int getPropCount()

  Gets the count of properties in the container.

  Specified by:

  getPropCount in interface IPropCnr

  Returns:

  int the array element count.

• containsProp

  public boolean containsProp​(java.lang.String name)

  Checks for presence of the property in the container.

  Specified by:

  containsProp in interface IPropCnr

  Parameters:

  name - The property name.

  Returns:

  true if property is present in the container, false otherwise.

• containsProp

  public boolean containsProp​(Atom atom)

  Checks for presence of the property in the container.

  Specified by:

  containsProp in interface IPropCnr

  Parameters:

  atom - The property atom.

  Returns:

  true if property is present in the container, false otherwise.

• getProps

  public GProp<?>[] getProps()

  Gets the current value set as a a property array, null for an uninitialized value.

  Specified by:

  getProps in interface IPropCnr

  Returns:

  GProp [] the array of properties in the container or null for an uninitialized array.

• getProps

  public <GP> GP[] getProps​(java.lang.Class<GP> clazz)

  Gets the properties of a certain class, i.e. they must be instance from the specified class, e.g. an interface or a super (or the same) class. Not not use this method "too much" as there are some memory allocation overhead with garbage collection associated.

  Specified by:

  getProps in interface IPropCnr

  Type Parameters:

  GP - The property class requested.

  Parameters:

  clazz - The property classes to retrieve.

  Returns:

  An array of items of the requested type.

• getAllProps

  public final <GP> int getAllProps​(java.lang.Class<GP> clazz,
                                    java.util.List<GP> list)

  Gets the properties of a certain class that are present in the tree below this container, i.e. they must be instance from the specified class, e.g. an interface or a super (or the same) class. Not not use this method "too much" as there are some memory allocation overhead with garbage collection associated.

  Specified by:

  getAllProps in interface IPropCnr

  Type Parameters:

  GP - The property class requested.

  Parameters:

  clazz - The property classes to retrieve.

  list - The list that is filled with the properties found of the specified class.

  Returns:

  The count of properties found.

• getAllProps

  public final int getAllProps​(java.lang.Class<?>[] classes,
                               java.util.List<GProp<?>> list)

  Gets the properties of a certain class that are present in the tree below this container, i.e. they must be instance from the specified class, e.g. an interface or a super (or the same) class. Not not use this method "too much" as there are some memory allocation overhead with garbage collection associated.

  Specified by:

  getAllProps in interface IPropCnr

  Parameters:

  classes - The array of property classes to retrieve.

  list - The list that is filled with the properties found of the specified class.

  Returns:

  The count of properties found.

• getAllProps

  public final <GP> int getAllProps​(java.lang.Class<GP> clazz,
                                    java.util.List<GP> list,
                                    boolean includeErrors)

  Gets the properties of a certain class that are present in the tree below this container, i.e. they must be instance from the specified class, e.g. an interface or a super (or the same) class. Not not use this method "too much" as there are some memory allocation overhead with garbage collection associated.

  Specified by:

  getAllProps in interface IPropCnr

  Type Parameters:

  GP - The property class requested.

  Parameters:

  clazz - The property classes to retrieve.

  list - The list that is filled with the properties found of the specified class.

  includeErrors - Flag to include properties containing errors.

  Returns:

  The count of properties found.

• getAllProps

  public final int getAllProps​(java.lang.Class<?>[] classes,
                               java.util.List<GProp<?>> list,
                               boolean includeErrors)

  Gets the properties of certain classes that are present in the tree below this container, i.e. they must be instance from the specified class, e.g. an interface or a super (or the same) class. Not not use this method "too much" as there are some memory allocation overhead with garbage collection associated.

  Specified by:

  getAllProps in interface IPropCnr

  Parameters:

  classes - The array property classes to retrieve.

  list - The list that is filled with the properties found of the specified class.

  includeErrors - Flag to include properties containing errors.

  Returns:

  The count of properties found.

• getAllProps

  public final <GP> GP[] getAllProps​(java.lang.Class<GP> clazz)

  Gets the properties of a certain class that are present in the tree below this container, i.e. they must be instance from the specified class, e.g. an interface or a super (or the same) class. Not not use this method "too much" as there are some memory allocation overhead with garbage collection associated.

  Specified by:

  getAllProps in interface IPropCnr

  Type Parameters:

  GP - The property class requested.

  Parameters:

  clazz - The property classes to retrieve.

  Returns:

  The array of properties found.

• getAllProps

  public final GProp<?>[] getAllProps​(java.lang.Class<? extends GProp<?>>... classes)

  Gets the properties of certain classes that are present in the tree below this container, i.e. they must be instance from the specified class, e.g. an interface or a super (or the same) class. Not not use this method "too much" as there are some memory allocation overhead with garbage collection associated.

  Specified by:

  getAllProps in interface IPropCnr

  Parameters:

  classes - The list or array of property classes to retrieve.

  Returns:

  The array of properties found.

• getAllProps

  public final <GP> GP[] getAllProps​(java.lang.Class<GP> clazz,
                                     boolean includeErrors)

  Gets the properties of a certain class that are present in the tree below this container, i.e. they must be instance from the specified class, e.g. an interface or a super (or the same) class. Not not use this method "too much" as there are some memory allocation overhead with garbage collection associated.

  Specified by:

  getAllProps in interface IPropCnr

  Type Parameters:

  GP - The property class requested.

  Parameters:

  clazz - The property classes to retrieve.

  includeErrors - Flag to include properties containing errors.

  Returns:

  The array of properties found.

• getAllProps

  public final GProp<?>[] getAllProps​(java.lang.Class<?>[] classes,
                                      boolean includeErrors)

  Gets the properties of certain classes that are present in the tree below this container, i.e. they must be instance from the specified class, e.g. an interface or a super (or the same) class. Not not use this method "too much" as there are some memory allocation overhead with garbage collection associated.

  Specified by:

  getAllProps in interface IPropCnr

  Parameters:

  classes - The array of property classes to retrieve.

  includeErrors - Flag to include properties containing errors.

  Returns:

  The array of properties found.

• getProp

  public final GProp<?> getProp​(Atom[] atomPath)

  Gets the property from a path of atoms.

  Specified by:

  getProp in interface IPropCnr

  Parameters:

  atomPath - Path of atoms, can be null (in which case null is returned).

  Returns:

  The property, or null if not found.

• getProp

  public final GProp<?> getProp​(Atom[] atomPath,
                                int count)

  Gets the property from a path of atoms.

  Specified by:

  getProp in interface IPropCnr

  Parameters:

  atomPath - Path of atoms.

  count - Count of atoms to process.

  Returns:

  The property, or null if not found.

• getProp

  public GProp<?> getProp​(java.lang.String name)

  Gets the property with the specified name. If the atom name for this property is not set, a NullPointerException may occur.

  Specified by:

  getProp in interface IPropCnr

  Parameters:

  name - the name of the property to locate in this property container.

  Returns:

  GProp the property or null for uninitialized container or the property with specified name is not found.

• getProp

  public <GP extends IGProp<?>> GP getProp​(java.lang.String name,
                                           java.lang.Class<GP> clazz)

  Gets the property with the specified name and checking the class instance of the property. An error message is logged if the class is not matching. If the atom name for this property is not set, a NullPointerException may occur.

  Specified by:

  getProp in interface IPropCnr

  Type Parameters:

  GP - The property class requested.

  Parameters:

  name - the name of the property to locate in this property container.

  clazz - the class the property must be or extend, null for no checking.

  Returns:

  GProp the property or null for uninitialized container or the property with specified name is not found, or the class type is not an instance of the specified class.

• getProp

  public <GP extends IGProp<?>> GP getProp​(java.lang.String name,
                                           java.lang.Class<GP> clazz,
                                           boolean logError)

  Gets the property with the specified name and checking the class instance of the property. An error message may be logged if the class is not matching. If the atom name for this property is not set, a NullPointerException may occur.

  Specified by:

  getProp in interface IPropCnr

  Type Parameters:

  GP - The property class requested.

  Parameters:

  name - the name of the property to locate in this property container.

  clazz - the class the property must be or extend, null for no checking.

  logError - logs an error message if the property is of a different type.

  Returns:

  GProp the property or null for uninitialized container or the property with specified name is not found, or the class type is not an instance of the specified class.

• getProp

  public GProp<?> getProp​(Atom atom)

  Gets the property with the atom name.

  Specified by:

  getProp in interface IPropCnr

  Parameters:

  atom - the atom of the property to locate in this property container.

  Returns:

  GProp the property or null for uninitialized container or the property with specified name is not found.

• getProp

  public <GP extends IGProp<?>> GP getProp​(Atom atom,
                                           java.lang.Class<GP> clazz)

  Gets the property with the atom name and checking the class instance of the property. An error message is logged if the class is not matching.

  Specified by:

  getProp in interface IPropCnr

  Type Parameters:

  GP - The property class requested.

  Parameters:

  atom - the atom of the property to locate in this property container.

  clazz - the class the property must be or extend, null for no checking.

  Returns:

  GProp the property or null for uninitialized container or the property with specified name is not found, or the class type is not an instance of the specified class.

• getProp

  public <GP extends IGProp<?>> GP getProp​(Atom atom,
                                           java.lang.Class<GP> clazz,
                                           boolean logError)

  Gets the property with the atom name and checking the class instance of the property.

  Specified by:

  getProp in interface IPropCnr

  Type Parameters:

  GP - The property class requested.

  Parameters:

  atom - the atom of the property to locate in this property container.

  clazz - the class the property must be or extend, null for no checking.

  logError - logs an error message if the property is of a different type.

  Returns:

  GProp the property or null for uninitialized container or the property with specified name is not found, or the class type is not an instance of the specified class.

• getFirstProp

  public GProp<?> getFirstProp​(java.lang.String name)

  Finds the first property with the specified name in the property tree. The search order is a match in the immediate children of this property container. Then all children property containers are searched recursively with the same mechanism as described here.

  Specified by:

  getFirstProp in interface IPropCnr

  Parameters:

  name - The name of the property to locate in the tree.

  Returns:

  GProp the property or null for uninitialized container or the property with specified name is not found.

• getFirstProp

  public GProp<?> getFirstProp​(Atom atom)

  Finds the first property with the specified atom in the property tree. The search order is a match in the immediate children of this property container. Then all children property containers are searched recursively with the same mechanism as described here.

  Specified by:

  getFirstProp in interface IPropCnr

  Parameters:

  atom - The atom of the property to locate in the tree.

  Returns:

  GProp the property or null for uninitialized container or the property with specified atom is not found.

• getProp

  public GProp<?> getProp​(int index)

  Gets the property at requested index.

  Specified by:

  getProp in interface IPropCnr

  Parameters:

  index - the index of the property in the array.

  Returns:

  GProp the property at request index.

  Throws:

  java.lang.IndexOutOfBoundsException - If the index is invalid.

• getProp

  public <GP extends IGProp<?>> GP getProp​(int index,
                                           java.lang.Class<GP> clazz)

  Gets the property at requested index. An error message is logged if the class is not matching.

  Specified by:

  getProp in interface IPropCnr

  Parameters:

  index - the index of the property in the array.

  clazz - the class the property must be or extend, null for no checking.

  Returns:

  GProp the property or null if the class type is not an instance of the specified class.

  Throws:

  java.lang.IndexOutOfBoundsException - If the index is invalid.

• getProp

  public <GP extends IGProp<?>> GP getProp​(int index,
                                           java.lang.Class<GP> clazz,
                                           boolean logError)

  Gets the property at requested index. An error message is logged if the class is not matching depending on the logError flag.

  Specified by:

  getProp in interface IPropCnr

  Parameters:

  index - the index of the property in the array.

  clazz - the class the property must be or extend, null for no checking.

  logError - logs an error message if the property is of a different type.

  Returns:

  GProp the property or null if the class type is not an instance of the specified class.

• getPropCount

  public int getPropCount​(java.lang.String... propNames)

  Gets the count of present direct child properties.

  Parameters:

  propNames - The property names.

  Returns:

  The count of direct child properties found.

• getPropValue

  public java.lang.Object getPropValue​(Atom atom)

  Gets the value of the property by the atom name.

  Specified by:

  getPropValue in interface IPropCnr

  Parameters:

  atom - the atom of the property to locate in the array.

  Returns:

  Object the property or null for uninitialized container or the property with specified name is not found.

• getPropValue

  public final <VALUE> VALUE getPropValue​(Atom atom,
                                          java.lang.Class<VALUE> clazz)

  Gets the value of the property by the atom name. An error is logged if the value is not of specified class.

  Specified by:

  getPropValue in interface IPropCnr

  Type Parameters:

  VALUE - The value class of the property requested.

  Parameters:

  atom - the atom of the property to locate in the array.

  clazz - the class the property value must be or extend, null for no checking.

  Returns:

  Object the property or null for uninitialized container or the property with specified name is not found.

• getPropValue

  public final <VALUE> VALUE getPropValue​(Atom atom,
                                          java.lang.Class<VALUE> clazz,
                                          boolean logError)

  Gets the value of the property by the atom name.

  Specified by:

  getPropValue in interface IPropCnr

  Type Parameters:

  VALUE - The value class of the property requested.

  Parameters:

  atom - the atom of the property to locate in the array.

  clazz - the class the property value must be or extend, null for no checking.

  logError - logs an error message if the property is of a different type.

  Returns:

  Object the property or null for uninitialized container or the property with specified name is not found.

• getPropValue

  public final java.lang.Object getPropValue​(java.lang.String name)

  Gets the value of the property by the name.

  Specified by:

  getPropValue in interface IPropCnr

  Parameters:

  name - the name of the property to locate in the array.

  Returns:

  Object the property or null for uninitialized container or the property with specified name is not found.

• getPropValue

  public final <VALUE> VALUE getPropValue​(java.lang.String name,
                                          java.lang.Class<VALUE> clazz)

  Gets the value of the property by the name. An error is logged if the value is not of specified class.

  Specified by:

  getPropValue in interface IPropCnr

  Type Parameters:

  VALUE - The value class of the property requested.

  Parameters:

  name - the name of the property to locate in the array.

  clazz - the class the property value must be or extend, null for no checking.

  Returns:

  Object the property or null for uninitialized container or the property with specified name is not found.

• getPropValue

  public final <VALUE> VALUE getPropValue​(java.lang.String name,
                                          java.lang.Class<VALUE> clazz,
                                          boolean logError)

  Gets the value of the property by the name.

  Specified by:

  getPropValue in interface IPropCnr

  Type Parameters:

  VALUE - The value class of the property requested.

  Parameters:

  name - the name of the property to locate in the array.

  clazz - the class the property value must be or extend, null for no checking.

  logError - logs an error message if the property is of a different type.

  Returns:

  Object the property or null for uninitialized container or the property with specified name is not found.

• getPropValue

  public final java.lang.Object getPropValue​(int index)

  Gets the value of the property by the index.

  Specified by:

  getPropValue in interface IPropCnr

  Parameters:

  index - the index of the property in the array.

  Returns:

  Object the property or null for uninitialized container or the property with specified name is not found.

• setPropValue

  public <VALUE> boolean setPropValue​(java.lang.String name,
                                      VALUE value,
                                      java.lang.Class<? extends GProp<VALUE>> propClass)

  Sets a property value in the container.

  Specified by:

  setPropValue in interface IPropCnr

  Type Parameters:

  VALUE - The value class of the property requested.

  Parameters:

  name - The name of the property.

  value - The value to set, null to remove the property.

  propClass - The property class.

  Returns:

  true if value was changed, false for no changes.

  Throws:

  java.lang.InternalError - If the property could not be removed or set due to errors.

• setPropValue

  public <VALUE> boolean setPropValue​(Atom atom,
                                      VALUE value,
                                      java.lang.Class<? extends GProp<VALUE>> propClass)

  Sets a property value in the container.

  Specified by:

  setPropValue in interface IPropCnr

  Type Parameters:

  VALUE - The value class of the property requested.

  Parameters:

  atom - The atom name of the property.

  value - The value to set, null to remove the property.

  propClass - The property class.

  Returns:

  true if value was changed, false for no changes.

  Throws:

  java.lang.InternalError - If the property could not be removed or set due to errors.

• getPropIndex

  public final int getPropIndex​(IGProp<?> property)

  Gets the index of this property in this container.

  Specified by:

  getPropIndex in interface IPropCnr

  Parameters:

  property - The property who's index is to be located.

  Returns:

  int, the index of this property, -1 if not found.

• getPropIndex

  public final int getPropIndex​(Atom atom)

  Gets the index of an atom in this container.

  Specified by:

  getPropIndex in interface IPropCnr

  Parameters:

  atom - The atom to look-up.

  Returns:

  int, the index of the atom, -1 if not found.

• createUniqueAtom

  public final Atom createUniqueAtom​(java.lang.String baseName)

  Creates an atom with the base name specified with a unique serial number (starting with one) appended, making this atom unique within this property container. This function is mainly used for indexed property containers.

  Specified by:

  createUniqueAtom in interface IPropCnr

  Parameters:

  baseName - The base name for the property. A numeric value is appended to the name to make it unique.

  Returns:

  Atom, an atom with the baseName requested, appended with a numeric value, making this atom unique within this property container.

• createUniqueAtom

  public final Atom createUniqueAtom​(java.lang.String baseName,
                                     java.lang.String adder)

  Creates an atom with the base name specified with a unique serial number (starting with one) appended, making this atom unique within this property container. This function is mainly used for indexed property containers.

  Parameters:

  baseName - The base name for the property. A numeric value is appended to the name to make it unique.

  adder - String to add before the number if baseName was taken.

  Returns:

  Atom, an atom with the baseName requested, appended with a numeric value, making this atom unique within this property container.

• createUniqueAtom

  public final Atom createUniqueAtom​(Atom name,
                                     java.lang.String first,
                                     java.lang.String next,
                                     java.lang.String next2)

  Creates an atom with the base name specified with a unique serial number (starting with one) appended, making this atom unique within this property container. This function is mainly used for indexed property containers.

  Specified by:

  createUniqueAtom in interface IPropCnr

  Parameters:

  name - The name of the property.

  first - The first appended string, e.g. "Copy of ".

  next - The next appended string, e.g. "Copy ". The next and next2 are used to append string, e.g. "Copy 2 of NNN".

  next2 - The next #2 appended string, e.g. " of ".

  Returns:

  Atom, an atom with the baseName requested, appended with a numeric value, making this atom unique within this property container.

• createCopyOfAtom

  public final Atom createCopyOfAtom​(Atom name)

  Creates a "Copy of NNN" or "Copy 2 of NNN" of an atom. If the atom name is not present, that atom is returned.

  Specified by:

  createCopyOfAtom in interface IPropCnr

  Parameters:

  name - Input name.

  Returns:

  An atom unique in this container, based on the input name, or if the input atom is not present in the container, the same atom is returned.

• setProp

  public final boolean setProp​(IGProp<?> property)
                        throws PropException

  Sets a property to this container. If the property doesn't exist, it is added at the end. If it exists and is of the same instance, the value in the existing property is set from the new one being set or "put". If the property exists but is of another instance, a PropertyException is thrown.

  Specified by:

  setProp in interface IPropCnr

  Parameters:

  property - Property to set.

  Returns:

  true if the property was added or set successfully, false otherwise (also means no change!).

  Throws:

  PropException - when the property has a duplicate property name or if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• setProp

  public final boolean setProp​(IGProp<?> property,
                               IGProp<?> trigger)
                        throws PropException

  Sets a property to this container. If the property doesn't exist, it is added at the end. If it exists and is of the same instance, the value in the existing property is set from the new one being set or "put". If the property exists but is of another instance, a PropertyException is thrown.

  Specified by:

  setProp in interface IPropCnr

  Parameters:

  property - Property to set.

  trigger - The trigger, or null for none.

  Returns:

  true if the property was added or set successfully, false otherwise (also means no change!).

  Throws:

  PropException - when the property has a duplicate property name or if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• setProp2

  public final boolean setProp2​(IGProp<?> property)

  Convenience method to set a property to this container. If the property doesn't exist, it is added at the end. If it exists and is of the same instance, the value in the existing property is set from the new one being set or "put". If the property exists but is of another instance, an InternalError is thrown.

  Specified by:

  setProp2 in interface IPropCnr

  Parameters:

  property - Property to set.

  Returns:

  true if the property was added or set successfully, false otherwise (also means no change!).

• setProp2

  public final boolean setProp2​(IGProp<?> property,
                                IGProp<?> trigger)

  Convenience method to set a property to this container. If the property doesn't exist, it is added at the end. If it exists and is of the same instance, the value in the existing property is set from the new one being set or "put". If the property exists but is of another instance, an InternalError is thrown.

  Specified by:

  setProp2 in interface IPropCnr

  Parameters:

  property - Property to set.

  trigger - The trigger, or null for none.

  Returns:

  true if the property was added or set successfully, false otherwise (also means no change!).

• addProp

  public final boolean addProp​(IGProp<?> property)
                        throws PropException

  Adds a new property to this container at the end.

  Specified by:

  addProp in interface IPropCnr

  Parameters:

  property - the property to insert.

  Returns:

  true, always, because property is added.

  Throws:

  PropException - when the property has a duplicate property name or if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• addProp

  public final boolean addProp​(IGProp<?> property,
                               IGProp<?> trigger)
                        throws PropException

  Adds a new property to this container at the end.

  Specified by:

  addProp in interface IPropCnr

  Parameters:

  property - the property to insert.

  trigger - The trigger, or null for none.

  Returns:

  true, always, because property is added.

  Throws:

  PropException - when the property has a duplicate property name or if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• addProp2

  public final boolean addProp2​(IGProp<?> property)

  Adds a new property to this container at the end.

  This method doesn't throw a PropException, but InternalError. It is intended to be used when the property can be added without exception, e.g. in a new container.

  Specified by:

  addProp2 in interface IPropCnr

  Parameters:

  property - the property to insert.

  Returns:

  true, always, because property is added.

• addProp2

  public final boolean addProp2​(IGProp<?> property,
                                IGProp<?> trigger)

  Adds a new property to this container at the end.

  This method doesn't throw a PropException, but InternalError. It is intended to be used when the property can be added without exception, e.g. in a new container.

  Specified by:

  addProp2 in interface IPropCnr

  Parameters:

  property - the property to insert.

  trigger - The trigger, or null for none.

  Returns:

  true, always, because property is added.

• setProp

  public final boolean setProp​(IGProp<?> property,
                               int index)
                        throws PropException

  Adds a new property to this container at the indicated index. If the property already exists, the property is replaced. If it did not existed before, it is created.

  Specified by:

  setProp in interface IPropCnr

  Parameters:

  property - the property to set.

  index - the index to use if property is inserted.

  Returns:

  true if the update was successful.

  Throws:

  PropException - when the property has a duplicate property name or if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• insertProp

  public final boolean insertProp​(IGProp<?> property,
                                  int index)
                           throws PropException

  Inserts a new property to this container at the specified index.

  Specified by:

  insertProp in interface IPropCnr

  Parameters:

  property - the property to insert.

  index - index where to insert the property.

  Returns:

  true, always, because property is added.

  Throws:

  PropException - when the property has a duplicate property name or if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• insertProp2

  public final boolean insertProp2​(IGProp<?> property,
                                   int index)

  Convenience method to inserts a new property to this container at the specified index.

  Specified by:

  insertProp2 in interface IPropCnr

  Parameters:

  property - the property to insert.

  index - index where to insert the property.

  Returns:

  true, always, because property is added.

  Throws:

  java.lang.InternalError - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• onInsertProp

  protected void onInsertProp​(GProp<?> aProperty,
                              int index,
                              boolean replace,
                              boolean isCloning,
                              PropMgr propMgr,
                              boolean isMoving)
                       throws PropException

  Method called when the internal function insertProp is called to verify that this is allowed. This method is typically used for the runtime virtuals container in the server.

  Parameters:

  aProperty - The property to insert.

  index - Index where to insert the property.

  replace - Flag indicating if the value should be replaced or not.

  isCloning - Flag indicating this property is being cloned.

  propMgr - The property manager for remote change, null for local.

  isMoving - Flag indicating the property is moved.

  Throws:

  PropException - when the property has a duplicate property name or if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp

  public final boolean removeProp​(IGProp<?> property)
                           throws PropException

  Removes a property from this container.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp in interface IPropCnr

  Parameters:

  property - the property to remove.

  Returns:

  true for success, false for failure.

  Throws:

  PropException - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp

  public final boolean removeProp​(IGProp<?> property,
                                  IGProp<?> trigger)
                           throws PropException

  Removes a property from this container.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp in interface IPropCnr

  Parameters:

  property - The property to remove.

  trigger - The trigger property, null for none.

  Returns:

  true for success, false for failure.

  Throws:

  PropException - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp2

  public final boolean removeProp2​(IGProp<?> property)

  Convenience method to remove a property from this container.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp2 in interface IPropCnr

  Parameters:

  property - The property to remove.

  Returns:

  true for success, false for failure.

  Throws:

  java.lang.InternalError - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp2

  public final boolean removeProp2​(IGProp<?> property,
                                   IGProp<?> trigger)

  Convenience method to remove a property from this container.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp2 in interface IPropCnr

  Parameters:

  property - The property to remove.

  trigger - The trigger property, null for none.

  Returns:

  true for success, false for failure.

  Throws:

  java.lang.InternalError - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp

  public final boolean removeProp​(java.lang.String name)
                           throws PropException

  Removes a property from this container with the specified name.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp in interface IPropCnr

  Parameters:

  name - The name of the property to remove.

  Returns:

  true for success, false for failure.

  Throws:

  PropException - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp

  public final boolean removeProp​(java.lang.String name,
                                  IGProp<?> trigger)
                           throws PropException

  Removes a property from this container with the specified name.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp in interface IPropCnr

  Parameters:

  name - The name of the property to remove.

  trigger - The trigger property, null for none.

  Returns:

  true for success, false for failure.

  Throws:

  PropException - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp2

  public final boolean removeProp2​(java.lang.String name)

  Convenience method to remove a property from this container with the specified name.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp2 in interface IPropCnr

  Parameters:

  name - The name of the property to remove.

  Returns:

  true for success, false for failure.

  Throws:

  java.lang.InternalError - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp2

  public final boolean removeProp2​(java.lang.String name,
                                   IGProp<?> trigger)

  Convenience method to remove a property from this container with the specified name.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp2 in interface IPropCnr

  Parameters:

  name - The name of the property to remove.

  trigger - The trigger property, null for none.

  Returns:

  true for success, false for failure.

  Throws:

  java.lang.InternalError - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp

  public final boolean removeProp​(Atom atom)
                           throws PropException

  Removes a property from this container with the specified atom.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp in interface IPropCnr

  Parameters:

  atom - The atom of the property to remove.

  Returns:

  true for success, false for failure.

  Throws:

  PropException - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp

  public final boolean removeProp​(Atom atom,
                                  IGProp<?> trigger)
                           throws PropException

  Removes a property from this container with the specified atom.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp in interface IPropCnr

  Parameters:

  atom - The atom of the property to remove.

  trigger - The trigger property, null for none.

  Returns:

  true for success, false for failure.

  Throws:

  PropException - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp2

  public final boolean removeProp2​(Atom atom)

  Convenience method to remove a property from this container with the specified atom.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp2 in interface IPropCnr

  Parameters:

  atom - The atom of the property to remove.

  Returns:

  true for success, false for failure.

  Throws:

  java.lang.InternalError - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp2

  public final boolean removeProp2​(Atom atom,
                                   IGProp<?> trigger)

  Convenience method to remove a property from this container with the specified atom.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp2 in interface IPropCnr

  Parameters:

  atom - The atom of the property to remove.

  trigger - The trigger property, null for none.

  Returns:

  true for success, false for failure.

  Throws:

  java.lang.InternalError - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp

  public final boolean removeProp​(int index)
                           throws PropException

  Removes a property from this container with the specified index.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp in interface IPropCnr

  Parameters:

  index - the index of the property to remove.

  Returns:

  true for success, false for failure.

  Throws:

  PropException - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeProp2

  public final boolean removeProp2​(int index)

  Removes a property from this container with the specified index.

  Note: removing a property automatically disposes of it, so there is no need to call dispose() on it.

  Specified by:

  removeProp2 in interface IPropCnr

  Parameters:

  index - the index of the property to remove.

  Returns:

  true for success, false for failure.

  Throws:

  java.lang.InternalError - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• onPropRemoved

  protected void onPropRemoved​(GProp<?> prop,
                               PropMgr propMgr,
                               boolean isMoving)

  Called when a property is removed in this container, before the event is fired, but after the property has been removed.

  Parameters:

  prop - The property being removed.

  propMgr - The property manager, null for local.

  isMoving - Moving flag, i.e. the property is moved within containers.

• removeAllProps

  public final boolean removeAllProps()
                               throws PropException

  Removes all properties from this container.

  Note: removing properties automatically disposes of them, so there is no need to call dispose() on them.

  Specified by:

  removeAllProps in interface IPropCnr

  Returns:

  true for changed, false for no change.

  Throws:

  PropException - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• removeAllProps2

  public final boolean removeAllProps2()

  Removes all properties from this container.

  Note: removing properties automatically disposes of them, so there is no need to call dispose() on them.

  Specified by:

  removeAllProps2 in interface IPropCnr

  Returns:

  true for changed, false for no change.

  Throws:

  java.lang.InternalError - if structural changes in containers is prohibited due to creation-ship of container and who is requesting the structural change.

• replaceProps

  public final void replaceProps​(PropCnr cnr)
                          throws java.lang.CloneNotSupportedException,
                                 PropException

  Replaces all properties in this container with the ones from the specified one. All replaced properties are "cloned-in".

  Parameters:

  cnr - The property container.

  Throws:

  java.lang.CloneNotSupportedException - For cloning errors.

  PropException - If the properties could not be replaced.

• getPropIndexes

  public final Atom[] getPropIndexes()

  Gets the indexes of all properties along with the atom names. This array can be used for reordering purposes.

  Specified by:

  getPropIndexes in interface IPropCnr

  Returns:

  The array of atoms.

• reorderProps

  public final boolean reorderProps​(Atom[] atoms)
                             throws PropException

  Reorders the properties according to the array.

  Specified by:

  reorderProps in interface IPropCnr

  Parameters:

  atoms - The array of the properties atoms.

  Returns:

  true for change, false for no change.

  Throws:

  PropException - When the atoms does not correspond to the properties.

• hasSendData

  public boolean hasSendData()

  Checks if any data is present in the property container that needs sending to the remote party.

  Returns:

  The data-present flag.

• appendPropValue

  protected void appendPropValue​(PropMgr propertyManager,
                                 SendTransaction trans,
                                 java.lang.Object value)

  Appends the container property value. If uninitialized, an empty properties array is appended.

  Specified by:

  appendPropValue in class GProp<GProp<?>[]>

  Parameters:

  propertyManager - the property manager instance.

  trans - transaction to append the properties to.

  value - the value to append to the transaction, a reference to the current property value.

• logPropNotFound

  protected void logPropNotFound​(java.lang.String msg)

  Logs a warning message specific to a property updated from remote party that is not found during Remove, Modify or Rename. For certain property containers, it is quite normal. They can override this method and avoid the logging message.

  By default a WARNING message is logged.

  Parameters:

  msg - The message.

• initializeValue

  protected boolean initializeValue​(PropMgr propertyManager,
                                    ReadTransaction trans)
                             throws java.lang.ClassNotFoundException,
                                    java.lang.InstantiationException,
                                    java.lang.IllegalAccessException,
                                    PropException,
                                    java.lang.IllegalArgumentException,
                                    java.lang.reflect.InvocationTargetException,
                                    java.lang.NoSuchMethodException,
                                    java.lang.SecurityException

  Initializes the property value from a transaction.

  Specified by:

  initializeValue in class GProp<GProp<?>[]>

  Parameters:

  propertyManager - the property manager.

  trans - the transaction to initialize the property with.

  Returns:

  true if the value has changed, false otherwise.

  Throws:

  java.lang.ClassNotFoundException - - if the class could not be found.

  java.lang.IllegalAccessException - - if the class or its nullary constructor is not accessible.

  java.lang.InstantiationException - - if this Class represents an abstract class, an interface, an array class, a primitive type, or void; or if the class has no nullary constructor; or if the instantiation fails for some other reason.

  java.lang.ExceptionInInitializerError - - if the initialization provoked by this method fails.

  java.lang.SecurityException - - if a security manager, s, is present and any of the following conditions is met:

  • invocation of s.checkMemberAccess(this, Member.PUBLIC) denies creation of new instances of this class,
  • the caller's class loader is not the same as or an ancestor of the class loader for the current class and invocation of s.checkPackageAccess() denies access to the package of this class.

  PropException - - if the property cannot be initialized, because of erroneous data.

  java.lang.NoSuchMethodException

  java.lang.reflect.InvocationTargetException

  java.lang.IllegalArgumentException

• initializeProp

  public void initializeProp​(org.w3c.dom.Element element)
                      throws PropException

  Called to initialize the property from an Element. The property should initialize itself from attributes and nodes with appropriate information.

  This call does nothing in this class and should be overridden by subclasses wishing for special processing.

  Overrides:

  initializeProp in class GProp<GProp<?>[]>

  Parameters:

  element - The Element.

  Throws:

  PropException - when the initialization fails.

• onPropTreeInitialized

  public void onPropTreeInitialized()
                             throws java.io.IOException,
                                    PropException

  Called when the property has initialized from the Element when streamed from an XML file, has had all (if any) children elements and nodes added as properties and that the property has been added into it's parent.

  The PropertyContainer calls all its children with this method in order to inform the tree.

  The ExtendablePropertyContainer overrides this method to load all extended containers.

  Specified by:

  onPropTreeInitialized in interface IGProp<GProp<?>[]>

  Overrides:

  onPropTreeInitialized in class GProp<GProp<?>[]>

  Throws:

  java.io.IOException - For file errors.

  PropException - When there is an initialization problem.

• initializeElement

  protected void initializeElement​(org.w3c.dom.Element element)

  Called when the XML file for the property tree is serialized from properties. The property should fill attributes and nodes with appropriate information.

  This call does nothing in this class and should be overridden by subclasses wishing for special processing.

  Overrides:

  initializeElement in class GProp<GProp<?>[]>

  Parameters:

  element - The Element to initialize.

• shouldCreateProps

  protected boolean shouldCreateProps​(org.w3c.dom.Element element)

  Checks if a child Element should be created as properties or if it should be skipped. Override this method (and call super.shouldCreateProps(element)) if the container creates other child elements.

  Parameters:

  element - The element in question.

  Returns:

  true to create properties out of it, false to ignore the element.

• shouldSerializeToXML

  protected boolean shouldSerializeToXML​(int programType,
                                         GProp<?> childProp)

  Method used to check for child property serialization to XML. Override this method and return false to avoid writing the child property to XML. The default is to write all properties.

  Parameters:

  programType - From PropFactory.getProgramType(): 0=PropFactory.CLIENT, 1=PropFactory.SERVER or 2=PropFactory.EDITOR.

  childProp - The child property.

  Returns:

  true (default if not VOLATILE) to save to XML, false to avoid writing the property to XML.

• convertLoadedProp

  protected GProp<?> convertLoadedProp​(GProp<?> childProp)

  Enables conversion or omission of a property loaded from XML.

  This method is typically used to process changes of e.g. property types, e.g. from IntProp to NumberProp, in case of a change of property definitions.

  Parameters:

  childProp - The child property that is about to be added.

  Returns:

  The property to add, null to omit it. The default processing is to return the same property, i.e. childProp.

• toElementString

  public java.lang.String toElementString​(java.lang.Object value)

  Called from the initializeProperty(Element element) method once the element String is retrieved from the first child node of type "#text". Override this method to provide the appropriate Object to String conversion.

  The default implementation returns the Object value.toString() return code.

  Specified by:

  toElementString in interface IGProp<GProp<?>[]>

  Overrides:

  toElementString in class GProp<GProp<?>[]>

  Parameters:

  value - the value in the object to convert to a string.

  Returns:

  the string corresponding to the object value.

• equalsTree

  protected java.lang.Object equalsTree​(PropCnr pc2,
                                        int how)

  Checks for equality in the whole container structure.

  NOTE: This method should not be overridden except in extreme situations, e.g. for MememtoPropCnr.

  Overrides:

  equalsTree in class GProp<GProp<?>[]>

  Parameters:

  pc2 - The property value to compare with.

  how - Flags EQC_* values for equal checking.

  Returns:

  Both atom and value are equal on all levels.

• equalsTree

  protected java.lang.Object equalsTree​(PropCnr pc2,
                                        java.lang.Class<? extends IGProp<?>> arrayItemClass,
                                        int how)

  Checks for equality in the whole container structure.

  NOTE: This method should not be overridden except in extreme situations, e.g. for MememtoPropCnr.

  Parameters:

  pc2 - The property value to compare with.

  how - Flags EQC_* values for equal checking.

  Returns:

  Both atom and value are equal on all levels.

• doPropEqualsArrayValues

  protected boolean doPropEqualsArrayValues()

  Method checking if the property container should do a normal comparison with its contents based on extends framework, atoms, errors, etc.

  Returns:

  false (default) to perform normal checking, true to compare property values as a plain array container instead.

• getPropValue0

  protected java.lang.Object getPropValue0​(java.lang.Object value,
                                           int index)
                                    throws java.lang.Exception

  Gets the property value in another class form than the "native" one. This method tries conversion of a "native" property value into another class type. This method is used when filling in a POJO variable (Plain Old Java Object Field) from a "native" property value.

  Specified by:

  getPropValue0 in class GProp<GProp<?>[]>

  Parameters:

  value - The property value.

  index - The index in the Class array returned by getValueClasses().

  Returns:

  The property value in the requested class, after conversion.

  Throws:

  java.lang.IllegalArgumentException - Invalid index, this should never happen though.

  java.lang.Exception - Other exceptions that could occur.

• toNativeValue0

  protected java.lang.Object toNativeValue0​(java.lang.Object value,
                                            int index)
                                     throws java.lang.Exception

  Tries conversion of possibly accepted properties values using the setPropertyValue method into the most preferred property value type. If the input value already is of the preferred type, the same object is returned.

  Specified by:

  toNativeValue0 in class GProp<GProp<?>[]>

  Parameters:

  value - The input value to convert to native value.

  index - The index in the array returned by getValueClasses(), or -1 if not found.

  Returns:

  The converted input value in the preferred property value object type.

  Throws:

  java.lang.IllegalArgumentException - Invalid index, this should never happen though.

  java.lang.Exception - For conversion exceptions.

• paramString

  protected java.lang.String paramString()

  Returns the parameter string representing the state of this event. This string is useful for debugging. Subclasses adds extra information to the string by preceding it with a comma followed by the extra information.

  Overrides:

  paramString in class GProp<GProp<?>[]>

  Returns:

  the parameter string of this event.

• list

  public void list​(java.io.PrintStream out,
                   int indent)

  Prints a listing of this container to the specified output stream. The listing starts at the specified indentation.

  Specified by:

  list in interface IGProp<GProp<?>[]>

  Overrides:

  list in class GProp<GProp<?>[]>

  Parameters:

  out - a print stream.

  indent - the number of spaces to indent.

• list

  public void list​(java.io.PrintWriter out,
                   int indent)

  Prints out a list, starting at the specified indentation, to the specified print writer.

  Specified by:

  list in interface IGProp<GProp<?>[]>

  Overrides:

  list in class GProp<GProp<?>[]>

  Parameters:

  out - a print writer.

  indent - the number of spaces to indent.

• getString

  public java.lang.String getString​(java.lang.String name)

  Gets a string property from this property container.

  Specified by:

  getString in interface IPropCnr

  Parameters:

  name - The name of the property.

  Returns:

  String, the requested property string or null if not found or not initialized.

• getString

  public final java.lang.String getString​(java.lang.String name,
                                          java.lang.String defaultValue)

  Gets a string property from this property container.

  Specified by:

  getString in interface IPropCnr

  Parameters:

  name - The name of the property.

  defaultValue - The default value if not found (can be null).

  Returns:

  String, the requested property string or the default if not found or not initialized.

• getString

  public final java.lang.String getString​(Atom atom)

  Gets a string property from this property container.

  Specified by:

  getString in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  Returns:

  String, the requested property string or null if not found or not initialized.

• getString

  public final java.lang.String getString​(Atom atom,
                                          java.lang.String defaultValue)

  Gets a string property from this property container.

  Specified by:

  getString in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  defaultValue - The default value if not found (can be null) .

  Returns:

  String, the requested property string or null if not found or not initialized.

• setString

  public final boolean setString​(Atom atom,
                                 java.lang.String value)

  Sets a string property with the specified atom to the value in this property container.

  If the string property doesn't exist, it is created and added to this property container.

  If the property cannot be set, an warning message is logged.

  Specified by:

  setString in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The string value.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setString

  public final boolean setString​(java.lang.String name,
                                 java.lang.String value)

  Sets a string property with the specified name to the value in this property container.

  If the string property doesn't exist, it is created and added to this property container.

  If the property cannot be set, an warning message is logged.

  Specified by:

  setString in interface IPropCnr

  Parameters:

  name - The name of the property.

  value - The string value.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setString

  public final boolean setString​(Atom atom,
                                 java.lang.String value,
                                 boolean logError)

  Sets a string property with the specified atom to the value in this property container.

  If the string property doesn't exist, it is created and added to this property container.

  Specified by:

  setString in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The string value.

  logError - Flag indicating if a warning event should be logged for failures.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setString

  public final boolean setString​(Atom atom,
                                 java.lang.String value,
                                 boolean logError,
                                 IGProp<?> trigger)

  Sets a string property with the specified atom to the value in this property container.

  If the string property doesn't exist, it is created and added to this property container.

  Specified by:

  setString in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The string value.

  logError - Flag indicating if a warning event should be logged for failures.

  trigger - The trigger property, null for none.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• getInt

  public final int getInt​(java.lang.String name)

  Gets an integer property from this property container.

  Specified by:

  getInt in interface IPropCnr

  Parameters:

  name - The name of the property.

  Returns:

  int, the requested property integer or zero if not found or not initialized.

• getInt

  public final int getInt​(java.lang.String name,
                          int defaultValue)

  Gets an integer property from this property container.

  Specified by:

  getInt in interface IPropCnr

  Parameters:

  name - The name of the property.

  defaultValue - The default value to return when the property is not found or initialized.

  Returns:

  int, the requested property integer or defaultValue if not found or not initialized.

• getInt

  public final int getInt​(Atom atom)

  Gets an integer property from this property container.

  Specified by:

  getInt in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  Returns:

  int, the requested property integer or zero if not found or not initialized.

• getInt

  public final int getInt​(Atom atom,
                          int defaultValue)

  Gets an integer property from this property container.

  Specified by:

  getInt in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  defaultValue - The default value to return when the property is not found or initialized.

  Returns:

  int, the requested property integer or defaultValue if not found or not initialized.

• setInt

  public final boolean setInt​(Atom atom,
                              int value)

  Sets an integer property with the specified atom to the value in this property container.

  If the integer property doesn't exist, it is created and added to this property container.

  If the property cannot be set, an warning message is logged.

  Specified by:

  setInt in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The integer value.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setInt

  public final boolean setInt​(java.lang.String name,
                              int value)

  Sets an integer property with the specified name to the value in this property container.

  If the integer property doesn't exist, it is created and added to this property container.

  If the property cannot be set, an warning message is logged.

  Specified by:

  setInt in interface IPropCnr

  Parameters:

  name - The name of the property.

  value - The integer value.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setInt

  public final boolean setInt​(Atom atom,
                              int value,
                              boolean logError)

  Sets an integer property with the specified atom to the value in this property container.

  If the integer property doesn't exist, it is created and added to this property container.

  Specified by:

  setInt in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The integer value.

  logError - Flag indicating if a warning event should be logged for failures.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• getLong

  public final long getLong​(java.lang.String name)

  Gets a long property from this property container.

  Specified by:

  getLong in interface IPropCnr

  Parameters:

  name - The name of the property.

  Returns:

  long, the requested property long or zero if not found or not initialized.

• getLong

  public final long getLong​(java.lang.String name,
                            long defaultValue)

  Gets a long property from this property container.

  Specified by:

  getLong in interface IPropCnr

  Parameters:

  name - The name of the property.

  defaultValue - The default value to return when the property is not found or initialized.

  Returns:

  long, the requested property long or defaultValue if not found or not initialized.

• getLong

  public final long getLong​(Atom atom)

  Gets a long property from this property container.

  Specified by:

  getLong in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  Returns:

  long, the requested property long or zero if not found or not initialized.

• getLong

  public final long getLong​(Atom atom,
                            long defaultValue)

  Gets a long property from this property container.

  Specified by:

  getLong in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  defaultValue - The default value to return when the property is not found or initialized.

  Returns:

  long, the requested property long or defaultValue if not found or not initialized.

• setLong

  public final boolean setLong​(Atom atom,
                               long value)

  Sets a long property with the specified atom to the value in this property container.

  If the long property doesn't exist, it is created and added to this property container.

  If the property cannot be set, an warning message is logged.

  Specified by:

  setLong in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The long value.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setLong

  public final boolean setLong​(java.lang.String name,
                               long value)

  Sets a long property with the specified name to the value in this property container.

  If the long property doesn't exist, it is created and added to this property container.

  If the property cannot be set, an warning message is logged.

  Specified by:

  setLong in interface IPropCnr

  Parameters:

  name - The name of the property.

  value - The long value.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setLong

  public final boolean setLong​(Atom atom,
                               long value,
                               boolean logError)

  Sets an integer property with the specified atom to the value in this property container.

  If the integer property doesn't exist, it is created and added to this property container.

  Specified by:

  setLong in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The integer value.

  logError - Flag indicating if a warning event should be logged for failures.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setLong

  public final boolean setLong​(Atom atom,
                               long value,
                               boolean logError,
                               IGProp<?> trigger)

  Sets an integer property with the specified atom to the value in this property container.

  If the integer property doesn't exist, it is created and added to this property container.

  Specified by:

  setLong in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The integer value.

  logError - Flag indicating if a warning event should be logged for failures.

  trigger - The trigger property, or null for none.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• getNumber

  public final double getNumber​(java.lang.String name)

  Gets a Number property from this property container.

  Specified by:

  getNumber in interface IPropCnr

  Parameters:

  name - The name of the property.

  Returns:

  double, the requested property number or zero if not found or not initialized.

• getNumber

  public final double getNumber​(java.lang.String name,
                                double defaultValue)

  Gets a Number property from this property container.

  Specified by:

  getNumber in interface IPropCnr

  Parameters:

  name - The name of the property.

  defaultValue - The default value to return when the property is not found or initialized.

  Returns:

  double, the requested property number or defaultValue if not found or not initialized.

• getNumber

  public final double getNumber​(Atom atom)

  Gets a Number property from this property container.

  Specified by:

  getNumber in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  Returns:

  double, the requested property number or zero if not found or not initialized.

• getNumber

  public final double getNumber​(Atom atom,
                                double defaultValue)

  Gets a Number property from this property container.

  Specified by:

  getNumber in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  defaultValue - The default value to return when the property is not found or initialized.

  Returns:

  double, the requested property number or defaultValue if not found or not initialized.

• setNumber

  public final boolean setNumber​(Atom atom,
                                 double value)

  Sets a Number property with the specified atom to the value in this property container.

  If the Number property doesn't exist, it is created and added to this property container.

  If the property cannot be set, an warning message is logged.

  Specified by:

  setNumber in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The Number value.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setNumber

  public final boolean setNumber​(java.lang.String name,
                                 double value)

  Sets an integer property with the specified name to the value in this property container.

  If the Number property doesn't exist, it is created and added to this property container.

  If the property cannot be set, an warning message is logged.

  Specified by:

  setNumber in interface IPropCnr

  Parameters:

  name - The name of the property.

  value - The Number value.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setNumber

  public final boolean setNumber​(Atom atom,
                                 double value,
                                 boolean logError)

  Sets an integer property with the specified atom to the value in this property container.

  If the Number property doesn't exist, it is created and added to this property container.

  Specified by:

  setNumber in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The Number value.

  logError - Flag indicating if a warning event should be logged for failures.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setNumber

  public final boolean setNumber​(Atom atom,
                                 double value,
                                 boolean logError,
                                 IGProp<?> trigger)

  Sets an integer property with the specified atom to the value in this property container.

  If the Number property doesn't exist, it is created and added to this property container.

  Specified by:

  setNumber in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The Number value.

  logError - Flag indicating if a warning event should be logged for failures.

  trigger - The trigger property, null for none.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• getBool

  public final boolean getBool​(java.lang.String name)

  Gets a boolean property from this property container.

  Specified by:

  getBool in interface IPropCnr

  Parameters:

  name - The name of the property.

  Returns:

  boolean, the requested property boolean or defaultValue if not found or not initialized.

• getBool

  public final boolean getBool​(java.lang.String name,
                               boolean defaultValue)

  Gets a boolean property from this property container.

  Specified by:

  getBool in interface IPropCnr

  Parameters:

  name - The name of the property.

  defaultValue - The default value to return when the property is not found or initialized.

  Returns:

  boolean, the requested property boolean or defaultValue if not found or not initialized.

• getBool

  public final boolean getBool​(Atom atom)

  Gets a boolean property from this property container.

  Specified by:

  getBool in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  Returns:

  boolean, the requested property boolean or defaultValue if not found or not initialized.

• getBool

  public final boolean getBool​(Atom atom,
                               boolean defaultValue)

  Gets a boolean property from this property container.

  Specified by:

  getBool in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  defaultValue - The default value to return when the property is not found or initialized.

  Returns:

  boolean, the requested property boolean or defaultValue if not found or not initialized.

• setBool

  public final boolean setBool​(Atom atom,
                               boolean value)

  Sets a boolean property with the specified atom to the value in this property container.

  If the boolean property doesn't exist, it is created and added to this property container.

  If the property cannot be set, an warning message is logged.

  Specified by:

  setBool in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The boolean value.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setBool

  public final boolean setBool​(java.lang.String name,
                               boolean value)

  Sets a boolean property with the specified name to the value in this property container.

  If the boolean property doesn't exist, it is created and added to this property container.

  If the property cannot be set, an warning message is logged.

  Specified by:

  setBool in interface IPropCnr

  Parameters:

  name - The name of the property.

  value - The boolean value.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setBool

  public final boolean setBool​(Atom atom,
                               boolean value,
                               boolean logError)

  Sets a boolean property with the specified atom to the value in this property container.

  If the boolean property doesn't exist, it is created and added to this property container.

  Specified by:

  setBool in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The boolean value.

  logError - Flag indicating if a warning event should be logged for failures.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• setBool

  public final boolean setBool​(Atom atom,
                               boolean value,
                               boolean logError,
                               IGProp<?> trigger)

  Sets a boolean property with the specified atom to the value in this property container.

  If the boolean property doesn't exist, it is created and added to this property container.

  Specified by:

  setBool in interface IPropCnr

  Parameters:

  atom - The atom of the property.

  value - The boolean value.

  logError - Flag indicating if a warning event should be logged for failures.

  trigger - The trigger property or null for none.

  Returns:

  true when this property container has been changed, false otherwise (or for error).

• getFocusEngine

  public IFocusEngine getFocusEngine​(IFocusComp comp)

  Locates the focus engine instance for the specified component.

  Specified by:

  getFocusEngine in interface IPropCnr

  Parameters:

  comp - The component requesting the focus engine.

  Returns:

  The focus engine instance, or null if not found.

• canRequestFocus

  public java.lang.String canRequestFocus​(boolean ignoreVisibleFlag,
                                          boolean ignoreEnabledFlag)

  Returns if this component can receive focus. Focus capable components may override to return null for success, or other error message.

  Default processing is to return "Component not focusable" if the component doesn't implement the IFocusComp interface, "Not virtualized" if the component is not in a virtualized state, or null otherwise.

  Specified by:

  canRequestFocus in interface IPropCnr

  Parameters:

  ignoreVisibleFlag - Flag indicating that the visible state should be ignored. If this flag is false and the component hidden an error message is returned.

  ignoreEnabledFlag - Flag indicating that the enabled state should be ignored. If this flag is false and the component hidden an error message is returned.

  Returns:

  null focus is possible to this component, or an error message describing why focus cannot be requested.

• couldRequestFocusIfVirtualized

  public java.lang.String couldRequestFocusIfVirtualized​(boolean ignoreVisibleFlag,
                                                         boolean ignoreEnabledFlag)

  Returns if this component could receive focus if it would be virtualized. Focus capable components may override to return null for success, or other error message.

  Default processing is to return "Component not focusable" if the component doesn't implement the IFocusComp interface or null otherwise.

  Specified by:

  couldRequestFocusIfVirtualized in interface IPropCnr

  Parameters:

  ignoreVisibleFlag - Flag indicating that the visible state should be ignored. If this flag is false and the component hidden an error message is returned.

  ignoreEnabledFlag - Flag indicating that the enabled state should be ignored. If this flag is false and the component hidden an error message is returned.

  Returns:

  null focus is possible to this component, or an error message describing why focus cannot be requested.

• requestFocus

  public java.lang.String requestFocus​(IGProp<?> trigger,
                                       boolean isRemoteInduced)

  Requests focus to this component. This call is redirected to the focus engine for the component type. The engine may veto the focus change, because it currently cannot change focus, or the request is not or cannot be virtualized.

  This method is less precise than requestFocusEx(IGProp, boolean, IFocusVetoListener), but avoids try-catching.

  This method is implemented in PropCnr, but should only be called for IFocusComp implementing property classes. This method will return "Component not focusable" if called on a non-focus component.

  Specified by:

  requestFocus in interface IPropCnr

  Parameters:

  trigger - The trigger property, null for none.

  isRemoteInduced - Flag for remote induced focus.

  Returns:

  null for success, otherwise an error message indicating why focus was not able to be changed.

• requestFocusEx

  public boolean requestFocusEx​(IGProp<?> trigger,
                                boolean isRemoteInduced)
                         throws FocusException

  Requests focus to this component. This call is redirected to the focus engine for the component type. The engine may veto the focus change, because it currently cannot change focus, or the request is not or cannot be virtualized.

  This method is implemented in PropCnr, but should only be called for IFocusComp implementing property classes. This method will throw FocusException with message "Component not focusable" if called on a non-focus component.

  Specified by:

  requestFocusEx in interface IPropCnr

  Parameters:

  trigger - The trigger property, null for none.

  isRemoteInduced - Flag for remote induced focus.

  Returns:

  true if focus was changed, false otherwise.

  Throws:

  FocusException - If focus could not be changed.

• requestFocus

  protected java.lang.String requestFocus​(IGProp<?> trigger,
                                          boolean isRemoteInduced,
                                          IFocusVetoListener callback)

  Requests focus to this component. This call is redirected to the focus engine for the component type. The engine may veto the focus change, because it currently cannot change focus, or the request is not or cannot be virtualized.

  This method is less precise than requestFocusEx(IGProp, boolean, IFocusVetoListener), but avoids try-catching.

  This method is implemented in PropCnr, but should only be called for IFocusComp implementing property classes. This method will return "Component not focusable" if called on a non-focus component.

  Parameters:

  trigger - The trigger property, null for none.

  isRemoteInduced - Flag for remote induced focus.

  callback - Optional callback that may throw a veto exception, null for none. This callback is intended to perform focus changes in the tree, typically for UI containers.

  Returns:

  null for success, otherwise an error message indicating why focus was not able to be changed.

• requestFocusEx

  protected boolean requestFocusEx​(IGProp<?> trigger,
                                   boolean isRemoteInduced,
                                   IFocusVetoListener callback)
                            throws FocusException

  Requests focus to this component. This call is redirected to the focus engine for the component type. The engine may veto the focus change, because it currently cannot change focus, or the request is not or cannot be virtualized.

  This method is implemented in PropCnr, but should only be called for IFocusComp implementing property classes. This method will throw FocusException with message "Component not focusable" if called on a non-focus component.

  Parameters:

  trigger - The trigger property, null for none.

  isRemoteInduced - Flag for remote induced focus.

  callback - Optional callback that may throw a veto exception, null for none. This callback is intended to perform focus changes in the tree, typically for UI containers.

  Returns:

  true if focus was changed, false otherwise.

  Throws:

  FocusException - If focus could not be changed.

• hasFocus

  public boolean hasFocus()

  Returns if the component currently has focus.

  Specified by:

  hasFocus in interface IPropCnr

  Returns:

  true if this component has focus, false otherwise.

• getRetargetedVerifyContainer

  protected PropCnr getRetargetedVerifyContainer()

  Gets the retargeted verification property container.

  Returns:

  The default is to return null.

• verifyInternalUseOnly

  public final int verifyInternalUseOnly​(java.util.Set<PropCnr> currentlyBeingVerifiedPropCnrs,
                                         IKStringInfoProvider provider)

  Verifies this property after editing. This is done from the PropHelper during processing of queued verifications.

  To request a verification, use com.iizigo.editor#queueVerify(PropCnr) or com.iizigo.editor#doVerify(PropCnr) instead.

  This method will warn if called for a property not having the parent of FileURIPropCnr, FolderURIPropCnr or a root property.

  Parameters:

  currentlyBeingVerifiedPropCnrs - The synchronized set of properties currently being verified.

  provider - The KString information provider.

  Returns:

  0 for no errors, 1 for errors present, -1 for not executed.

  Throws:

  java.lang.NullPointerException - If provider is null.

• getErrorsProp

  public ErrorsProp getErrorsProp​(boolean createIfNotPresent)

  Gets the errors property. If it's not present it may be created. An InternalError is thrown if the property is created by couldn't be added.

  Specified by:

  getErrorsProp in interface IPropCnr

  Parameters:

  createIfNotPresent - Set to true to create the property if it's not present.

  Returns:

  null if the errors property doesn't exist.

• getChildPropErrorSeverity

  public final int getChildPropErrorSeverity​(Atom atom)

  Gets the error severity of a child property. This call makes it possible to check if the property is missing.

  Specified by:

  getChildPropErrorSeverity in interface IPropCnr

  Parameters:

  atom - The atom name of the child property.

  Returns:

  -1 for none, otherwise IPropErrorItem.INFO=0, WARNING=1, ERROR=2.

• getChildPropErrorSeverity

  public final int getChildPropErrorSeverity​(java.lang.String name)

  Gets the error severity of a child property. This call makes it possible to check if the property is missing.

  Specified by:

  getChildPropErrorSeverity in interface IPropCnr

  Parameters:

  name - The name of the child property.

  Returns:

  -1 for none, otherwise IPropErrorItem.INFO=0, WARNING=1, ERROR=2.

• getChildPropError

  public IPropErrorItem getChildPropError​(Atom atom)

  Gets the child property default error ID. This call makes it possible to get an error for a property that does not exist and the error is stored in this parent instead.

  Specified by:

  getChildPropError in interface IPropCnr

  Parameters:

  atom - The atom name of the child property.

  Returns:

  The error item property, or null for no error.

• getChildPropError

  public IPropErrorItem getChildPropError​(java.lang.String name)

  Gets the child property default error ID. This call makes it possible to get an error for a property that does not exist and the error is stored in this parent instead.

  Specified by:

  getChildPropError in interface IPropCnr

  Parameters:

  name - The name of the child property.

  Returns:

  The error item property, or null for no error.

• getReferences

  public int getReferences​(java.util.List<Reference> references)

  Gets the references of this property top others. This method is typically used in the Designer to search for circular references during verification.

  Specified by:

  getReferences in interface IGProp<GProp<?>[]>

  Overrides:

  getReferences in class GProp<GProp<?>[]>

  Parameters:

  references - The references array is filled in by this method.

  Returns:

  The count of references added.

• verify

  public boolean verify​(PropVerification verification)

  Verifies this property container. The check performed is the extension of classes and that no circular reference is present. It is recommended to override the method rather than the verify method.

  Specified by:

  verify in interface IGProp<GProp<?>[]>

  Overrides:

  verify in class GProp<GProp<?>[]>

  Parameters:

  verification - The property verification class.

  Returns:

  true if verification should proceed, false if disposed of and verification should not take place.

• verifyTree

  public java.util.List<java.lang.String> verifyTree​(IKStringInfoProvider provider)

  Verifies if this property container and its children for problems.

  Parameters:

  provider - The KString information provider.

  Returns:

  A list of errors, or null if OK.

  Throws:

  java.lang.NullPointerException - If provider is null.

• isChild

  public final boolean isChild​(IGProp<?> prop)

  Checks if the property parameter is a child property in this container property.

  Specified by:

  isChild in interface IPropCnr

  Parameters:

  prop - The property.

  Returns:

  true if property is a child, false otherwise.

• isSibling

  public final boolean isSibling​(IGProp<?> prop)

  Checks if the property parameter is a sibling property in this container property.

  Specified by:

  isSibling in interface IPropCnr

  Parameters:

  prop - The property.

  Returns:

  true if property is a sibling, false otherwise.

• getPossibleChildren

  public java.lang.Class<?>[] getPossibleChildren()

  Gets the acceptable children property classes that can be used in conjunction with e.g. a Paste operation.

  Specified by:

  getPossibleChildren in interface IPropCnr

  Returns:

  An array containing the classes of possible children, or null for no support.

• validateClassInstances

  public boolean validateClassInstances​(boolean doPerform,
                                        GProp<?>[] props,
                                        boolean isMove)

  Validates the target property container classes for paste/move with additional instance testing, extra check when the possible children are verified.

  Override this method that by default returns true to provide fine-tuned testing for validity.

  Specified by:

  validateClassInstances in interface IPropCnr

  Parameters:

  doPerform - The perform flag, false means just testing.

  props - Properties to move or paste.

  isMove - Flag for move if true, false means paste.

  Returns:

  true if the class instances for move or paste are valid, false otherwise.

• getVSReference

  public VSReference getVSReference​(Atom refAtom)

  Gets a VSReference instance from the container or any parent containers. The method is used by VSRelativeReference to look up the VSReference instance in order to resolve the relative path to the target property.

  This method needs to be overridden by subclasses of PropCnr that has a VSReference as property, e.g. the JSONInProp class in the Web Service plug-in.

  The default is to re-target the call to the parent container, and if the root, a folder or a file property is reached, null is returned.

  Specified by:

  getVSReference in interface IGProp<GProp<?>[]>

  Overrides:

  getVSReference in class GProp<GProp<?>[]>

  Parameters:

  refAtom - The property asking for the VSReference.

  Returns:

  The instance of the VSReference or null if unassigned. The returned instance could also be a VSParticipant and should therefore be processed accordingly.

• createVSReference

  public VSReference createVSReference​(Atom refAtom,
                                       PropCnr[] returnParent)

  Creates a VSReference instance from the container or any parent containers. The method is used in the Designer to create a VirtualSpace connection for VSRelativeReference to look up the VSReference instance in order to resolve the relative path to the target property.

  This method needs to be overridden by subclasses of PropCnr that has a VSReference as property, and *SHOULD* match getVSReference(Atom).

  The default is to re-target the call to the parent container, and if the root, a folder or a file property is reached, null is returned.

  Parameters:

  refAtom - The property asking for the VSReference.

  returnParent - An array of PropCnr [1] that will be filled in with the parent property of the VSRefernce.

  Returns:

  The instance of the VSReference created or null if impossible. The instance has NOT been added to any container, i.e. is orphan.

• getPropBaseReference

  public PropCnr getPropBaseReference()

  Gets a base property container reference instance from the container or any parent containers. The method is used by PropRelativeReference to look up the reference instance in order to resolve the relative path to the target property.

  This method needs to be overridden by subclasses of PropCnr that has a PropRelativeReference as property, e.g. the ScreenProp class in the Terminal Core plug-in.

  The default is to re-target the call to the parent container, and if the root, a folder or a file property is reached, null is returned.

  Specified by:

  getPropBaseReference in interface IGProp<GProp<?>[]>

  Overrides:

  getPropBaseReference in class GProp<GProp<?>[]>

  Returns:

  The instance of the PropCnr or null if unassigned.

• resolveRuntimeReferences

  public void resolveRuntimeReferences​(IRuntimeResolver resolver)

  Called before transactions are prepared for sending. This method allows creation of e.g. runtime references such as Styles or Panel references that adds a virtual instance for the Client.

  This call is propagated in the entire client tree.

  Specified by:

  resolveRuntimeReferences in interface IGProp<GProp<?>[]>

  Overrides:

  resolveRuntimeReferences in class GProp<GProp<?>[]>

  Parameters:

  resolver - The reference resolver.

• getExtendsPossibleClasses

  public java.lang.Class<?>[] getExtendsPossibleClasses()

  Gets the possible classes this container supports for the Extends Framework. The default implementation is to return null.

  Specified by:

  getExtendsPossibleClasses in interface IPropCnr

  Returns:

  List of supported classes, or null for none.

• isExtendsPropertyValid

  public boolean isExtendsPropertyValid​(GProp<?> property)

  Validates an extends property for the Extends Framework.

  Parameters:

  property - The property to validate.

  Returns:

  true if the extends property is valid.

• setExtendsName

  public boolean setExtendsName​(java.lang.String newName)
                         throws PropException

  Sets the extends property name. The property name is set, but this can still result in an error (the reference is not found, or a circular reference occurred).

  Specified by:

  setExtendsName in interface IPropCnr

  Parameters:

  newName - The new extends from property, null to clear.

  Returns:

  Change flag, i.e. if there was a change, or false for no change or failure.

  Throws:

  PropException - If called from the Server or Client, or if this property container doesn't support the Extends Framework.

• getExtendsName

  public java.lang.String getExtendsName()

  Gets the reference property name being extended.

  Specified by:

  getExtendsName in interface IPropCnr

  Returns:

  The reference name of the extended container, or null for none.

• getExtendsError

  public java.lang.String getExtendsError()

  Gets the Extends Framework error.

  Specified by:

  getExtendsError in interface IPropCnr

  Returns:

  An error string with the error, or null for no error.

• setExtendsOverride

  public boolean setExtendsOverride​(Atom atom,
                                    boolean on)

  Sets a property name as overridden in this container using extendsFrom another container. This effectively removes the property that is present in the extends-from-container from this container, leaving a null-reply at e.g. getProp(...).

  Specified by:

  setExtendsOverride in interface IPropCnr

  Parameters:

  atom - The atom to override.

  on - When set, adds this as being an overridden property. When cleared, removes the property from being overridden.

  Returns:

  true for change, false for no change or failure.

• isExtendsOverriden

  public boolean isExtendsOverriden​(Atom atom)

  Checks if a property name is overridden in this container when using the Extends Framework.

  Specified by:

  isExtendsOverriden in interface IPropCnr

  Parameters:

  atom - The atom to override.

  Returns:

  true for overridden, false otherwise.

• initializeExtendsFramework

  public boolean initializeExtendsFramework​(GEvent triggerEvent)
                                     throws PropException

  Initializes the extends framework for this container. It must first have been defined using setExtendsName.

  If an exception occurs, use getExtendsError() to get the error message.

  Specified by:

  initializeExtendsFramework in interface IPropCnr

  Parameters:

  triggerEvent - The event that triggered this reference event, null for none.

  Returns:

  true if initialized, false for already initialize.

  Throws:

  PropException - An exception for initializing errors (e.g. invalid reference, invalid properties).

• getExtendsOverride

  public Atom[] getExtendsOverride()

  Gets the extends override atoms.

  Returns:

  The atom array (never empty), or null for none.

• isExtendsRoot

  public final boolean isExtendsRoot()

  Checks if this container is an Extends Root container, i.e. one that has a defined Extends Name defined.

  Specified by:

  isExtendsRoot in interface IPropCnr

  Returns:

  true if this container is the root of an extended container, or false for all other properties.

• getExtendsContainer

  public PropCnr getExtendsContainer()

  Gets the extends container. This method will only work in the Designer and when the extends name has been resolved.

  Returns:

  The container being extended, null for none or if the name is not resolved.