org.openide.util

Class SharedClassObject

java.lang.Object

org.openide.util.SharedClassObject

All Implemented Interfaces:

Externalizable, Serializable

Direct Known Subclasses:

SystemAction

public abstract class SharedClassObject
extends Object
implements Externalizable

Shared object that allows different instances of the same class to share common data.

The data are shared only between instances of the same class (not subclasses). Thus, such "variables" have neither instance nor static behavior.

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SharedClassObject() Create a shared object.

Method Summary

Modifier and Type	Method and Description
protected void	addNotify() Notify subclasses that the first listener has been added to this object.
void	addPropertyChangeListener(PropertyChangeListener l) Adds the specified property change listener to receive property change events from this object.
protected boolean	clearSharedData() Indicate whether the shared data of the last existing instance of this class should be cleared when that instance is finalized.
boolean	equals(Object obj) Test whether the classes of the compared objects are the same.
protected void	finalize()
static <T extends SharedClassObject> T	findObject(Class<T> clazz) Obtain an instance of the desired class, if there is one.
static <T extends SharedClassObject> T	findObject(Class<T> clazz, boolean create) Find an existing object, possibly creating a new one as needed.
protected void	firePropertyChange(String name, Object oldValue, Object newValue) Fire a property change event to all listeners.
protected Object	getLock() Obtain lock for synchronization on manipulation with this class.
protected Object	getProperty(Object key) Get a shared variable.
int	hashCode() Get a hashcode of the shared class.
protected void	initialize() Initialize shared state.
protected Object	putProperty(Object key, Object value) Set a shared variable.
protected Object	putProperty(String key, Object value, boolean notify) Set a shared variable available only for string names.
void	readExternal(ObjectInput oi) Reads nothing from the stream.
protected void	removeNotify() Notify subclasses that the last listener has been removed from this object.
void	removePropertyChangeListener(PropertyChangeListener l) Removes the specified property change listener so that it no longer receives property change events from this object.
protected void	reset() Is called by the infrastructure in cases when a clean instance is requested.
void	writeExternal(ObjectOutput oo) Writes nothing to the stream.
protected Object	writeReplace() This method provides correct handling of serialization and deserialization.

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SharedClassObject

protected SharedClassObject()

Create a shared object. Typically shared-class constructors should not take parameters, since there will conventionally be no instance variables.

See Also:

SharedClassObject.initialize()

Method Detail

finalize

protected final void finalize()
                       throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

clearSharedData

protected boolean clearSharedData()

Indicate whether the shared data of the last existing instance of this class should be cleared when that instance is finalized. Subclasses may perform additional tasks on finalization if desired. This method should be overridden in lieu of SharedClassObject.finalize().

The default implementation returns true. Classes which have precious shared data may want to return false, so that all instances may be finalized, after which new instances will pick up the same shared variables without requiring a recalculation.

Returns:

true if all shared data should be cleared, false if it should stay in memory

equals

public final boolean equals(Object obj)

Test whether the classes of the compared objects are the same.

Overrides:

equals in class Object

Parameters:

obj - the object to compare to

Returns:

true if the classes are equal

hashCode

public final int hashCode()

Get a hashcode of the shared class.

Overrides:

hashCode in class Object

Returns:

the hash code

getLock

protected final Object getLock()

Obtain lock for synchronization on manipulation with this class. Can be used by subclasses when performing nonatomic writes, e.g.

Returns:

an arbitrary synchronizable lock object

putProperty

protected final Object putProperty(Object key,
                                   Object value)

Set a shared variable. Automatically locks.

Parameters:

key - name of the property

value - value for that property (may be null)

Returns:

the previous value assigned to the property, or null if none

putProperty

protected final Object putProperty(String key,
                                   Object value,
                                   boolean notify)

Set a shared variable available only for string names. Automatically locks.

