com.programix.da2
Class DAFactory

java.lang.Object
  com.programix.da2.DAFactory

public class DAFactory
extends Object

Used to construct and initialize instances of data access implementations using reflection.

Common usage is (where CustomerDA is an interface that extends the GenericDA interface):

 ValueMap config = //...
 CustomerDA cda = DAFactory.create(config, CustomerDA.class);

or

 String filename = //...
 CustomerDA cda = DAFactory.create(filename, CustomerDA.class);

The configuration ValueMap passed in must contain the class name of the class to be instantiated stored under the key DA_IMPLEMENTATION_CLASSNAME. Other key/value pairs in the map are populated with whatever the specific data access implementation needs for initialization.

Author:

Paul Hyde

Field Summary

static String	DA_DECOREE_PREFIX Used by this factory to facilitate the creation and initialization of a chain of data access' if the outer 'wrappers' implement DecoratorDA.
static String	DA_IMPLEMENTATION_CLASSNAME The reserved key that retrieves the fully-qualified name (as a String) of the data access implementation class that will be instantiated via reflection.
static String	DA_REMOTE_SOURCE_URL This reserved key is used to retrieve the URL (as a String) of a remote DASource available via HTTP or HTTPS.

Method Summary

static <T extends GenericDA> T	create(File file, Class<T> targetType) Create a data access instance using an File whose data is in the format described by ValueMap (nearly identical to the format for a Properties file).
static <T extends GenericDA> T	create(InputStream rawIn, Class<T> targetType) Create a data access instance using an InputStream whose data is in the format described by ValueMap (nearly identical to the format for a Properties file).
static <T extends GenericDA> T	create(Reader rawIn, Class<T> targetType) Create a data access instance using a Reader whose data is in the format described by ValueMap (nearly identical to the format for a Properties file).
static <T extends GenericDA> T	create(URL propertiesURL, Class<T> targetType) Create a data access instance using the specified URL whose data is in the format described by ValueMap(nearly identical to the format for a Properties file).
static <T extends GenericDA> T	create(ValueMap config, Class<T> daInterfaceType) Constructs an instance of the data access implementation specified in the configuration.
static <T extends GenericDA> T	createFromFile(String filename, Class<T> targetType) Create a data access instance using the specified filename whose data is in the format described by ValueMap(nearly identical to the format for a Properties file).
static <T extends GenericDA> T	createFromResource(String resourceLocation, Class<T> targetType) Create a data access instance using the specified resourceLocation whose data is in the format described by ValueMap(nearly identical to the format for a Properties file).

Methods inherited from class java.lang.Object

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

Field Detail

DA_IMPLEMENTATION_CLASSNAME

public static final String DA_IMPLEMENTATION_CLASSNAME

The reserved key that retrieves the fully-qualified name (as a String) of the data access implementation class that will be instantiated via reflection.

The value of this key is always:

 da.impl.classname
 

See Also:

create(ValueMap, Class), Constant Field Values

DA_REMOTE_SOURCE_URL

public static final String DA_REMOTE_SOURCE_URL

This reserved key is used to retrieve the URL (as a String) of a remote DASource available via HTTP or HTTPS.

The value of this key is always:

 da.remote.source.url
 

See Also:

create(ValueMap, Class), Constant Field Values

DA_DECOREE_PREFIX

public static final String DA_DECOREE_PREFIX

Used by this factory to facilitate the creation and initialization of a chain of data access' if the outer 'wrappers' implement DecoratorDA. The reserved key prefix that when present in the configuration ValueMap is used to extract a sub-map via the getNestedValueMap(prefix) on ValueMap. This sub-map is then passed off to the decoree of the DecoratorDA.

The value of this key is always (note the trailing dot):

 da.decoree.
 

See Also:

create(ValueMap, Class), Constant Field Values

Method Detail

create

public static <T extends GenericDA> T create(ValueMap config,
                                             Class<T> daInterfaceType)
                                  throws DAException

Constructs an instance of the data access implementation specified in the configuration. One of two special keys must be present, either:

• DA_IMPLEMENTATION_CLASSNAME with a String value which is the full class name of the implementation of the data access interface.
• DA_REMOTE_SOURCE_URL with a String value which is the URL (using the http or https protocol) where a remote DASource is available

If both happen to be present and non-empty, then the classname will be used.

Immediately after the zero-argument constructor is invoked, the init(ValueMap conf) of GenericDA is invoked to initialize the configuration.

If the targetType is not null, then an additional check is done to ensure that the constructed object can be type cast into that type (failures throw a DAException instead of a ClassCastException).

If the implementation happens to be not only a GenericDA but also a DecoratorDA and there are config map keys starting with the DA_DECOREE_PREFIX, then this create method will attempt to create the chain of decorated data access implementations. This create method will attempt to extract a sub-map using this reserved key prefix via the getNestedValueMap(prefix) on ValueMap. This sub-map is then used to create the decoree of the DecoratorDA. If you'd like to manually chain, then make sure that there are no keys starting with the prefix DA_DECOREE_PREFIX.

