info.pppc.base.system

Class PluginDescription

java.lang.Object

info.pppc.base.system.PluginDescription

All Implemented Interfaces:

ISerializable, IExtension

public final class PluginDescription
extends java.lang.Object
implements ISerializable, IExtension

Object which describes a plug-in implementation and can be propagated to other systems. The plug-in description contains an ability, an extension and a key. These are read-only values that are set when the description is created for the first time. The ability describes the task performed by the plug-in. For space purposes it is described by a byte array of length two. A plug-in that announces an ability must be compatible with all other plug-ins that announce the same ability. The extension defines the extension points provided by the plug-in. The possible extension points are defined as constants in the extension interface.

Author:

Marcus Handte

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ABBREVIATION The abbreviation used for this class during serialization.
static int	EVENT_PROPERTY_ADDED Signals that a property has been added to the description.
static int	EVENT_PROPERTY_CHANGED Signals that a property of the description has been changed.
static int	EVENT_PROPERTY_REMOVED Signals that a property is about to be removed.

Fields inherited from interface info.pppc.base.system.IExtension

EXTENSION_COMPRESSION, EXTENSION_DISCOVERY, EXTENSION_ENCRYPTION, EXTENSION_ROUTING, EXTENSION_SEMANTIC, EXTENSION_SERIALIZATION, EXTENSION_TRANSCEIVER

Constructor Summary

Constructors

Constructor and Description
PluginDescription() Creates a new plug-in description.
PluginDescription(short ability, short extension) Creates a new plug-in description with the specified ability and the specified extension.

Method Summary

Methods

Modifier and Type	Method and Description
void	addListener(int type, IListener listener) Registers a listener for the specified types of events.
boolean	equals(java.lang.Object o) Determines whether the passed object equals this plug-in description.
short	getAbility() Returns the ability of the plug-in.
short	getExtension() Returns the extension point that is supported by this plug-in.
java.lang.String[]	getProperties() Returns the property names that are defined by this plug-in description.
java.lang.Object	getProperty(java.lang.String key) Returns the property with the specified key or null if it is not set.
int	hashCode() Returns the hash code of the plug-in description.
boolean	hasProperty(java.lang.String key) Determines whether the specified property is set.
boolean	isPropertyDynamic(java.lang.String key) Determines whether the property at the specified key is dynamic.
void	readObject(IObjectInput input) Deserializes the description from the given input stream.
boolean	removeListener(int type, IListener listener) Unregisters the specified listener from the specified set of event types.
java.lang.Object	setProperty(java.lang.String key, java.lang.Object property, boolean dynamic) Sets a property to the specified value.
java.lang.Object	unsetProperty(java.lang.String key) Removes a property with the specified key.
void	writeObject(IObjectOutput output) Serializes the description to the given output stream.

Methods inherited from class java.lang.Object

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

Field Detail

ABBREVIATION

public static final java.lang.String ABBREVIATION

The abbreviation used for this class during serialization.

See Also:

Constant Field Values

EVENT_PROPERTY_ADDED

public static final int EVENT_PROPERTY_ADDED

Signals that a property has been added to the description. The data object of the event will contain the name of the property.

See Also:

Constant Field Values

EVENT_PROPERTY_CHANGED

public static final int EVENT_PROPERTY_CHANGED

Signals that a property of the description has been changed. The data object of the event will contain the name of the property.

See Also:

Constant Field Values

EVENT_PROPERTY_REMOVED

public static final int EVENT_PROPERTY_REMOVED

Signals that a property is about to be removed. The data object of the event will contain the name of the property.

See Also:

Constant Field Values

Constructor Detail

PluginDescription

public PluginDescription()

Creates a new plug-in description. This default constructor is intended for serialization purposes, it must not be called by user code.

PluginDescription

public PluginDescription(short ability,
                 short extension)

Creates a new plug-in description with the specified ability and the specified extension.

Parameters:

ability - The ability of the plu-gin. The ability must be globally unique. The default policy to assign abilities is to use the most significant byte as plug-in identifier and the least significant byte as unique id. Note that the ability is used to match plug-ins on different devices, thus if two plug-ins with different tasks have the same id, you might not be able to communicate with a remote device.

extension - The extension point of the plug-in. The possible extensions are defined as constants in the extension interface.

Method Detail

addListener

public void addListener(int type,
               IListener listener)