Important: remember that SharedClassObjects are like singleton beans; when you use putProperty with a value of true, or call SharedClassObject.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object), you must consider that the property name should match the JavaBeans name for a natural (introspected) property for the bean, if such a property uses this key. For example, if you have a method getFoo which uses SharedClassObject.getProperty(java.lang.Object) and a method setFoo which uses putProperty(..., true), then the key used must be named foo (assuming you did not override this name in a BeanInfo). Otherwise various listeners may not be prepared for the property change and may just ignore it. For example, the property sheet for a BeanNode based on a SharedClassObject which stores its properties using a misnamed key will probably not refresh correctly.

Parameters:

key - name of the property

value - value for that property (may be null)

notify - should all listeners be notified about property change?

Returns:

the previous value assigned to the property, or null if none

getProperty

protected final Object getProperty(Object key)

Get a shared variable. Automatically locks.

Parameters:

key - name of the property

Returns:

value of the property, or null if none

initialize

protected void initialize()

Initialize shared state. Should use SharedClassObject.putProperty(java.lang.Object, java.lang.Object) to set up variables. Subclasses should always call the super method.

This method need not be called explicitly; it will be called once the first time a given shared class is used (not for each instance!).

addPropertyChangeListener

public final void addPropertyChangeListener(PropertyChangeListener l)

Adds the specified property change listener to receive property change events from this object.

Parameters:

l - the property change listener

removePropertyChangeListener

public final void removePropertyChangeListener(PropertyChangeListener l)

Removes the specified property change listener so that it no longer receives property change events from this object.

Parameters:

l - the property change listener

addNotify

protected void addNotify()

Notify subclasses that the first listener has been added to this object. Subclasses should always call the super method. The default implementation does nothing.

removeNotify

protected void removeNotify()

Notify subclasses that the last listener has been removed from this object. Subclasses should always call the super method. The default implementation does nothing.

firePropertyChange

protected void firePropertyChange(String name,
                                  Object oldValue,
                                  Object newValue)

Fire a property change event to all listeners.

Parameters:

name - the name of the property

oldValue - the old value

newValue - the new value

writeExternal

public void writeExternal(ObjectOutput oo)
                   throws IOException

Writes nothing to the stream.

Specified by:

writeExternal in interface Externalizable

Parameters:

oo - ignored

Throws:

IOException

readExternal

public void readExternal(ObjectInput oi)
                  throws IOException,
                         ClassNotFoundException

Reads nothing from the stream.

Specified by:

readExternal in interface Externalizable

Parameters:

oi - ignored

Throws:

IOException

ClassNotFoundException

writeReplace

protected Object writeReplace()

This method provides correct handling of serialization and deserialization. When serialized the method writeExternal is used to store the state. When deserialized first an instance is located by a call to findObject (clazz, true) and then a method readExternal is called to read its state from stream.

This allows to have only one instance of the class in the system and work only with it.

Returns:

write replace object that handles the described serialization/deserialization process

findObject

public static <T extends SharedClassObject> T findObject(Class<T> clazz)

Obtain an instance of the desired class, if there is one.

Parameters:

clazz - the shared class to look for

Returns:

the instance, or null if such does not exists

findObject

public static <T extends SharedClassObject> T findObject(Class<T> clazz,
                                                         boolean create)

Find an existing object, possibly creating a new one as needed. To create a new instance the class must be public and have a public default constructor.

Parameters:

clazz - the class of the object to find (must extend SharedClassObject)

create - true if the object should be created if it does not yet exist

Returns:

an instance, or null if there was none and create was false

Throws:

IllegalArgumentException - if a new instance could not be created for some reason

reset

protected void reset()

Is called by the infrastructure in cases when a clean instance is requested. As instances of SharedClassObject are singletons, there is no way how to create new instance that would not contain the same data as previously existing one. This method allows all subclasses that care about the ability to refresh the settings (like SystemOptions) to be notified about the cleaning request and clean their settings themselves.

Default implementation does nothing.

Since:

made protected in version 4.46