org.openide.util 8.19.1

org.openide.util
Class SharedClassObject

java.lang.Object
  extended by 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
protected SharedClassObject()
          Create a shared object.
 
Method Summary
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:
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 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 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 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 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

org.openide.util 8.19.1

Built on December 7 2011.  |  Portions Copyright 1997-2011 Oracle. All rights reserved.