Registers a listener for the specified types of events. At the present time, the plug-in description emits EVENT_PROPERTY_ADDED, EVENT_PROPERTY_REMOVED and EVENT_PROPERTY_CHANGED events whenever a property changes. The other values of the plug-in description are read only values. The data object will contain the name of the property that has been changed, removed or added. All notifications are sent in sync and the listeners will hold the lock.

Parameters:

type - The types to register for.

listener - The listener to register

removeListener

public boolean removeListener(int type,
                     IListener listener)
                       throws java.lang.NullPointerException

Unregisters the specified listener from the specified set of event types.

Parameters:

type - The types to unregister for.

listener - The listener to unregister.

Returns:

True if the listener is no longer registered for any event, false if the listener is still registered or if it has not been registered.

Throws:

java.lang.NullPointerException - Thrown if the listener is null.

setProperty

public java.lang.Object setProperty(java.lang.String key,
                           java.lang.Object property,
                           boolean dynamic)

Sets a property to the specified value. If the property has been set before, this method will return and replace the existing value. The listeners will be informed either by a EVENT_PROPERTY_ADDED or EVENT_PROPERTY_CHANGED event about the changed or added property. If the property is set to the same value as the original property, the listeners will not be informed.

Parameters:

key - The key of the property to set, this may not be null.

property - The value of the property.

dynamic - A boolean that determines whether the property is dynamic. Dynamic properties are only used for local communication.

Returns:

The value of the property that has been replaced.

unsetProperty

public java.lang.Object unsetProperty(java.lang.String key)

Removes a property with the specified key. If the property has been set before, this method will return and remove the existing value. If the property was not set, the method will return null. If the property was set, the listeners will be informed by a EVENT_PROPERTY_REMOVED event. If the property was not set, the listeners will not be informed.

Parameters:

key - The key of the property to remove, this may not be null.

Returns:

The value of the property that has been removed or null if the property did not exist.

isPropertyDynamic

public boolean isPropertyDynamic(java.lang.String key)

Determines whether the property at the specified key is dynamic. If the property does not exist, false will be returned. Dynamic properties are not used for communication through a gateway.

Parameters:

key - The key of the property.

Returns:

True if the property is dynamic, false otherwise.

getProperty

public java.lang.Object getProperty(java.lang.String key)

Returns the property with the specified key or null if it is not set.

Parameters:

key - The key of the property to retrieve, this may not be null.

Returns:

The value of the property or null if it is not set.

hasProperty

public boolean hasProperty(java.lang.String key)

Determines whether the specified property is set. Returns true if the property is set (even if it is set to null) and false if it is not set.

Parameters:

key - The key of the property to retrieve, this may not be null.

Returns:

Returns true if the specified property is set and false if it is not set.

getProperties

public java.lang.String[] getProperties()

Returns the property names that are defined by this plug-in description.

Returns:

The property names defined by the plug-in description.

getAbility

public short getAbility()

Returns the ability of the plug-in.

Returns:

The ability of the plug-in.

getExtension

public short getExtension()

Returns the extension point that is supported by this plug-in. The value can be one of the three extensions defined by the extension constants or a combination of them that is concatenated using a logical or.

Returns:

The extension supported by the plug-in.

equals

public boolean equals(java.lang.Object o)

Determines whether the passed object equals this plug-in description. Two plug-in descriptions are equal if they have the same key and creator system. If the creator system or the key of one of the descriptions is not specified the method will test for reference equality.

Overrides:

equals in class java.lang.Object

Parameters:

o - The object to compare.

Returns:

True if the plug-in descriptions are the same object or if they have the same key generated by the same system.

hashCode

public int hashCode()

Returns the hash code of the plug-in description. If the key is set, the hash code will be equal to the key, otherwise the system generated hash code will be returned.

Overrides:

hashCode in class java.lang.Object

Returns:

The hash code of the plug-in description (typically this will be the value of the key.

readObject

public void readObject(IObjectInput input)
                throws java.io.IOException

Deserializes the description from the given input stream. The listeners that were registered at the original description are not deserialized.

Specified by:

readObject in interface ISerializable

Parameters:

input - The stream to read from.

Throws:

java.io.IOException - Thrown if the deserialization fails.

writeObject

public void writeObject(IObjectOutput output)
                 throws java.io.IOException

Serializes the description to the given output stream. The listeners that are registered at the description are not serialized, they are transient.

Specified by:

writeObject in interface ISerializable

Parameters:

output - The stream to write to.

Throws:

java.io.IOException - Thrown if the serialization fails.