com.caplin.datasource

Interface DataSource

public interface DataSource

This is the main interface of DataSource for Java. To use the functionality provided by DataSource, your application must obtain an instance of this interface by calling one of the createDataSource() methods of DataSourceFactory.

The following example illustrates how to construct a DataSource.

import java.util.logging.Logger;

import com.caplin.datasource.DataSource;
import com.caplin.datasource.DataSourceFactory;

public class ExampleDataSource
{
        @SuppressWarnings("unused")
        public static void main(String[] args)
        {
                // Construct a DataSource instance using the factory and a logger
                
                Logger myLogger = Logger.getLogger(ExampleDataSource.class.getName());
                
                // The constructed DataSource uses configuration in conf/DataSource.xml
                // and record fieldnames defined in conf/Fields.xml
                
                DataSource myDataSource = DataSourceFactory.createDataSource("conf/DataSource.xml", "conf/Fields.xml", myLogger);
        }
}

Method Summary

Methods

Modifier and Type	Method and Description
void	addChannelListener(Namespace namespace, ChannelListener channelListener) Registers a ChannelListener for a specified namespace.
void	addConnectionListener(ConnectionListener connectionListener) Adds a connection listener that receives status events about the state of the DataSource application's connection to other peers.
void	addGenericChannelListener(Namespace namespace, ChannelListener channelListener) Registers a ChannelListener for a specified namespace.
ActivePublisher	createActivePublisher(Namespace namespace, DataProvider dataProvider) Creates an ActivePublisher for the specified namespace.
ActiveSubscription	createActiveSubscription(java.lang.String subject, SubscriptionListener subscriptionListener) Creates an active subscription to an individual subject.
BroadcastPublisher	createBroadcastPublisher(Namespace namespace) Creates a BroadcastPublisher for the specified namespace.
BroadcastSubscription	createBroadcastSubscription(Namespace namespace, SubscriptionListener subscriptionListener) Creates a subscription to many subjects.
CompatibilityPublisher	createCompatibilityPublisher(Namespace namespace, DataProvider dataProvider) Creates a CompatibilityPublisher for the specified namespace.
java.lang.String	getCommandOption(java.lang.String defaultValue, java.lang.String... commandOptionNames) Retrieves the value of a DataSource command option.
DataSourceConfiguration	getConfiguration() Retrieves configuration on datasource.conf file
FieldManager	getFieldManager() Gets the datasource field manager
java.util.logging.Logger	getLogger() Gets the logger used by DataSource for Java.
javax.management.MBeanServer	getMBeanServer() Retrieves the MBeanServer used for JMX monitoring by the DataSource.
java.util.Set<Peer>	getPeers() Retrieves a set of all peers configured to connect to this DataSource.
java.util.List<Peer>	getPeersInOrder() Retrieves a list of all peers configured to connect to this DataSource.
void	removeConnectionListener(ConnectionListener connectionListener) Removes a previously registered connection listener.
void	setStatusDown() Causes the DataSource to disconnect and stop listening for connections.
void	setStatusUp() Causes the DataSource to reconnect and listen for connections.
void	start() Starts this DataSource.
void	stop() Stops this DataSource.

Method Detail

start

void start()

Starts this DataSource. Following a call to this method, DataSource for Java starts connecting to its peers. The method immediately returns with DataSource running in a background thread. You should take care to ensure that your application does not exit immediately after calling start().

Throws:

java.lang.UnsupportedOperationException - If this method is called after stop() has been called. It is not possible to restart a DataSource for Java instance once it has been stopped.

stop

void stop()

Stops this DataSource. Following a call to this method, DataSource for Java disconnects from all of its peers. This method places the DataSource for Java instance in a terminal state from which it cannot be restarted.

addConnectionListener

void addConnectionListener(ConnectionListener connectionListener)

Adds a connection listener that receives status events about the state of the DataSource application's connection to other peers.

Once registered, the ConnectionListener will receive event updates whenever the connection status has changed (for details see the description of ConnectionListener).

You can register more than one ConnectionListener with DataSource. Each registered ConnectionListener will receive events for changes to all peers' connection statuses.

Parameters:

connectionListener - The ConnectionListener to be registered.

removeConnectionListener

void removeConnectionListener(ConnectionListener connectionListener)

Removes a previously registered connection listener.

Once removed, the ConnectionListener will no longer receive event updates whenever the connection status has changed.

Parameters:

connectionListener - The ConnectionListener to be removed.

createCompatibilityPublisher

CompatibilityPublisher createCompatibilityPublisher(Namespace namespace,
                                                  DataProvider dataProvider)

Creates a CompatibilityPublisher for the specified namespace.

A CompatibilityPublisher is similar to an ActivePublisher except that it requires you to maintain a count of how many peers are subscribed to each subject. Because it does not maintain a cache, this Publisher passes all requests and discards for such subjects on to the DataProvider. For details, see the description of CompatibilityPublisher.

Note: The use of CompatibilityPublisher is not recommended; use ActivePublisher instead.

CompatibilityPublisher is provided for backwards compatibility with versions of DataSource for Java prior to 5.0, which require you to manage peers yourself. You may want to use this publisher if you are upgrading an existing DataSource application that contains such peer management logic.

