All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class javax.infobus.InfoBus 

java.lang.Object
   |
   +----javax.infobus.InfoBus
public final class InfoBus
extends Object
implements PropertyChangeListener
An InfoBus object maintains a list of InfoBusMembers that have attached to it and enables communication among those members. Using methods on the InfoBus object, members create InfoBusEvents which are distributed to other members to request, announce, and revoke data items.

The InfoBus supports a flexible security module called the InfoBusPolicyHelper that determines which, if any, methods called on the InfoBus perform permission checking. If the policy helper in use determines that a caller does not have the proper security clearance to perform the requested action, it will throw a RuntimeException. Note that all methods on the InfoBus are potentially subject to the policy helper's inspection.

InfoBusMembers should not new an InfoBus, but should call InfoBus.get to find the InfoBus they need.

Version:
$Revision: 1.24.1.2 $ $Date: 16 Mar 1998 12:04:58 $
See Also:
get

Variable Index

o HIGH_PRIORITY
A priority for a data controller.
o LOW_PRIORITY
A priority for a data controller.
o MEDIUM_PRIORITY
A priority for a data controller.
o MONITOR_PRIORITY
A priority for a data controller.
o VERY_HIGH_PRIORITY
A priority for a data controller.
o VERY_LOW_PRIORITY
A priority for a data controller.

Method Index

o addDataConsumer(InfoBusDataConsumer)
Registers an InfoBusDataConsumer on the InfoBus, so that the consumer can receive announcements of data availability via InfoBusItemAvailableEvents and InfoBusItemRevokedEvents.
o addDataController(InfoBusDataController, int)
Registers the InfoBusDataController on the InfoBus, adding it to a list of controllers sorted by priority.
o addDataProducer(InfoBusDataProducer)
Registers an InfoBusDataProducer on the InfoBus, so that the producer can receive request notifications from consumers in the form of InfoBusItemRequestedEvents.
o findDataItem(String, DataFlavor[], InfoBusDataConsumer)
Seeks a DataItem for a given data item name, by creating an InfoBusItemRequestedEvent and distributing it to producers on the bus.
o findDataItem(String, DataFlavor[], InfoBusDataConsumer, InfoBusDataProducer)
Seeks a named DataItem only from a named target producer.
o findDataItem(String, DataFlavor[], InfoBusDataConsumer, Vector)
Requests data from a Vector of producers.
o findMultipleDataItems(String, DataFlavor[], InfoBusDataConsumer)
Seeks all available data items for a specified data item name.
o fireItemAvailable(String, DataFlavor[], InfoBusDataProducer)
Announces the availability of a DataItem, by creating an InfoBusItemAvailableEvent and sending it to all registered InfoBusDataConsumers.
o fireItemAvailable(String, DataFlavor[], InfoBusDataProducer, InfoBusDataConsumer)
Creates an InfoBusItemAvailableEvent and sends it to the specified InfoBusDataConsumer.
o fireItemAvailable(String, DataFlavor[], InfoBusDataProducer, Vector)
Creates an InfoBusItemAvailableEvent and sends it to all InfoBusDataConsumers in the targets Vector.
o fireItemRevoked(String, InfoBusDataProducer)
Notifies consumers that a DataItem is being revoked and will no longer be available from the given source.
o fireItemRevoked(String, InfoBusDataProducer, InfoBusDataConsumer)
Creates an InfoBusItemRevokedEvent and sends it to the specified InfoBusDataConsumer.
o fireItemRevoked(String, InfoBusDataProducer, Vector)
Creates an InfoBusItemRevokedEvent and sends it to all InfoBusDataConsumers in the targets Vector.
o get(Component)
Returns the default InfoBus for a component.
o get(String)
Returns a named InfoBus.
o getName()
Returns the String used as the unique identifier for this InfoBus.
o join(InfoBusMember)
Attaches an InfoBusMember to the InfoBus on which the method was called.
o leave(InfoBusMember)
Removes an InfoBusMember from the InfoBus.
o propertyChange(PropertyChangeEvent)
Accepts notifications of an InfoBus change via a PropertyChangeEvent.
o register(InfoBusMember)
Registers an InfoBusMember on the InfoBus's list of active members, and also causes the InfoBus to register itself as a PropertyChangeListener on the InfoBusMember's InfoBus property.
o release()
Releases the artificial reference to an InfoBus instance set by calling get().
o removeDataConsumer(InfoBusDataConsumer)
Removes an InfoBusDataConsumer from the distribution list for InfoBusItemAvailableEvents and InfoBusItemRevokedEvents.
o removeDataController(InfoBusDataController)
Removes a controller from the list of registered InfoBusDataControllers on this InfoBus.
o removeDataProducer(InfoBusDataProducer)
Removes an InfoBusDataProducer from the distribution list for InfoBusItemRequestedEvents.

