Package com.iizix.prop

Class PropReference

java.lang.Object
com.iizix.prop.PropReference
Direct Known Subclasses:
JavaPropReference
public class PropReference extends Object
This class is used to hold a reference to a property by the reference name for an owner property. It keeps track of what happens with the property being referenced once the reference is found, fully automatically, and informs the owner of the reference using the IPropReference interface.

It is of utmost importance to dispose of the reference when the property no longer needs it or the object instance is to be released or removed. During finalizer, Java collects this object and an error will then be logged, because this is a strong candidate for memory leaks. This is due to the fact that a listener is added to the referenced property.

If an instance if created, it should always be disposed of. The only case that is acceptable not to dispose of PropReference is: a single instance of PropReference is created for with a property as owner.

Reference names look like ModuleProject:/folder/... and the function used to look up properties using these names is GProp.getPropFromReference(referenceName).

Author:
Christopher Mindus

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    MSG_REF_NOT_FOUND
    Message for reference not found.
    static final String
    MSG_REF_WRONG_CLASS
    Message for reference found, but wrong class.

  • Constructor Summary

    Constructors
    Constructor
    Description
    PropReference(GProp<?> owner, String name, Class<?>[] supportedClasses, IPropReference listener)
    Constructs a new property reference with a property owner.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    dispose()
    Disposes of the PropReference instance.
    protected void
    finalize()
    Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
    String
    getName()
    Gets the reference name.
    String
    getOriginalName()
    Gets the original reference name that was specified in the constructor or by a call to setName.
    GProp<?>
    getOwner()
    Gets the owner property.
    GProp<?>
    getProperty()
    Gets the property referenced.
    boolean
    isDisposed()
    Checks if the reference is disposed of.
    boolean
    isResolved()
    Checks if the property reference is resolved and that reference is not disposed of.
    int
    resolve(boolean doReCheck, GEvent triggerEvent)
    Attempts to resolve the property name.
    int
    resolve(GProp<?> anyPropertyInTree, boolean doReCheck, GEvent triggerEvent)
    Attempts to resolve the property name.
    boolean
    setName(String newName)
    Sets a new reference name.
    String
    toString()
    Returns a String representation of this instance.
    String
    toString(boolean includeFullProperties)
    Returns a String representation of this instance.
    static String
    toString(PropReference ref)
    The toString representation without risk of causing a StackOverflow in case of round-robbin scenarios.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

    • PropReference

      public PropReference(GProp<?> owner, String name, Class<?>[] supportedClasses, IPropReference listener)
      Constructs a new property reference with a property owner. A property listener is added to the owner (if not null) listening at property dispose, in order for PropReference to clean-up automatically.

      In addition, PropReference will reply with the owner property at the events for references to resolve references and to reply at query references.

      The classes is used without checking for superclasses or subclasses, it must be a direct class match.

      If the listener parameter is null, no property listener is used, thus this class will be safe and cannot cause memory leaks, but the real-time change notification is lost.

      Parameters:
      owner - The owner property, null for none.
      name - The reference name.
      supportedClasses - Array of supported classes for the referenced property, or null for no check.
      listener - The listener, or null for none.

  • Method Details

    • dispose

      public void dispose()
      Disposes of the PropReference instance.

    • isDisposed

      public boolean isDisposed()
      Checks if the reference is disposed of.
      Returns:
      true if disposed of, false otherwise.

    • getOwner

      public GProp<?> getOwner()
      Gets the owner property.
      Returns:
      null if no property is the owner of the property reference.

    • setName

      public boolean setName(String newName)
      Sets a new reference name. By calling this method, any existing listener to a property with a resolved reference is removed.

      In order to re-establish a new working listener, a successful call to resolve is required, or that there is an owner property that is non-null.

      Parameters:
      newName - The new reference name.
      Returns:
      true for name change, false for no change (listener to previous property is retained).

    • getOriginalName

      public String getOriginalName()
      Gets the original reference name that was specified in the constructor or by a call to setName.

    • getName

      public String getName()
      Gets the reference name.

    • getProperty

      public GProp<?> getProperty()
      Gets the property referenced. Even if the property failed to be retrieve due to wrong property class, this method still returns that wrong-class'ed property.

      Use isResolved() to check for valid property.

      Returns:
      The instance of the property, or null if not successfully found.

    • resolve

      public int resolve(boolean doReCheck, GEvent triggerEvent)
      Attempts to resolve the property name. This method can be used when the owner property has been set in the constructor. Otherwise use the method resolve(anyPropertyInTree,doReCheck).
      Parameters:
      doReCheck - Force a re-check flag.
      triggerEvent - The event that triggered this reference event, null for none.
      Returns:
      Value indicating success to resolve:
      • 1 (one) for completed successfully with correct class (if this applies),
      • 0 (zero) indicating failure,
      • -1 (minus one) indicating project is loading and references should not be processed.

    • resolve

      public int resolve(GProp<?> anyPropertyInTree, boolean doReCheck, GEvent triggerEvent)
      Attempts to resolve the property name.
      Parameters:
      anyPropertyInTree - Any property in the tree, fastest is to use a root property, but if you don't have access to it, use what is available (don't do the look-up unless very-very fast). This property is used to get the property reference.
      doReCheck - Force a re-check flag.
      triggerEvent - The event that triggered this reference event, null for none.
      Returns:
      Value indicating success to resolve:
      • 1 (one) for completed successfully with correct class (if this applies),
      • 0 (zero) indicating failure,
      • -1 (minus one) indicating project is loading and references should not be processed.

    • isResolved

      public boolean isResolved()
      Checks if the property reference is resolved and that reference is not disposed of.
      Returns:
      true if property is found and there is a possible class match, false otherwise.

    • finalize

      protected void finalize() throws Throwable
      Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

      If the property listener is still in place, it will be removed.

      Overrides:
      finalize in class Object
      Throws:
      Throwable - For finalizer errors.

    • toString

      public String toString()
      Returns a String representation of this instance.
      Overrides:
      toString in class Object
      Returns:
      String formatted as className and the class parameters.

    • toString

      public String toString(boolean includeFullProperties)
      Returns a String representation of this instance.
      Parameters:
      includeFullProperties - Flag to include full properties or not.
      Returns:
      String formatted as className and the class parameters.

    • toString

      public static String toString(PropReference ref)
      The toString representation without risk of causing a StackOverflow in case of round-robbin scenarios.
      Parameters:
      ref - The PropReference instance or null for none.
      Returns:
      The short version of PropReference.toString(false) if non-null, otherwise "null".