Parameters:

config - key/value mapping with everything that is needed to initialize this data access implementation.

daInterfaceType - the class type that this instance is expected to be cast into. Use null to skip this check. If not null and the type does not match what is constructed, then a DAException is thrown.

Returns:

the constructed and initialized instance.

Throws:

DAException - if instance can not be constructed and initialized.

See Also:

create(Reader, Class), create(InputStream, Class), createFromFile(String, Class), create(File, Class), create(URL, Class)

create

public static <T extends GenericDA> T create(Reader rawIn,
                                             Class<T> targetType)
                                  throws DAException

Create a data access instance using a Reader whose data is in the format described by ValueMap (nearly identical to the format for a Properties file). Internally, the stream will be buffered and the stream will be closed.

Parameters:

rawIn - a stream whose contents can be loaded into a ValueMap with everything that is needed to initialize the instance of data access.

targetType - the class type that this instance is expected to be cast into. Use null to skip this check. If not null and the type does not match what is constructed, then a DAException is thrown.

Returns:

the constructed and initialized instance.

Throws:

DAException - if instance can not be constructed and initialized.

See Also:

create(ValueMap, Class), create(InputStream, Class), createFromFile(String, Class), create(File, Class), create(URL, Class)

create

public static <T extends GenericDA> T create(InputStream rawIn,
                                             Class<T> targetType)
                                  throws DAException

Create a data access instance using an InputStream whose data is in the format described by ValueMap (nearly identical to the format for a Properties file). Internally, the stream will be buffered and the stream will be closed.

Parameters:

rawIn - a stream whose contents can be loaded into a ValueMap with everything that is needed to initialize the instance of data access.

targetType - the class type that this instance is expected to be cast into. Use null to skip this check. If not null and the type does not match what is constructed, then a DAException is thrown.

Returns:

the constructed and initialized instance.

Throws:

DAException - if instance can not be constructed and initialized.

See Also:

create(ValueMap, Class), create(Reader, Class), createFromFile(String, Class), create(File, Class), create(URL, Class)

create

public static <T extends GenericDA> T create(File file,
                                             Class<T> targetType)
                                  throws DAException

Create a data access instance using an File whose data is in the format described by ValueMap (nearly identical to the format for a Properties file).

Parameters:

file - file with key/value mapping with everything that is needed to initialize the instance of data access.

targetType - the class type that this instance is expected to be cast into. Use null to skip this check. If not null and the type does not match what is constructed, then a DAException is thrown.

Returns:

the constructed and initialized instance.

Throws:

DAException - if instance can not be constructed and initialized.

See Also:

create(ValueMap, Class), create(Reader, Class), create(InputStream, Class), createFromFile(String, Class), create(URL, Class)

createFromFile

public static <T extends GenericDA> T createFromFile(String filename,
                                                     Class<T> targetType)
                                          throws DAException

Create a data access instance using the specified filename whose data is in the format described by ValueMap(nearly identical to the format for a Properties file).

Parameters:

filename - file with key/value mapping with everything that is needed to initialize the instance of data access.

targetType - the class type that this instance is expected to be cast into. Use null to skip this check. If not null and the type does not match what is constructed, then a DAException is thrown.

Returns:

the constructed and initialized instance.

Throws:

DAException - if instance can not be constructed and initialized.

See Also:

create(ValueMap, Class), create(Reader, Class), create(InputStream, Class), create(File, Class), create(URL, Class)

create

public static <T extends GenericDA> T create(URL propertiesURL,
                                             Class<T> targetType)
                                  throws DAException

Create a data access instance using the specified URL whose data is in the format described by ValueMap(nearly identical to the format for a Properties file).

Parameters:

propertiesURL - a URL whose contents can be loaded into a ValueMap with everything that is needed to initialize the instance of data access.

targetType - the class type that this instance is expected to be cast into. Use null to skip this check. If not null and the type does not match what is constructed, then a DAException is thrown.

Returns:

the constructed and initialized instance.

Throws:

DAException - if instance can not be constructed and initialized.

See Also:

create(ValueMap, Class), create(Reader, Class), create(InputStream, Class), createFromFile(String, Class), create(File, Class)

createFromResource

public static <T extends GenericDA> T createFromResource(String resourceLocation,
                                                         Class<T> targetType)
                                              throws DAException

Create a data access instance using the specified resourceLocation whose data is in the format described by ValueMap(nearly identical to the format for a Properties file).

Parameters:

resourceLocation - resource with key/value mapping with everything that is needed to initialize the instance of data access.

targetType - the class type that this instance is expected to be cast into. Use null to skip this check. If not null and the type does not match what is constructed, then a DAException is thrown.

Returns:

the constructed and initialized instance.

Throws:

DAException - if instance can not be constructed and initialized.

See Also:

create(ValueMap, Class), create(Reader, Class), create(InputStream, Class), create(File, Class), create(URL, Class)