Variables

o MONITOR_PRIORITY 
 public static final int MONITOR_PRIORITY
A priority for a data controller.

o VERY_HIGH_PRIORITY 
 public static final int VERY_HIGH_PRIORITY
A priority for a data controller.

o HIGH_PRIORITY 
 public static final int HIGH_PRIORITY
A priority for a data controller.

o MEDIUM_PRIORITY 
 public static final int MEDIUM_PRIORITY
A priority for a data controller.

o LOW_PRIORITY 
 public static final int LOW_PRIORITY
A priority for a data controller.

o VERY_LOW_PRIORITY 
 public static final int VERY_LOW_PRIORITY
A priority for a data controller.

Methods

o getName 
 public String getName()
Returns the String used as the unique identifier for this InfoBus. When an InfoBusMember joins its InfoBus, this bus name is either specified or it is calculated automatically. If calculated automatically, the bus name is based on DocumentBase, which guarantees that all InfoBusMembers on the same HTML page are assigned to the same InfoBus.

Returns:
the unique bus name for this InfoBus
o get 
 public static synchronized InfoBus get(Component component)
Returns the default InfoBus for a component. Determines the default bus name from the given component and then searches for an existing InfoBus with that bus name and returns it, or, if a match does not exist, creates a new InfoBus with that bus name and returns it.

The get() method introduces an artificial reference to the InfoBus to ensure that it is kept alive until a member joins it. This artificial reference must be released by calling the release() method on this class after the InfoBus has been used for a join or setInfoBus.

Parameters:
component - The java.awt.Component on which to base the default name
Returns:
the InfoBus having the name determined from the component
o get 
 public static synchronized InfoBus get(String busName)
Returns a named InfoBus. Searches for an existing InfoBus with the specified busName and returns it if found; if none is found, creates and returns a new InfoBus labeled with the busName.

Named infobuses are useful for builder environments, for classes that are not Components, and for applications that wish to specify security constraints on particular buses by name.

The get() method introduces an artificial reference to the InfoBus to ensure that it is kept alive until a member joins it. This artificial reference must be released by calling the release() method on this class after the InfoBus has been used for a join or setInfoBus.

Parameters:
busName - the unique identifier for the InfoBus being requested
Returns:
the InfoBus matching the busName identifier
Throws: IllegalArgumentException
indicates an illegal name that begins with the dash ('-') character or contains the asterisk ('*') character. Other reserved characters may be restricted but not checked, including percent ('%')
o release 
 public synchronized void release()
Releases the artificial reference to an InfoBus instance set by calling get(). It must be called after join and/or setInfoBus attempts using the InfoBus instance have completed. If there are no registered members, event listeners, or data controllers for this InfoBus instance, this method allows this InfoBus instance to be garbage-collected.

o join 
 public synchronized void join(InfoBusMember member) throws PropertyVetoException
Attaches an InfoBusMember to the InfoBus on which the method was called. The InfoBus calls the InfoBusMember's setInfoBus() method to set itself as the value for the member's InfoBus property.

The join method is typically called by the InfoBusMember wishing to join an InfoBus, after it has obtained an InfoBus instance by calling the get() method.

