org.generationcp.core
Interface PropertyChannel

All Known Implementing Classes:

DefaultPropertyChannel

public interface PropertyChannel

PropertyChannel is an interface describing a device that can be used to exchange data and events between components, and to store them in a shareable storage.

The basic rule is that all components that wish to communicate together (exchanging data or events) have to share an instance implementing this interface. There is no rule, however, limiting an application to use only one property channel: different kind of components can talk together using separate instance of a property channel.

The second rule is that all exchanging data are passed as java.beans.PropertyChangeEvent - which allow to send any data. Note, however, that in concrete situations the components exchanging data need to agree on some subset of possible data types. For example, the GCP data consumers consume data as java.util.List with element types defined in the GCP Domain model. Or, the GCP data transformers informs about their transformations using events defined in the package org.generationcp.core.events.

The basic functions of a property channel is similar to functions of a Hashtable (actually the DefaultPropertyChannel extends java.util.Hashtable). The components are sending properties to a channel by calling method put.

Additionally, whenever a value is added to a channel, or updated, the channel also fires an event to inform about it its listeners. In other words, this channel provides its stored properties in two ways:

• A channel push way when an event is fired whenever something new happens, or whwnever a user of a property channel calls its method fire(java.lang.String, java.lang.Object), and
• A component pull way when anytime any component can ask what is the current status of the stored properties.

Additionally, it also serves as a java.beans.PropertyChangeSupport object: it can register and deregister java.beans.PropertyChangeListeners, and it can fire an event to them on behalf of other components. The other components either identify themselves (see method fire(Object,String,Object)), or they use this channel for firing anonymous messages (see method fire(String,Object)) - in which case the message source will be the property channel itself.

The events that were put here (those coming by the put(java.lang.Object, java.lang.Object) method) are stored here under their names. That means that you can always get the last stored event of a particular name. Concrete property names are of no interest for the channel, but they are definitely needed to be agreed on (using controlled vocabularies) - see, for example, ontologies defined in DataConsumer.

Version:

$Id: PropertyChannel.html 19678 2010-07-23 23:41:44Z jbmorales $

Author:

Martin Senger

See Also:

A tutorial: How to create and use Data Consumers

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener l) Register a listener.
boolean	containsKey(java.lang.Object key) Return true if this channel contains property with the given 'key'.
void	fire(java.lang.Object source, java.lang.String key, java.lang.Object value) Fire an event to any registered listeners.
void	fire(java.lang.String key, java.lang.Object value) Fire an event to any registered listeners.
java.lang.Object	get(java.lang.Object key) Returns a value stored in this channel under given 'key'.
boolean	getBoolean(java.lang.Object key, boolean defaultValue) A convenient method returning a boolean value of the given property.
java.lang.String	getString(java.lang.Object key) A convenient method returning value of the given property as a string.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Maps the specified key to the specified value in the channel.
java.lang.Object	put(java.lang.Object source, java.lang.Object key, java.lang.Object value) Maps the specified key to the specified value in this channel.
java.lang.Object	remove(java.lang.Object key) Remove a property given by 'key' from this channel.
void	removePropertyChangeListener(java.beans.PropertyChangeListener l) Unregister a listener.

Method Detail

put

java.lang.Object put(java.lang.Object key,
                     java.lang.Object value)

Maps the specified key to the specified value in the channel. Neither the key nor the value can be null.

The given value, apart from being stored, is also propagated by firing a property change event (this is called a channel push style). The event is anonymous. If a component needs to identify itself as the source of the message, it uses instead put(Object,Object,Object).

Parameters:

key - is a property name

value - is a property value

Returns:

the previous value of the specified name stored in this channel, or null if it does not contain one

put

java.lang.Object put(java.lang.Object source,
                     java.lang.Object key,
                     java.lang.Object value)

Maps the specified key to the specified value in this channel. Neither the key nor the value can be null.

The given value, apart from being stored, is also propagated by firing a property change event (this is called a channel push style). The event contains also its 'source'. For event sent anonymously, use instead put(Object,Object).

Parameters:

source - is a component that is putting here this property

key - is a property namekey

value - is a property value

Returns:

the previous value of the specified name stored in this channel, or null if it does not contain one

get

java.lang.Object get(java.lang.Object key)

Returns a value stored in this channel under given 'key'.

Parameters:

key - is a property name

Returns:

the stored value, or null if there are no property with the given 'key'

containsKey

boolean containsKey(java.lang.Object key)

Return true if this channel contains property with the given 'key'.

Parameters:

key - is a property name

remove

java.lang.Object remove(java.lang.Object key)

Remove a property given by 'key' from this channel.

Parameters:

key - is a property name

Returns:

the value of the property being just removed, or null if there was not such property

getString

java.lang.String getString(java.lang.Object key)

A convenient method returning value of the given property as a string. It usually makes sense only for properties with value of type String.

Parameters:

key - is a property name

Returns:

a stringified version of the given property, or an empty string if the property does not exist

getBoolean

boolean getBoolean(java.lang.Object key,
                   boolean defaultValue)

A convenient method returning a boolean value of the given property. It usually makes sense only for properties with boolean value.

Parameters:

key - is a property name

defaultValue - to be returned in some cases

Returns:

a boolean version of the property value, or return 'defaultValue' if such property does not exist

fire

void fire(java.lang.String key,
          java.lang.Object value)

Fire an event to any registered listeners. The source of this event will be this channel.

Note that this event is just fired but not stored here. If you need to store it, as well, use the put(Object,Object) method.

Parameters:

key - is a name of the fired event

value - is a value associated with this event

fire

void fire(java.lang.Object source,
          java.lang.String key,
          java.lang.Object value)

Fire an event to any registered listeners. The source of this event will be the 'source'.

Note that this event is just fired but not stored here. If you need to store it, as well, use the put(Object,Object,Object) method.

Parameters:

source - that initiated the event

key - is a name of the fired event

value - is a value associated with this event

addPropertyChangeListener

void addPropertyChangeListener(java.beans.PropertyChangeListener l)

Register a listener.

removePropertyChangeListener

void removePropertyChangeListener(java.beans.PropertyChangeListener l)

Unregister a listener.