com.caplin.datasource

Class DataSourceFactory

java.lang.Object

com.caplin.datasource.DataSourceFactory

public final class DataSourceFactory
extends java.lang.Object

A factory used to create DataSource instances. The preferred method to use for this purpose is createDataSource(String[], Logger).

Method Summary

Methods

Modifier and Type	Method and Description
static DataSource	createDataSource(java.lang.String configurationString) Creates an instance of DataSource using the supplied configuration string.
static DataSource	createDataSource(java.lang.String[] args) Creates an instance of DataSource using the supplied command options.
static DataSource	createDataSource(java.lang.String[] args, java.util.logging.Logger logger) Creates an instance of DataSource using the supplied command options and Logger.
static DataSource	createDataSource(java.lang.String configurationString, java.util.logging.Logger logger) Creates an instance of DataSource using the supplied configuration string and Logger.
static DataSource	createDataSource(java.lang.String configFile, java.lang.String fieldsFile) Creates an instance of DataSource using the supplied configuration file and fields definition file.
static DataSource	createDataSource(java.lang.String configFile, java.lang.String fieldsFile, java.util.logging.Logger logger) Creates an instance of DataSource using the supplied configuration file, fields definition file, and Logger.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createDataSource

public static DataSource createDataSource(java.lang.String configFile,
                          java.lang.String fieldsFile,
                          java.util.logging.Logger logger)

Creates an instance of DataSource using the supplied configuration file, fields definition 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 XML file.

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

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

Parameters:

configFile - Path to a DataSource configuration XML file.

fieldsFile - Path to a Fields configuration XML 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 XML file. You can construct DataSource instances by either:

• calling createDataSource(String, String, Logger) or createDataSource(String[], Logger) and ensuring that you do not have any logging configuration in your DataSource configuration XML file, or
• calling createDataSource(String, String) or createDataSource(String[]) and ensuring that you have included logging configuration in your DataSource configuration XML file so that DataSource for Java can create its own logger.

java.lang.IllegalArgumentException - If any of the configFile, fieldsFile, or Logger values are null.

createDataSource

public static DataSource createDataSource(java.lang.String configFile,
                          java.lang.String fieldsFile)

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

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

Note 1: It is recommended that you provide your own Logger implementation and supply it to the DataSource by calling the createDataSource(String, String, Logger) method or createDataSource(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 and fields definition file, call the createDataSource(String[]) method or createDataSource(String[], Logger) method, rather than this one.

Parameters:

configFile - Path to a DataSource configuration XML file.

fieldsFile - Path to a Fields definition XML file.

Returns:

The DataSource.

Throws:

java.lang.IllegalArgumentException - If either configFile or fieldsFile is null.

createDataSource

public static DataSource createDataSource(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 XML file.

Note: It is recommended that you provide your own Logger implementation and supply it to the DataSource by calling the createDataSource(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.xml	Path to a DataSource configuration XML file.
fields-file	e	conf/Fields.xml	Path to a Fields configuration XML file.

For example:

Long command option: --config-file=conf/DataSource.xml

Short command option: -f conf/DataSource.xml

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

If you construct the DataSource using this method, you can retrieve the command option values by calling the DataSource.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;
import com.caplin.datasource.DataSourceFactory;

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[6];
                
                // A short command option takes this form:
                args[0] = "-f";
                args[1] = "conf/DataSource.xml";
                
                // A long command option takes this form:
                args[2] = "--fields-file=conf/Fields.xml";
                
                // 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[3] = "--myLongOptionName=myValue1";
                
                // Here is a custom short option:
                args[4] = "-t";
                args[5] = "myValue2";
                
                // Construct the DataSource using the args
                DataSource myDataSource = DataSourceFactory.createDataSource(args);
                
                // The following call to getCommandOption() returns "conf/DataSource.xml". Note
                // that you can pass in any number of option names and the first matching value
                // will be returned.
                String configFileLocation = myDataSource.getCommandOption("defaultConfig.xml", "config-file", "f");
                
                // This call returns "conf/Fields.xml":
                String fieldsFileLocation = myDataSource.getCommandOption("defaultFields.xml", "fields-file", "e");
                
                // 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 XML configuration file. It is recommended that you use either the createDataSource(String, String, Logger) method or createDataSource(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.

createDataSource

public static DataSource createDataSource(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 XML 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	conf/DataSource.xml	Path to a DataSource configuration XML file.
fields-file	e	conf/Fields.xml	Path to a Fields configuration XML file.

For example:

Long command option: --config-file=conf/DataSource.xml

Short command option: -f conf/DataSource.xml

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

If you construct the DataSource using this method, you can retrieve the command option values by calling the DataSource.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;
import com.caplin.datasource.DataSourceFactory;

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[6];
                
                // A short command option takes this form:
                args[0] = "-f";
                args[1] = "conf/DataSource.xml";
                
                // A long command option takes this form:
                args[2] = "--fields-file=conf/Fields.xml";
                
                // 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[3] = "--myLongOptionName=myValue1";
                
                // Here is a custom short option:
                args[4] = "-t";
                args[5] = "myValue2";
                
                // Construct the DataSource using the args and the custom logger
                DataSource myDataSource = DataSourceFactory.createDataSource(args, myLogger);
                
                // The following call to getCommandOption() returns "conf/DataSource.xml". Note
                // that you can pass in any number of option names and the first matching value
                // will be returned.
                String configFileLocation = myDataSource.getCommandOption("defaultConfig.xml", "config-file", "f");
                
                // This call returns "conf/Fields.xml":
                String fieldsFileLocation = myDataSource.getCommandOption("defaultFields.xml", "fields-file", "e");
                
                // 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.

createDataSource

public static DataSource createDataSource(java.lang.String configurationString)

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

Note: This method only supports the Caplin configuration syntax. That is XML fragments are not supported.

Parameters:

configurationString - String containing the DataSource configuration.

Returns:

The DataSource.

Throws:

java.lang.IllegalArgumentException - The configurationString is null.

createDataSource

public static DataSource createDataSource(java.lang.String configurationString,
                          java.util.logging.Logger logger)

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

Note: This method only supports the Caplin configuration syntax. That is XML fragments are not supported.

Parameters:

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

main

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