Class ObjectProperty<T>

java.lang.Object

com.thecsdev.common.properties.ObjectProperty<T>

Type Parameters:

T - The type of the stored value.

Direct Known Subclasses:

DefaultableProperty, NotNullProperty, StringProperty

@Virtual
public class ObjectProperty<T>
extends Object

A property wrapper for an Object of type T, similar to AtomicReference, but with additional utility features.
Inspired by JavaFX's property system.

Constructor Summary

Constructors

Constructor	Description
ObjectProperty()
ObjectProperty(T value)

Method Summary

Modifier and Type	Method	Description
final boolean	addChangeListener(@NotNull IChangeListener<T> changeListener)	Adds an IChangeListener to the list of change listeners.
final boolean	addFilter(Function<T,T> filter, @NotNull Class<?> whoIsAsking)	Adds a filter Function to the list of filters.
final T	applyFilters(T newValue)	Applies filters to a given value.
protected final void	assertCallerIsOwner(@NotNull Class<?> caller)	Ensures that a given Class is an owner using isOwner(Class).
T	get()	Returns the current value of this ObjectProperty.
final ValueHandle<T>	getHandle()	Returns the internal AtomicReference backing this property.
final @Nullable IChangeListener<T>	getInterceptor(@NotNull Class<?> whoIsAsking)	Returns the interceptor instance that intercepts set(Object) calls by Classes that do not own this ObjectProperty.
@NotNull Optional<@Nullable T>	getOptional()	Returns the current value of this ObjectProperty wrapped in an Optional.
final Class<?>	getOwner()	Returns the Class that owns this ObjectProperty.
final boolean	getReadOnly()	Returns true if this ObjectProperty is read-only and cannot be set(Object).
final boolean	isOwner(@NotNull Class<?> caller)	Returns true if a given Class is considered an owner of this ObjectProperty.
final boolean	removeChangeListener(Object changeListener)	Removes an IChangeListener from the list of change listeners.
final boolean	removeFilter(Object filter)	Removes a filter Function from the list of filters.
final void	set(T value)	Deprecated. Because this uses stack walking to enforce CallerSensitive, this method causes performance bottlenecks.
final void	set(T value, @NotNull Class<?> whoIsAsking)	Sets the current value of this ObjectProperty.
final void	setHandle(@NotNull ValueHandle<T> newHandle)	Replaces the internal AtomicReference backing this property.
final void	setInterceptor(@Nullable IChangeListener<T> interceptor, @NotNull Class<?> whoIsAsking)	Assigns an interceptor instance for this ObjectProperty. Please see getInterceptor(Class) for more info.
final void	setOwner(@Nullable Class<?> owner, @NotNull Class<?> whoIsAsking)	Assigns a new owner Class for this ObjectProperty.
final void	setReadOnly(boolean readOnly, @NotNull Class<?> whoIsAsking)	Sets the getReadOnly() state.

Methods inherited from class Object

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

Constructor Details

ObjectProperty

public ObjectProperty()

ObjectProperty

public ObjectProperty(@Nullable
 T value)

Method Details

getOwner

public final Class<?> getOwner()

Returns the Class that owns this ObjectProperty.

API Note:

This is likely the Class that created this instance.

setOwner

@CallerSensitive
public final void setOwner(@Nullable
 @Nullable Class<?> owner,
 @NotNull
 @NotNull Class<?> whoIsAsking)
                    throws NullPointerException,
IllegalCallerException

Assigns a new owner Class for this ObjectProperty.

Parameters:

owner - The new owner.

whoIsAsking - The Class calling this method. It is CRITICAL not to lie here.

Throws:

NullPointerException - If a NotNull argument is null.

IllegalCallerException - See assertCallerIsOwner(Class).

isOwner

public final boolean isOwner(@NotNull
 @NotNull Class<?> caller)
                      throws NullPointerException

Returns true if a given Class is considered an owner of this ObjectProperty. Those are:

• getOwner()
• #getOwner().isAssignableFrom(caller)
• ObjectProperty.class.isAssignableFrom(caller)

Any other Class will return false.

Throws:

NullPointerException - If the argument is null.

API Note:

As a tip, remember that extending a Class that has declared ObjectPropertys means that you too (the subclass) now owns said properties as well.

assertCallerIsOwner

protected final void assertCallerIsOwner(@NotNull
 @NotNull Class<?> caller)
                                  throws IllegalCallerException

Ensures that a given Class is an owner using isOwner(Class). If said class is not an owner, IllegalCallerException is thrown.

Throws:

IllegalCallerException

getHandle

public final ValueHandle<T> getHandle()

Returns the internal AtomicReference backing this property.

This gives direct access to the underlying value, bypassing all access control such as getOwner() and getReadOnly().

Returns:

The atomic reference holding the actual value

API Note:

Use with caution. This provides low-level access and can break property invariants if misused.

setHandle

@UnstableApi
public final void setHandle(@NotNull
 @NotNull ValueHandle<T> newHandle)
                     throws NullPointerException

