Package 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 static from...() methods.

     

    The following example illustrates how to construct a DataSource. 

    import java.util.logging.Logger;

import com.caplin.datasource.DataSource;

public class ExampleDataSource
{
        @SuppressWarnings("unused")
        public static void main(String[] args)
        {
                // Construct a DataSource instance using a config file and a logger
                
                Logger myLogger = Logger.getLogger(ExampleDataSource.class.getName());
                
                // The constructed DataSource uses configuration in etc/datasource.conf
                
                DataSource myDataSource = DataSource.fromConfigFile("etc/datasource.conf", myLogger);
        }
}

    • 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().

        Note that the datasource starts with status UP by default. To start the datasource with status DOWN, call setStatusDown() before 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.

      • 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.

      • createActiveJsonSubscription

        <T> ActiveSubscription createActiveJsonSubscription​(java.lang.String subject,
                                                    SubjectConsumer<T> listener,
                                                    java.lang.Class<T> jsonDeserializationType)

        Creates an active subscription to an individual subject that returns Java objects from their serialized JSON form.

        To deserialize the JSON data a JsonHandler must have been installed (see getExtraConfiguration() and Configuration.setJsonHandler(JsonHandler)).

        Type Parameters:
        T - the Generic type of the object to deserialize the JSON to.
        Parameters:
        subject - The subject to subscribe to.
        listener - A listener to receive events raised for this subscription.
        jsonDeserializationType - the type of the object to deserialize the JSON to.
        Returns:
        An ActiveSubscription.

      • 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 fromArgs(String[]) or fromArgs(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 fromArgs(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

      • getExtraConfiguration

        Configuration getExtraConfiguration()
        Gets an object where extra programmatic configuration can be applied
        Returns:
        The instance of Configuration used by the DataSource.

      • getFieldManager

        FieldManager getFieldManager()
        Gets the datasource field manager
        Returns:
        FieldManager

      • main

        static void main​(java.lang.String[] args)

        Used to start the datasource and read the configuration file so the resultant configuration attribute values can be returned using the --get-config-value="attribute name" command line option.

        Parameters:
        args - An array of arguments containing command options. DataSource for Java understands both short command options of the form -key value and long command options of the form --key=value.

      • fromConfigString

        static DataSource fromConfigString​(java.lang.String configString,
                                   java.util.logging.Logger logger)

        Creates an instance of DataSource using the supplied configuration string and Logger.

        Parameters:
        configString - String containing the DataSource configuration.
        logger - The Logger to be used by DataSource for Java.
        Returns:
        The DataSource.
        Throws:
        java.lang.IllegalArgumentException - The configurationString is null.

      • fromConfigString

        static DataSource fromConfigString​(java.lang.String configString)

        Creates an instance of DataSource using the supplied configuration string.

        When this method is called, DataSource for Java creates a Logger using the logging configuration in the supplied DataSource configuration string.

        Parameters:
        configString - String containing the DataSource configuration.
        Returns:
        The DataSource.
        Throws:
        java.lang.IllegalArgumentException - The configurationString is null.

      • fromArgs

        static DataSource fromArgs​(java.lang.String[] args,
                           java.util.logging.Logger logger,
                           java.util.function.Function<java.lang.String,​java.lang.String> preprocessor)

        Creates an instance of DataSource using the supplied command options, Logger and preprocessor.

        The preprocessor Function will be called with the text loaded from the configuration file to allow user defined replacements to be applied before the text is parsed. Note: when include files are used the preprocessor will also be called for each include file.

        DataSource for Java parses the provided arguments into command options, which take the form of key/value pairs. DataSource for Java understands both short command options of the form -key value and long options of the form --key=value

        You can store arbitrary arguments in DataSource for Java and use them later in your own application code. However DataSource for Java also understands two built-in command options and will process them if they are found in the args array:

        Long Command Short Command Default Value Description
        config-file f etc/datasource.conf Path to a DataSource configuration file.

        For example:

        Long command option: --config-file=etc/datasource.conf

        Short command option: -f etc/datasource.conf

        If you set the a config option with the same name more than once, DataSource for Java will use the last occurrence of the option as the value.

        If you construct the DataSource using this method, you can retrieve the command option values by calling the getCommandOption(String, String...) method.

        Parameters:
        args - An array of arguments containing command options. DataSource for Java understands both short command options of the form -key value and long command options of the form --key=value.
        logger - The Logger to be used by DataSource for Java.
        preprocessor - A Function that takes a config string and returns the preprocessed string. Note: this function will be called several times if include files are used.
        Returns:
        The DataSource.
        Throws:
        java.lang.IllegalArgumentException - If the value of either args or logger is null.

      • fromArgs

        static DataSource fromArgs​(java.lang.String[] args,
                           java.util.logging.Logger logger)

        Creates an instance of DataSource using the supplied command options and Logger.

        Note: This is the recommended way to create your DataSource instance.

        When this method is called, DataSource for Java uses the provided Logger implementation for event logging. Packet logging must still be configured in the DataSource configuration file.

        DataSource for Java parses the provided arguments into command options, which take the form of key/value pairs. DataSource for Java understands both short command options of the form -key value and long options of the form --key=value

        You can store arbitrary arguments in DataSource for Java and use them later in your own application code. However DataSource for Java also understands two built-in command options and will process them if they are found in the args array:

        Long Command Short Command Default Value Description
        config-file f etc/datasource.conf Path to a DataSource configuration file.

        For example:

        Long command option: --config-file=etc/datasource.conf

        Short command option: -f etc/datasource.conf

        If you set the a config option with the same name more than once, DataSource for Java will use the last occurrence of the option as the value.

        If you construct the DataSource using this method, you can retrieve the command option values by calling the getCommandOption(String, String...) method.

        The following example shows how to construct a DataSource with an argument array containing command options, and how to subsequently retrieve the command options from the DataSource: 

        import java.util.logging.Logger;

import com.caplin.datasource.DataSource;

public class ArgumentProcessingWithLogger
{
        @SuppressWarnings("unused")
        public static void main(String[] args)
        {
                // Set up a custom logger
                Logger myLogger = Logger.getAnonymousLogger();
                
                // The args array containing the command options would generally be passed in
                // from the command line, but in this example we create the array manually.
                args = new String[5];
                
                // A short command option takes this form:
                args[0] = "-f";
                args[1] = "etc/datasource.conf";
                
                // You can add any arguments, even arguments used by your application but not
                // used by DataSource for Java. Here is a custom long option:
                args[2] = "--myLongOptionName=myValue1";
                
                // Here is a custom short option:
                args[3] = "-t";
                args[4] = "myValue2";
                
                // Construct the DataSource using the args and the custom logger
                DataSource myDataSource = DataSource.fromArgs(args, myLogger);
                
                // The following call to getCommandOption() returns "etc/datasource.conf". Note
                // that you can pass in any number of option names and the first matching value
                // will be returned.
                String configFileLocation = myDataSource.getCommandOption("default.conf", "config-file", "f");
                
                // This call returns "myValue1":
                String myFirstVariable = myDataSource.getCommandOption("defaultValue", "myLongOptionName");
                
                // This call returns "myValue2":
                String mySecondVariable = myDataSource.getCommandOption("defaultValue", "t");
        }
}

        Parameters:
        args - An array of arguments containing command options. DataSource for Java understands both short command options of the form -key value and long command options of the form --key=value.
        logger - The Logger to be used by DataSource for Java.
        Returns:
        The DataSource.
        Throws:
        java.lang.IllegalArgumentException - If the value of either args or logger is null.

      • fromArgs

        static DataSource fromArgs​(java.lang.String[] args)

        Creates an instance of DataSource using the supplied command options.

        When this method is called, DataSource for Java creates a Logger using the logging configuration in the supplied DataSource configuration file.

        Note: It is recommended that you provide your own Logger implementation and supply it to the DataSource by calling the fromArgs(String[], Logger) method, rather than calling this method.

        DataSource for Java parses the provided arguments into command options, which take the form of key/value pairs. DataSource for Java understands both short command options of the form -key value and long command options of the form --key=value.

        You can store arbitrary arguments in DataSource for Java and use them later in your own application code. However DataSource for Java also understands two built-in command options and will process them if they are found in the args array:

        Long Command Short Command Default Value Description
        config-file f conf/datasource.conf Path to a DataSource configuration file.

        For example:

        Long command option: --config-file=etc/datasource.conf

        Short command option: -f etc/datasource.conf

        If you set the a config option with the same name more than once, DataSource for Java will use the last occurrence of the option as the value.

        If you construct the DataSource using this method, you can retrieve the command option values by calling the getCommandOption(String, String...) method.

        The following example shows how to construct a DataSource with an argument array containing command options, and how to subsequently retrieve the command options from the DataSource: 

        import com.caplin.datasource.DataSource;

public class ArgumentProcessing
{
        @SuppressWarnings("unused")
        public static void main(String[] args)
        {
                // The args array containing the command options would generally be passed in
                // from the command line, but in this example we create the array manually.
                args = new String[5];
                
                // A short command option takes this form:
                args[0] = "-f";
                args[1] = "etc/datasource.conf";
                
                // You can add any arguments, even arguments used by your application but not
                // used by DataSource for Java. Here is a custom long option:
                args[2] = "--myLongOptionName=myValue1";
                
                // Here is a custom short option:
                args[3] = "-t";
                args[4] = "myValue2";
                
                // Construct the DataSource using the args
                DataSource myDataSource = DataSource.fromArgs(args);
                
                // The following call to getCommandOption() returns "etc/datasource.conf". Note
                // that you can pass in any number of option names and the first matching value
                // will be returned.
                String configFileLocation = myDataSource.getCommandOption("default.conf", "config-file", "f");
                
                // This call returns "myValue1":
                String myFirstVariable = myDataSource.getCommandOption("defaultValue", "myLongOptionName");
                
                // This call returns "myValue2":
                String mySecondVariable = myDataSource.getCommandOption("defaultValue", "t");
        }
}

        If this method is called then DataSource for Java will create a logger using the logging configuration in the DataSource configuration file. It is recommended that you use either the fromConfigFile(String, Logger) method or fromArgs(String[], Logger) method and provide your own Logger implementation rather than calling this method.

        Parameters:
        args - An array of arguments containing command options. DataSource for Java understands both short command options of the form -key value and long options of the form --key=value.
        Returns:
        The DataSource.
        Throws:
        java.lang.IllegalArgumentException - If the args value is null.

      • fromConfigFile

        static DataSource fromConfigFile​(java.lang.String configFileName)

        Creates an instance of DataSource using the supplied configuration file.

        When this method is called, DataSource for Java creates a Logger using the logging configuration in the supplied DataSource configuration file.

        Note 1: It is recommended that you provide your own Logger implementation and supply it to the DataSource by calling the fromConfigFile(String, Logger) method or fromArgs(String[], Logger) method, rather than calling this method.

        Note 2: If you want to supply your own command options to the DataSource application, in addition to the configuration, call the fromArgs(String[]) method or fromArgs(String[], Logger) method, rather than this one.

        Parameters:
        configFileName - Path to a DataSource configuration conf file.
        Returns:
        The DataSource.
        Throws:
        java.lang.IllegalArgumentException - If the configFileName is null.

      • fromConfigFile

        static DataSource fromConfigFile​(java.lang.String configFileName,
                                 java.util.logging.Logger logger)

        Creates an instance of DataSource using the supplied configuration file and Logger.

        When this method is called, DataSource for Java uses the provided Logger implementation for event logging. Packet logging must still be configured in the DataSource configuration file.

        Note: If you want to supply your own command options to the DataSource application, in addition to the configuration, call the fromArgs(String[], Logger) method, rather than this one.

        It is recommended that you use either the fromArgs(String[]) or fromArgs(String[], Logger) factory method instead of this method in order to discourage hard coding of configuration file locations.

        Parameters:
        configFileName - Path to a DataSource configuration conf file.
        logger - The Logger to be used by DataSource for Java.
        Returns:
        The DataSource.
        Throws:
        java.lang.IllegalStateException -

        If there is logging configuration in the DataSource configuration file. You can construct DataSource instances by either:

        java.lang.IllegalArgumentException - If the configFileName or Logger values are null.