Parameters:
member - the InfoBusMember to attach to the InfoBus
Throws: PropertyVetoException
if calling member.setInfoBus throws a PropertyVetoException
Throws: StaleInfoBusException
if join is called on a stale InfoBus -- one that was declared inactive and is no longer available to other members. In response to this exception, the member should perform a new InfoBus.get() to get a replacement for the stale InfoBus using the desired bus name.
o register 
 public synchronized void register(InfoBusMember member)
Registers an InfoBusMember on the InfoBus's list of active members, and also causes the InfoBus to register itself as a PropertyChangeListener on the InfoBusMember's InfoBus property. The InfoBus reverses these steps when the member calls the leave method. These tracking methods are used to free unused InfoBuses safely from system resources.

The register method must be called by an InfoBusMember's setInfoBus method (unless the setInfoBus was vetoed).

Parameters:
member - the member to add to the active member list
Throws: StaleInfoBusException
if the InfoBus on which the register() was called is stale -- inactive and unavailable to other callers. When register is being called by setInfoBus, the setInfoBus should normally NOT catch the StaleInfoBusException.
o propertyChange 
 public void propertyChange(PropertyChangeEvent event)
Accepts notifications of an InfoBus change via a PropertyChangeEvent. The PropertyChangeEvent must be constructed with the String "InfoBus" as its property name, and the InfoBusMember as its source.

Parameters:
event - encapsulates the InfoBusMember having its InfoBus property changed, and the property's old and new values
o leave 
 public synchronized void leave(InfoBusMember member) throws PropertyVetoException
Removes an InfoBusMember from the InfoBus. An InfoBusMember that wishes to remove itself from the InfoBus does so by calling leave(). The InfoBus that has its leave() method called calls the setInfoBus method with null on the InfoBusMember specified as the member parameter, and removes itself as a listener on the member.

Parameters:
member - the InfoBusMember which is disconnecting from the InfoBus
Throws: PropertyVetoException
if a VetoableChangeListener watching the member's InfoBus property objects to setting the property to null
o addDataController 
 public synchronized void addDataController(InfoBusDataController controller,
                                            int priority) throws InfoBusMembershipException
Registers the InfoBusDataController on the InfoBus, adding it to a list of controllers sorted by priority. When a consumer or producer action occurs, the InfoBus polls each controller in turn until directed not to continue.

Parameters:
controller - the controller to be added to the bus
priority - the priority of the controller for sorting purposes; should be one of the following:
  • InfoBus.MONITOR_PRIORITY
    Note that controllers added at MONITOR_PRIORITY have results and StopFlag ignored
  • InfoBus.VERY_HIGH_PRIORITY
  • InfoBus.HIGH_PRIORITY
  • InfoBus.MEDIUM_PRIORITY
  • InfoBus.LOW_PRIORITY
  • InfoBus.VERY_LOW_PRIORITY