Parameters:

namespace - The Namespace associated with this publisher.

dataProvider - The DataProvider that can publish data via this publisher.

Returns:

A CompatibilityPublisher for the supplied Namespace.

createActivePublisher

ActivePublisher createActivePublisher(Namespace namespace,
                                    DataProvider dataProvider)

Creates an ActivePublisher for the specified namespace.

An ActivePublisher publishes updates that are for subjects within the specified Namespace, to all peers that have subscribed to those subjects.

Parameters:

namespace - The Namespace associated with this publisher.

dataProvider - The DataProvider that can publish data via this publisher.

Returns:

An ActivePublisher for the supplied Namespace.

createBroadcastPublisher

BroadcastPublisher createBroadcastPublisher(Namespace namespace)

Creates a BroadcastPublisher for the specified namespace.

A BroadcastPublisher permits a DataSource to broadcast, to all connected peers, updates that are for subjects within the specified Namespace.

Parameters:

namespace - The Namespace associated with this publisher.

Returns:

A BroadcastPublisher for the supplied Namespace.

addChannelListener

void addChannelListener(Namespace namespace,
                      ChannelListener channelListener)

Registers a ChannelListener for a specified namespace.

Parameters:

namespace - The Namespace.

channelListener - The channel listener for the supplied Namespace.

addGenericChannelListener

void addGenericChannelListener(Namespace namespace,
                             ChannelListener channelListener)

Registers a ChannelListener for a specified namespace. To be used only for Generic Messages.

Parameters:

namespace - The Namespace.

channelListener - The channel listener for the supplied Namespace.

createActiveSubscription

ActiveSubscription createActiveSubscription(java.lang.String subject,
                                          SubscriptionListener subscriptionListener)

Creates an active subscription to an individual subject.

If a data service has been configured that matches the given subject and active peers within that data service are connected, a request will be made to those peers for the specified subject.

All events whose subjects match the method's subject parameter are passed to the given SubscriptionListener.

Parameters:

subject - The subject to subscribe to.

subscriptionListener - A listener to receive events raised for the ActiveSubscription.

Returns:

An ActiveSubscription.

createBroadcastSubscription

BroadcastSubscription createBroadcastSubscription(Namespace namespace,
                                                SubscriptionListener subscriptionListener)

Creates a subscription to many subjects. The scope of the subscription is defined by a Namespace; all events whose subjects match the given Namespace are passed to the given SubscriptionListener.

Parameters:

namespace - The Namespace defining the subjects to subscribe to.

subscriptionListener - A listener to receive events raised for the BroadcastSubscription.

Returns:

A BroadcastSubscription.

getCommandOption

java.lang.String getCommandOption(java.lang.String defaultValue,
                                java.lang.String... commandOptionNames)

Retrieves the value of a DataSource command option. Command options can be stored in DataSource for Java by creating them using one of the factory methods that take an array of arguments; either DataSourceFactory.createDataSource(String[]) or DataSourceFactory.createDataSource(String[], Logger). Typically your application would obtain the command options from the command line used to launch the DataSource application, and pass them to the appropriate createDataSource factory method. DataSource for Java then parses the options from the argument array and makes them available by calling the getCommandOption method.

For an example of how to construct a DataSource with an argument array containing options, and subsequently retrieve the options from the DataSource, see DataSourceFactory.createDataSource(String[], Logger).

Parameters:

defaultValue - The value to return if no value is stored for any of the option names provided.

commandOptionNames - One or more command option names to retrieve a value for. This parameter takes any number of strings in order to help you retrieve a value when there are multiple aliases for the same option. For example, if a command option has a short name "f" and a long name "fields-file" you can pass both of these names into this parameter and if either of them exists, the corresponding value will be returned.

Returns:

The value defined in the matching command option name, or the default value (see defaultValue parameter) if there is no value for any of the command option names provided.

getPeers

java.util.Set<Peer> getPeers()

Retrieves a set of all peers configured to connect to this DataSource. Peer connections are specified in the DataSource configuration file.

Returns:

A set of Peer objects.

getPeersInOrder

java.util.List<Peer> getPeersInOrder()

Retrieves a list of all peers configured to connect to this DataSource. Peer connections are specified in the DataSource configuration file.

Returns:

A list of Peer objects in the order they were added in the config file

setStatusUp

void setStatusUp()

Causes the DataSource to reconnect and listen for connections.

setStatusDown

void setStatusDown()

Causes the DataSource to disconnect and stop listening for connections.

getMBeanServer

javax.management.MBeanServer getMBeanServer()

Retrieves the MBeanServer used for JMX monitoring by the DataSource. The configuration properties for JMX monitoring are read from the DataSource configuration file.

Returns:

The instance of MBeanServer used by the DataSource.

getLogger

java.util.logging.Logger getLogger()

Gets the logger used by DataSource for Java.

Returns:

The logger.

getConfiguration

DataSourceConfiguration getConfiguration()

Retrieves configuration on datasource.conf file

Returns:

DataSourceConfiguration object

getFieldManager

FieldManager getFieldManager()

Gets the datasource field manager

Returns:

FieldManager