javax.infobus
Interface InfoBusDataController


public abstract interface InfoBusDataController

Custom implementations of InfoBusDataController can be added to an InfoBus to optimize the distribution of InfoBusEvents to InfoBusDataProducers and InfoBusDataConsumers.

Internally, an InfoBus maintains a set of InfoBusDataControllers that are active on the bus and passes an incoming request to each of them until notified that further distribution is unnecessary (via getStopFlag). The set of controllers will always contain a DefaultController, which is always the last to receive requests that have not been handled by another controller.

See Also:
InfoBusEventListener, InfoBus

Method Summary
 void addDataConsumer(InfoBusDataConsumer consumer)
          Called by the InfoBus each time an InfoBusDataConsumer joins the InfoBus after the DataController did, to update the DataController of the addition of the consumer.
 void addDataProducer(InfoBusDataProducer producer)
          Called by the InfoBus each time an InfoBusDataProducer joins the InfoBus after the DataController did, to update the DataController of the addition of the producer.
 boolean findDataItem(java.lang.String dataItemName, java.awt.datatransfer.DataFlavor[] flavors, InfoBusDataConsumer consumer, java.util.Vector foundItem)
          Called by the InfoBus when a consumer wishes to find a DataItem matching the given dataItemName.
 boolean findMultipleDataItems(java.lang.String dataItemName, java.awt.datatransfer.DataFlavor[] flavors, InfoBusDataConsumer consumer, java.util.Vector foundItems)
          Called by the InfoBus when a consumer wishes to find ALL DataItems matching the given dataItemName.
 boolean fireItemAvailable(java.lang.String dataItemName, java.awt.datatransfer.DataFlavor[] flavors, InfoBusDataProducer source)
          Called by the InfoBus when the producer "source" requests the distribution of an InfoBusItemAvailable event to consumers on the InfoBus.
 boolean fireItemRevoked(java.lang.String dataItemName, InfoBusDataProducer producer)
          Called by the InfoBus when a producer requests the distribution of an InfoBusItemRevoked event to consumers on the InfoBus.
 void removeDataConsumer(InfoBusDataConsumer consumer)
          Called by the InfoBus each time an InfoBusDataConsumer leaves the InfoBus to alert the DataController of the change.
 void removeDataProducer(InfoBusDataProducer producer)
          Called by the InfoBus each time an InfoBusDataProducer leaves the InfoBus to alert the DataController of the change.
 void setConsumerList(java.util.Vector consumers)
          Called once by the InfoBus when the DataController adds itself.
 void setProducerList(java.util.Vector producers)
          Called once by the InfoBus when the DataController adds itself.
 

Method Detail

setConsumerList

public void setConsumerList(java.util.Vector consumers)
Called once by the InfoBus when the DataController adds itself. Presents the DataController with the InfoBus's consumer list, which at that point contains the consumers that joined the bus before the controller did. The DataController should make a copy reference to any consumers that it wishes to manage.
Parameters:
consumers - the Vector of InfoBusDataConsumers held by the InfoBus when the DataController added itself to the bus

setProducerList

public void setProducerList(java.util.Vector producers)
Called once by the InfoBus when the DataController adds itself. Presents the DataController with the InfoBus's producer list, which at that point contains the producers that joined the bus before the controller did. The DataController should make a copy reference to any producers that it wishes to manage.
Parameters:
producers - the Vector of InfoBusDataProducers held by the InfoBus when the DataController added itself to the bus

addDataConsumer

public void addDataConsumer(InfoBusDataConsumer consumer)
Called by the InfoBus each time an InfoBusDataConsumer joins the InfoBus after the DataController did, to update the DataController of the addition of the consumer. If the DataController wishes to manage the new consumer it should add a reference to its own private consumer list.
Parameters:
consumer - the DataConsumer now joining the InfoBus

addDataProducer

public void addDataProducer(InfoBusDataProducer producer)
Called by the InfoBus each time an InfoBusDataProducer joins the InfoBus after the DataController did, to update the DataController of the addition of the producer. If the DataController wishes to manage the new producer it should add a reference to its own private producer list.
Parameters:
producer - the DataProducer now joining the InfoBus

removeDataConsumer

public void removeDataConsumer(InfoBusDataConsumer consumer)
Called by the InfoBus each time an InfoBusDataConsumer leaves the InfoBus to alert the DataController of the change. The DataController must remove all references to the consumer from its private lists and ensure that the controller sends no further InfoBusEvents to the consumer.
Parameters:
consumer - the DataConsumer that is leaving the InfoBus

removeDataProducer