Priorities that fall outside the range of these constants are truncated before adding the controller, with anything higher than MONITOR_PRIORITY truncated to VERY_HIGH_PRIORITY (because of MONITOR's restrictions)

Throws: InfoBusMembershipException
if the controller is already present
Throws: StaleInfoBusException
if called on a stale InfoBus -- one that was declared inactive and is no longer available to other members.
See Also:
InfoBusDataController
o removeDataController 
 public synchronized void removeDataController(InfoBusDataController controller)
Removes a controller from the list of registered InfoBusDataControllers on this InfoBus. No effect if the controller is not registered.

Parameters:
controller - the controller to be removed
o addDataProducer 
 public synchronized void addDataProducer(InfoBusDataProducer producer)
Registers an InfoBusDataProducer on the InfoBus, so that the producer can receive request notifications from consumers in the form of InfoBusItemRequestedEvents.

Parameters:
producer - the producer to add to the InfoBusItemRequestedEvent distribution list
Throws: StaleInfoBusException
if called on a stale InfoBus -- one that was declared inactive and is no longer available to other members.
o removeDataProducer 
 public synchronized void removeDataProducer(InfoBusDataProducer producer)
Removes an InfoBusDataProducer from the distribution list for InfoBusItemRequestedEvents.

Parameters:
producer - the producer that no longer wishes to receive InfoBus request notifications
o addDataConsumer 
 public synchronized void addDataConsumer(InfoBusDataConsumer consumer)
Registers an InfoBusDataConsumer on the InfoBus, so that the consumer can receive announcements of data availability via InfoBusItemAvailableEvents and InfoBusItemRevokedEvents.

Parameters:
consumer - the consumer to add to the distribution list for the above Events
Throws: StaleInfoBusException
if called on a stale InfoBus -- one that was declared inactive and is no longer available to other members.
o removeDataConsumer 
 public synchronized void removeDataConsumer(InfoBusDataConsumer consumer)
Removes an InfoBusDataConsumer from the distribution list for InfoBusItemAvailableEvents and InfoBusItemRevokedEvents.

Parameters:
consumer - the consumer that no longer wishes to receive InfoBus notifications
o fireItemAvailable 
 public void fireItemAvailable(String dataItemName,
                               DataFlavor flavors[],
                               InfoBusDataProducer source)
Announces the availability of a DataItem, by creating an InfoBusItemAvailableEvent and sending it to all registered InfoBusDataConsumers. Called by an InfoBusEventListener acting as a data source.

Each consumer that wants the DataItem uses one of the findDataItem methods, resulting in the source's requestDataItem method being called to retrieve the data.

Parameters:
dataItemName - the name of the DataItem being offered
flavors - the flavors of data the producer wishes to supply. Producers can use null if they don’t care to describe the data.
source - the producer that can provide the DataItem
o fireItemRevoked 
 public void fireItemRevoked(String dataItemName,
                             InfoBusDataProducer source)
Notifies consumers that a DataItem is being revoked and will no longer be available from the given source. The InfoBus creates an InfoBusItemRevokedEvent and distributes it to registered InfoBusConsumers.

The InfoBus requires that when an available event for a particular data item name and producer is fired, it must be received by all listeners before the corresponding revoked event (i.e., a revoked event from the same producer with the same data item name) is fired. In order to guarantee that this requirement is met, before firing the available event, the producer must temporarily disable its ability to send the corresponding revoked event by using synchronization techniques appropriate for multithreaded operation.

This can be accomplished using a synchronization block around code that fires available and revoked events. In implementing this, a component must not specify its InfoBus as the parameter to the Java synchronized keyword, as this can cause a deadlock to occur.

Parameters:
dataItemName - the name of the DataItem being revoked
source - the producer that will no longer provide the data
o findDataItem 
 public Object findDataItem(String dataItemName,
                            DataFlavor flavors[],
                            InfoBusDataConsumer consumer)
Seeks a DataItem for a given data item name, by creating an InfoBusItemRequestedEvent and distributing it to producers on the bus. Called by an InfoBusDataConsumer.

A producer that has the requested data will put a data item for it in the event's dataItem field, and the InfoBus returns it to the caller. The InfoBus stops distributing the event as soon as a non-null response is received.

Parameters:
dataItemName - the name of the data item to request on the InfoBus
flavors - the consumer's preferred transfer flavors (optional, may be null)
consumer - the InfoBusMember making the request
Returns:
the DataItem corresponding to the name if anyone fulfilled the request, or null if no responses occurred
See Also:
findMultipleDataItems
o findMultipleDataItems 
 public Object[] findMultipleDataItems(String dataItemName,
                                       DataFlavor flavors[],
                                       InfoBusDataConsumer consumer)
Seeks all available data items for a specified data item name. Like findDataItem(String,InfoBusDataConsumer) except that the InfoBus here polls all Producers and returns an array of DataItems containing all responses. Returns null if no response.

Parameters:
dataItemName - the name of the data item to request on the InfoBus
flavors - the consumer's preferred transfer flavors (optional, may be null)
consumer - the InfoBusDataConsumer making the request
Returns:
all DataItems corresponding to the name if anyone fulfilled the request, or null if no responses occurred
See Also:
findDataItem
o findDataItem 
 public Object findDataItem(String dataItemName,
                            DataFlavor flavors[],
                            InfoBusDataConsumer consumer,
                            InfoBusDataProducer target)
Seeks a named DataItem only from a named target producer. Only the producer named as a parameter in the method call is asked for the DataItem. If the producer is obtained from a recent InfoBusItemAvailableEvent for the data item name, it is still possible (but unlikely) that the method returns null.

Parameters:
dataItemName - the name of the data item being requested
flavors - the consumer's preferred transfer flavors (optional, may be null)
consumer - the consumer making the request
target - the target producer to be queried for the data
Returns:
the requested data item, or null if the target does not fulfill the request
o findDataItem 
 public Object findDataItem(String dataItemName,
                            DataFlavor flavors[],
                            InfoBusDataConsumer consumer,
                            Vector targets)
Requests data from a Vector of producers. The Vector of target producers is copied, and then the request is sent to each producer (in the copied list) until a non-null response is received or the list is exhausted.

This method is primarily for use by data controllers.

Parameters:
dataItemName - the name of the data item being requested
flavors - the consumer's preferred transfer flavors (optional, may be null)
consumer - the consumer making the request
targets - a list of target producers to be queried for the data
Returns:
the requested data item, or null if not fulfilled
Throws: ClassCastException
if any object in targets is not an InfoBusDataProducer
See Also:
InfoBusDataController
o fireItemAvailable 
 public void fireItemAvailable(String dataItemName,
                               DataFlavor flavors[],
                               InfoBusDataProducer source,
                               InfoBusDataConsumer target)
Creates an InfoBusItemAvailableEvent and sends it to the specified InfoBusDataConsumer. This method is provided primarily for use by data controllers.

Parameters:
dataItemName - the name of the DataItem being offered
flavors - the flavors of data the producer wishes to supply. Producers can use null if they don’t care to describe the data.
source - the producer that can provide the DataItem
target - the consumer that receives the notification event
See Also:
InfoBusDataController
o fireItemAvailable 
 public void fireItemAvailable(String dataItemName,
                               DataFlavor flavors[],
                               InfoBusDataProducer source,
                               Vector targets)
Creates an InfoBusItemAvailableEvent and sends it to all InfoBusDataConsumers in the targets Vector. This method is provided primarily for use by data controllers.

Parameters:
dataItemName - the name of the DataItem being offered
flavors - the flavors of data the producer wishes to supply. Producers can use null if they don’t care to describe the data.
source - the producer that can provide the DataItem
targets - the list of target consumers to receive the event
Throws: ClassCastException
if any object in targets is not an InfoBusDataConsumer
See Also:
InfoBusDataController
o fireItemRevoked 
 public void fireItemRevoked(String dataItemName,
                             InfoBusDataProducer source,
                             InfoBusDataConsumer target)
Creates an InfoBusItemRevokedEvent and sends it to the specified InfoBusDataConsumer. This method is provided primarily for use by data controllers.

Parameters:
dataItemName - the name of the DataItem being offered
source - the producer that is revoking the DataItem
target - the consumer that will receive the notification event
See Also:
InfoBusDataController
o fireItemRevoked 
 public void fireItemRevoked(String dataItemName,
                             InfoBusDataProducer source,
                             Vector targets)
Creates an InfoBusItemRevokedEvent and sends it to all InfoBusDataConsumers in the targets Vector. This method is provided primarily for use by data controllers.

Parameters:
dataItemName - the name of the DataItem being offered
source - the producer that is revoking the DataItem
targets - the list of target consumers to receive the event
Throws: ClassCastException
if any object in targets is not an InfoBusDataConsumer
See Also:
InfoBusDataController 
All Packages  Class Hierarchy  This Package  Previous  Next  Index