java.lang.Object
- com.iizix.prop.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.

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.

Class PropReference

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MSG_REF_NOT_FOUND

MSG_REF_WRONG_CLASS

Constructor Detail

PropReference

PropReference

Method Detail

dispose

isDisposed

getOwner

setName

getOriginalName

getName

getProperty

resolve

resolve

isResolved

finalize