Class PropReference

  • Direct Known Subclasses:
    JavaPropReference

    public class PropReference
    extends java.lang.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 java.lang.String MSG_REF_NOT_FOUND
      Message for reference not found.
      static java.lang.String MSG_REF_WRONG_CLASS
      Message for reference found, but wrong class.
    • Constructor Summary

      Constructors 
      Constructor Description
      PropReference​(GProp<?> owner, java.lang.String name, java.lang.Class<?>[] supportedClasses, IPropReference listener)
      Constructs a new property reference with a property owner.
      PropReference​(java.lang.String name, java.lang.Class<?>[] supportedClasses, IPropReference listener)
      Constructs a new property reference without property owner.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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.
      java.lang.String getName()
      Gets the reference name.
      java.lang.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.
      boolean resolve​(boolean doReCheck, GEvent triggerEvent)
      Attempts to resolve the property name.
      boolean resolve​(GProp<?> anyPropertyInTree, boolean doReCheck, GEvent triggerEvent)
      Attempts to resolve the property name.
      boolean setName​(java.lang.String newName)
      Sets a new reference name.
      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • MSG_REF_NOT_FOUND

        public static final java.lang.String MSG_REF_NOT_FOUND
        Message for reference not found.
        See Also:
        Constant Field Values
      • MSG_REF_WRONG_CLASS

        public static final java.lang.String MSG_REF_WRONG_CLASS
        Message for reference found, but wrong class.
        See Also:
        Constant Field Values
    • Constructor Detail

      • PropReference

        public PropReference​(java.lang.String name,
                             java.lang.Class<?>[] supportedClasses,
                             IPropReference listener)
        Constructs a new property reference without property owner. It is recommended to always use an owner property, so preferably the constructor PropReference(GProp owner, String name, Class [] supportedClasses, IPropReference listener) should be used.

        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:
        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.
      • PropReference

        public PropReference​(GProp<?> owner,
                             java.lang.String name,
                             java.lang.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 Detail

      • 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​(java.lang.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 java.lang.String getOriginalName()
        Gets the original reference name that was specified in the constructor or by a call to setName.
      • getName

        public java.lang.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 boolean 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:
        true if the resolve completed successfully with correct class (if this applies).
      • resolve

        public final boolean 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:
        true if the resolve completed successfully with correct class (if this applies).
      • 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 java.lang.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 java.lang.Object
        Throws:
        java.lang.Throwable - For finalizer errors.