Replaces the internal AtomicReference backing this property.

This completely overrides the current value holder, bypassing all checks including getOwner() and getReadOnly().

Parameters:

newHandle - The new ValueHandle to use

Throws:

NullPointerException - if handle is null

API Note:

Use with caution. This provides low-level access and can break property invariants if misused.
In addition, IChangeListeners are bound to ValueHandles! (for now)

getReadOnly

public final boolean getReadOnly()

Returns true if this ObjectProperty is read-only and cannot be set(Object).

API Note:

The owner of this ObjectProperty bypasses readOnly when calling set(Object).

In addition, read-only prevents getInterceptor(Class) from working.

setReadOnly

@CallerSensitive
public final void setReadOnly(boolean readOnly,
 @NotNull
 @NotNull Class<?> whoIsAsking)
                       throws IllegalCallerException

Sets the getReadOnly() state.

Parameters:

readOnly - The new readonly state.

whoIsAsking - The Class calling this method. It is CRITICAL not to lie here.

Throws:

IllegalCallerException - See assertCallerIsOwner(Class).

API Note:

Will prevent getInterceptor(Class) from working if set to true.

getInterceptor

@CallerSensitive
@Nullable
public final @Nullable IChangeListener<T> getInterceptor(@NotNull
 @NotNull Class<?> whoIsAsking)
                                                  throws IllegalCallerException

Returns the interceptor instance that intercepts set(Object) calls by Classes that do not own this ObjectProperty.

Parameters:

whoIsAsking - The Class calling this method. It is CRITICAL not to lie here.

Throws:

IllegalCallerException - See assertCallerIsOwner(Class).

setInterceptor

@CallerSensitive
public final void setInterceptor(@Nullable
 @Nullable IChangeListener<T> interceptor,
 @NotNull
 @NotNull Class<?> whoIsAsking)
                          throws IllegalCallerException

Assigns an interceptor instance for this ObjectProperty.
Please see getInterceptor(Class) for more info.

Parameters:

interceptor - The new interceptor instance.

whoIsAsking - The Class calling this method. It is CRITICAL not to lie here.

Throws:

IllegalCallerException - See assertCallerIsOwner(Class).

get

@Virtual
@Nullable
public T get()

Returns the current value of this ObjectProperty.

API Note:

Overrides should use the value in getHandle().

getOptional

@Virtual
@NotNull
public @NotNull Optional<@Nullable T> getOptional()

Returns the current value of this ObjectProperty wrapped in an Optional.

set

@Deprecated
@CallerSensitive
public final void set(@Nullable
 T value)
               throws IllegalCallerException

Deprecated.

Because this uses stack walking to enforce CallerSensitive, this method causes performance bottlenecks. Avoid this one.

Sets the current value of this ObjectProperty.

Parameters:

value - The new value.

Throws:

IllegalCallerException - If getReadOnly(), and the caller is not an owner. See assertCallerIsOwner(Class).

See Also:

• set(Object, Class)

set

@CallerSensitive
public final void set(@Nullable
 T value,
 @NotNull
 @NotNull Class<?> whoIsAsking)
               throws IllegalCallerException

Sets the current value of this ObjectProperty.

Parameters:

value - The new value.

whoIsAsking - The Class calling this method. It is CRITICAL not to lie here.

Throws:

IllegalCallerException - If getReadOnly(), and the caller is not an owner. See assertCallerIsOwner(Class).

addFilter

@CallerSensitive
public final boolean addFilter(Function<T,T> filter,
 @NotNull
 @NotNull Class<?> whoIsAsking)
                        throws IllegalCallerException

Adds a filter Function to the list of filters.

Parameters:

filter - The filter to add.

whoIsAsking - The Class calling this method. It is CRITICAL not to lie here.

Throws:

IllegalCallerException - See assertCallerIsOwner(Class).

removeFilter

public final boolean removeFilter(Object filter)

Removes a filter Function from the list of filters.

Parameters:

filter - The filter to remove.

Returns:

A boolean indicating if the Function was present prior to its removal.

applyFilters

public final T applyFilters(T newValue)

Applies filters to a given value. This is generally used in set(Object, Class)

See Also:

• addFilter(Function, Class)
• removeFilter(Object)

addChangeListener

public final boolean addChangeListener(@NotNull
 @NotNull IChangeListener<T> changeListener)
                                throws NullPointerException

Adds an IChangeListener to the list of change listeners.

Parameters:

changeListener - The IChangeListener to add.

Throws:

NullPointerException - If the argument is null.

API Note:

IMPORTANT: IChangeListeners are bound to ValueHandles! Using setHandle(ValueHandle) changes the IChangeListeners as well!

removeChangeListener

public final boolean removeChangeListener(Object changeListener)

Removes an IChangeListener from the list of change listeners.

Parameters:

changeListener - The IChangeListener to remove.

Returns:

A boolean indicating if the IChangeListener was present prior to its removal.