public void removeDataProducer(InfoBusDataProducer producer)
Called by the InfoBus each time an InfoBusDataProducer leaves the InfoBus to alert the DataController of the change. The DataController must remove all references to the producer from its private lists and ensure that the controller sends no further InfoBusEvents to the producer.
Parameters:
producer - the DataProducer that is leaving the InfoBus

fireItemAvailable

public boolean fireItemAvailable(java.lang.String dataItemName,
                                 java.awt.datatransfer.DataFlavor[] flavors,
                                 InfoBusDataProducer source)
Called by the InfoBus when the producer "source" requests the distribution of an InfoBusItemAvailable event to consumers on the InfoBus. The DataController decides whether any of the consumers it is managing are potential targets for the Available event, and calls one of the two target-specific fireItemAvailable methods on its InfoBus to create and send the event to those consumers.

Note that the DataController should copy the source field it receives to any target-specific method that the controller calls

Parameters:
dataItemName - the name of the DataItem made available by source
flavors - the DataFlavors the source makes available (optional, possibly null)
source - the Producer offering the DataItem
Returns:
Stop Code: if true, do not process this request further; if false, continue to next DataController
See Also:
InfoBus.fireItemAvailable(java.lang.String, java.awt.datatransfer.DataFlavor[], javax.infobus.InfoBusDataProducer)

fireItemRevoked

public boolean fireItemRevoked(java.lang.String dataItemName,
                               InfoBusDataProducer producer)
Called by the InfoBus when a producer requests the distribution of an InfoBusItemRevoked event to consumers on the InfoBus. The DataController decides whether any of the consumers it is managing are potential targets for the Revoked event, and calls one of the two target-specific fireItemRevoked methods on its InfoBus to create and send the event to those consumers.

Note that the DataController should copy the source field it receives to any target-specific method that the controller calls

Parameters:
dataItemName - the name of the DataItem being revoked by source
producer - the Producer no longer offering the DataItem
Returns:
Stop Code: if true, do not process this request further; if false, continue to next DataController
See Also:
InfoBus.fireItemRevoked(java.lang.String, javax.infobus.InfoBusDataProducer)

findDataItem

public boolean findDataItem(java.lang.String dataItemName,
                            java.awt.datatransfer.DataFlavor[] flavors,
                            InfoBusDataConsumer consumer,
                            java.util.Vector foundItem)
Called by the InfoBus when a consumer wishes to find a DataItem matching the given dataItemName. The DataController decides whether any of the producers it is managing are potential sources for the requested data, and issues an InfoBusItemRequestedEvent to them by calling one of the target-specific findDataItem methods on its InfoBus. The first non-null response should be stored in foundItem; the InfoBus only retrieves element 0 from foundItem; any other objects stored there are ignored.

If the DataController returns a DataItem from this method, the InfoBus will stop seeking the data and return that DataItem (calling no other controllers). If foundItem is empty when the call completes, the InfoBus uses the boolean return value to determine whether to continue polling controllers: if true, polling stops and null is returned to the consumer.

Parameters:
dataItemName - the name of the DataItem that the consumer is seeking
flavors - the DataFlavors the consumer prefers (optional, possibly null)
consumer - the Consumer seeking the data
foundItem - a Vector for storing the result which will be empty when the method is called
Returns:
Stop Code: if true, do not process this request further; if false, continue to next DataController. Ignored if foundDataItem is not empty.
See Also:
InfoBus.findDataItem(java.lang.String, java.awt.datatransfer.DataFlavor[], javax.infobus.InfoBusDataConsumer)

findMultipleDataItems

public boolean findMultipleDataItems(java.lang.String dataItemName,
                                     java.awt.datatransfer.DataFlavor[] flavors,
                                     InfoBusDataConsumer consumer,
                                     java.util.Vector foundItems)
Called by the InfoBus when a consumer wishes to find ALL DataItems matching the given dataItemName. The DataController decides whether any of the producers it is managing are potential sources for the requested data, and issues an InfoBusItemRequestedEvent to each by calling a target-specific findDataItem method on its InfoBus.

All non-null responses should be stored in the foundItems Vector. The responses returned by this controller will be concatenated with those of the controllers called before and after this one. If the return value is true, no further controllers will be polled.

Parameters:
dataItemName - the name of the DataItem that the consumer is seeking
flavors - the DataFlavors the consumer prefers (optional, possibly null)
consumer - the Consumer seeking the data
foundItems - a Vector for storing all non-null results; will be empty when the method is called
Returns:
Stop Code: if true, do not process this request further; if false, continue to next DataController.
See Also:
InfoBus.findDataItem(java.lang.String, java.awt.datatransfer.DataFlavor[], javax.infobus.InfoBusDataConsumer)