HiRISE

HiRISE.HiPlan.HiCat
Class DatabaseFactory

java.lang.Object
  extended by HiRISE.HiPlan.HiCat.DatabaseFactory

public class DatabaseFactory
extends Object

A factory for producing database objects.

The getInstance methods produce a Database from an input Configuration; databases so created are cached, based on the relevant server parameters, so that only one instance of a given database will be created. Repeated invocations of getInstance yield the same database object for a given set of parameters.

Server Parameters

The following configuration parameters describe a unique database object for the purposes of this factory:

The "catalog" term describes a collection of tables. For MySQL, the corresponding term is "database," while for PostgreSQL, the term is "schema." In each case, the configuration parameter Catalog is used to refer to that structure, regardless of the term used by the server type. The Database is the name of the database on the server to be used. Some server types do not use it (MySQL); some require it (PostgreSQL).

The port number is optional and should only be used for non-standard ports. It will be appended to the host parameter (with the requried : character) if supplied. Note also that the host parameter may include it directly in the configuration, but if so, it must not be supplied as a separate parameter.

Finally, localhost is the same as 127.0.0.1 as part of the host name, and host names are not case-sensitive.

Version:
2.6
Author:
Shawn Wheelock - UA/PIRL

Field Summary
static String ID
          Class identification name with source code version and date.
 
Method Summary
static Database getInstance(Configuration configuration)
          Gets a database instance with the indicated configuration.
static Database getInstance(Configuration configuration, String id)
          Gets a database instance with the indicated configuration and optional ID.
static void main(String[] args)
          Invokes a test stub for exercising the database factory.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values
Method Detail

getInstance

public static Database getInstance(Configuration configuration,
                                   String id)
                            throws Invalid_Argument_Exception
Gets a database instance with the indicated configuration and optional ID. New database objects are cached according to the relevant server parameters, so that only one instance of any given database will be created. Repeated invocations of this method yield the same database object for a given set of parameters.

The configuration must include a Server parameter, and it must include a group parameter whose name is the same as the value of the server parameter. Furthermore, the server group must contain the parameters necessary to describe a database. For example:

        Server = foo_server

        Group = foo_server
                Type = MySQL
                Host = foo.org
                User = "foo"
                Password = "sekrit"
                Catalog = "test"
        End_Group

If the configuration does not contain sufficient parameters to create a new database, an Invalid_Argument_Exception is thrown.

An optional string, id, allows the user to add an additional layer of uniqueness to the identificaton of a database object when such a layer is desired. For example given the above foo_server server group in a configuration, the following code will result in two different database objects:

        Database
                d1 = DatabaseFactory.getInstance(configuration);
        Database
                d2 = DatabaseFactory.getInstance(configuration, "Shape Layer");

Parameters:
configuration - a configuration describing the desired database.
id - an optional identifier to add an additional layer of uniqueness to a server group when such is desired; may be null.
Returns:
a database with the indicated configuration.
Throws:
Invalid_Argument_Exception - if the configuration is insufficient to yield a usable database object.

getInstance

public static Database getInstance(Configuration configuration)
                            throws Invalid_Argument_Exception
Gets a database instance with the indicated configuration. New database objects are cached according to the relevant server parameters, so that only one instance of any given database will be created. Repeated invocations of this method yield the same database object for a given set of parameters.

The configuration must include a Server parameter, and it must include a group parameter whose name is the same as the value of the server parameter. Furthermore, the server group must contain the parameters necessary to describe a database. For example:

        Server = foo_server

        Group = foo_server
                Type = MySQL
                Host = foo.org
                User = "foo"
                Password = "sekrit"
                Catalog = "test"
        End_Group

If the configuration does not contain sufficient parameters to create a new database, an Invalid_Argument_Exception is thrown.

Parameters:
configuration - a configuration describing the desired database.
Returns:
a database with the indicated configuration.
Throws:
Invalid_Argument_Exception - if the configuration is insufficient to yield a usable database object.
See Also:
getInstance(Configuration,String)

main

public static void main(String[] args)
Invokes a test stub for exercising the database factory. Command-line arguments are presumed to be configuration filenames; the test stub loads each in succession, retrieves a database from the factory, and displays some statistics about the database and the database catalog. If an exception is encountered, a stacktrace is dumped.

The test stub reports the creation of new databases as they are created.

Usage

DatabaseFactory configuration_pathname [...]

Parameters:
args - the command-line arguments, presumed to be configuration filenames.

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona