DSR
Keywords: uk.ac.ic.doc.automed.DSR,DSR class

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## uk.ac.ic.doc.automed
Class DSR

    java.lang.Object
      |
      +--uk.ac.ic.doc.automed.DSR

All Implemented Interfaces:
  uk.ac.ic.doc.automed.xml.XMLifyConstants

Direct Known Subclasses:
  DataSourceRepository

public class DSR
extends java.lang.Object
implements uk.ac.ic.doc.automed.xml.XMLifyConstants

Reads data source definitions from a configuration file and provides methods to get a `Connection` for a data souce.

Configuration File
The default configuration file "uk.ac.ic.doc.automed.DSR::data_source_repository.cfg" is read and checked for syntax errors when the class is first loaded.
Blank lines (lines containing only white space) are ignored. Comments can appear anywhere, they start with a '#' character and extend to the end of their line. A directive is a line that starts with a keyword (preceeded onlly by white space) which is followed by the keyword's value. The value starts from the first non white space character after the keyword and extends to the end of the line or first comment character. All white space within the value is preserved. Trailing white space and white space between a value and a comment are stripped. Multline values can be specified using '\' as the last, non white space character before the the beginning of a comment or the end of the line. The newlines seperating the lines are preserved.

A data source definition must begin with the DataSource directive. The order of the directives after the DataSource directive is not significant.

Directives

Keyword | Argument Type | Description |
--- | --- | --- | ---
DataSource | String | The name of the data source for which all directives up to the next DataSouce apply | Required
ConnectionType | String | Currently only type "JDBC" is supported | Required
JdbcURL | String | The JDBC URL used to connect to the data source | Required
JdbcDriver | String | The fully qualified name of the JDBC driver class needed to connect to the data source | Required
Username | String | Username needed to connect to data source | Optional
Password | String | Password needed to connect to data source
| Optional
ZeroForNull | String | A table name and field name seperated by a period. Certain commands such as display and exportdb will use this to convert values of the field to null when they are zero in a result set quering the table. This is get round a bug in the postgresql driver where integer foreign key fields return 0 when their value is null. | Optional
SerialID | String | A table name and field name seperated by a period. A field marked as SerialID will still have it's values written by the exportdb command but the importdb command will not try to set a value for the field when inserting rows. It is assumed that the underlying database will supply values (presumably sequential).
| Optional
SerialRef | String | A table name and field name seperated by a period followed by a colon and another table name and field. The first field marked as a SerialRef should be a field that is a foreign key to the second field named which itself should be a SerialID field. importdb will use the value supplied by the DBS for the SerialID field when inserting the SerialRef field.
| Optional

A property can be defined using the same syntax, any unrecognized keyword is interpreted as a property name and the value is assumed to be of type String. The difference between properties and keywords is that keywords are those properties that the DSR "knows about"

Author:
  Michael Boyd

Nested Class Summary

Nested classes inherited from class uk.ac.ic.doc.automed.xml.XMLifyConstants
`uk.ac.ic.doc.automed.xml.XMLifyConstants.IgnoreNextElementException`

Field Summary

Fields inherited from interface uk.ac.ic.doc.automed.xml.XMLifyConstants
`CHARACTERS, CHILDREN, DEFINITIVE, DEFINITIVE_CHILDREN, DEFINITIVE_CHILDREN_RECURSE, DEFINITIVE_MEMBER, DEFINITIVE_MEMBER_AND_CHILDREN, DEFINITIVE_MEMBER_RECURSE, END_DOCUMENT, END_ELEMENT, ERROR, EXCLUDE, EXCLUDE_MEMBER, FATAL_ERROR, FIRSTPASS, IGNORABLE_WHITESPACE, MEMBER, NOTATION_DECL, OBJECT, OBJECT_CHILDREN, OBJECT_CHILDREN_RECURSE, OBJECT_MEMBER, OBJECT_MEMBER_AND_CHILDREN, OBJECT_MEMBER_RECURSE, ONEPASS, PRIMITIVE, PRIMITIVE_CHILDREN, PRIMITIVE_CHILDREN_RECURSE, PRIMITIVE_MEMBER, PRIMITIVE_MEMBER_AND_CHILDREN, PRIMITIVE_MEMBER_RECURSE, PROCESSING_INSTRUCTION, RECURSE, REFERENCE, REFERENCE_CHILDREN, REFERENCE_CHILDREN_RECURSE, REFERENCE_MEMBER, REFERENCE_MEMBER_AND_CHILDREN, REFERENCE_MEMBER_RECURSE, SAX_ERROR, SECONDPASS, START_DOCUMENT, START_ELEMENT, UNPARSED_ENTITY_DECL, WARNING`

Method Summary
`static java.lang.reflect.Method` | `addCommand(java.lang.String command, java.lang.Class methodClass, java.lang.String help)` Looks for a public method with the signature doCommand(String[] args) in the class methodClass and adds it to the commands that can be invoked from the CLI.
`static void` | `addReloadHook(java.lang.reflect.Method m)`
`static void` | `dispatchCommand(java.lang.String[] args)` Invokes the method registered for the command args[0] with `#addCommand(String, Class)`.
`static void` | `doCreateCommand(java.lang.String[] args)`
`static void` | `doCreatedbCommand(java.lang.String[] args)` Reads the property CreateDB property for the data source and executes the value as an update on the databse connection
`static void` | `doDefaultCommand(java.lang.String[] args)`
`static void` | `doDisplayCommand(java.lang.String[] args)`
`static void` | `doDropdbCommand(java.lang.String[] args)`
`static void` | `doGetCommand(java.lang.String[] args)`
`static void` | `doHelpCommand(java.lang.String[] args)`
`static void` | `doIsCommand(java.lang.String[] args)`
`static void` | `doPopulatedbCommand(java.lang.String[] args)`
`static void` | `doPrintCommand(java.lang.String[] args)`
`static void` | `doReloadCommand(java.lang.String[] args)`
`static void` | `doRemoveCommand(java.lang.String[] args)`
`static void` | `doSetCommand(java.lang.String[] args)`
`static java.lang.Object` | `executeStatement(java.lang.String dataSource, java.lang.String sql, boolean display)`
`static java.lang.Object` | `executeStatement(java.lang.String dataSource, java.lang.String sql, boolean display, java.util.Set nullifyZeros)`
`static java.lang.Object[]` | `executeStatements(java.lang.String dataSource, java.lang.String sql, boolean display)`
`static java.lang.Object[]` | `executeStatements(java.lang.String dataSource, java.lang.String sql, boolean display, java.util.Set nullifyZeros)`
`static java.lang.Class` | `getCommandClass()`
`static java.lang.String` | `getConfigFileName()` Returns the name of the file used for data source definitions.
`static java.sql.Connection` | `getDataSourceConnection(java.lang.String name)` Gets a connection to the named data souce.
`static java.sql.Connection` | `getDataSourceConnection(java.lang.String name, java.lang.String username, java.lang.String password)` Gets a connection to the named data souce.
`static java.lang.Object` | `getDataSourceProperty(java.lang.String dataSourceName, java.lang.String propertyName)` Returns the named property for the named data source as defined in the configuration file.
`static java.lang.String` | `getDefaultDataSource()`
`static java.lang.String` | `getDefaultUserName()`
`static void` | `main(java.lang.String[] args)` Provides a simple command line interface to enable the configuration file to be checked.
`protected static void` | `readConfigFile()` Reads the current configuration file.
`protected static void` | `readConfigFile(java.lang.String configFile)` Reads the directives for the data sources defined in configFile.
`static void` | `setCommandClass(java.lang.Class c)`
`static void` | `setCommandHelp(java.lang.String[][] commandHelp)`
`static void` | `setConfigFileName(java.lang.String filename)` Sets the name of the file used for data source defintiions, this resets any data cached in the MDR or STR and invalidates all objects returned by them prior to this call.
`static void` | `setDefaultDataSource(java.lang.String name)`
`static void` | `setDefaultUserName(java.lang.String name)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### getDefaultDataSource

    public static java.lang.String getDefaultDataSource()

### setDefaultDataSource

    public static void setDefaultDataSource(java.lang.String name)

### getDefaultUserName

    public static java.lang.String getDefaultUserName()

### setDefaultUserName

    public static void setDefaultUserName(java.lang.String name)

### setCommandHelp

    public static void setCommandHelp(java.lang.String[][] commandHelp)

### getCommandClass

    public static java.lang.Class getCommandClass()

### setCommandClass

    public static void setCommandClass(java.lang.Class c)

### readConfigFile

    protected static void readConfigFile()
                                  throws java.io.IOException,
                                         DSRException

  Reads the current configuration file. This method is called when the class is loaded with the value "::data_source_repository.cfg". It calls `readConfigFile(String)` with the name of the last configuration file read.

    `java.io.IOException`
    `DSRException`
  See Also:
    `readConfigFile(String configFile)`

### readConfigFile

    protected static void readConfigFile(java.lang.String configFile)
                                  throws java.io.IOException,
                                         DSRException

  Reads the directives for the data sources defined in configFile. If the file is successfully found, then all current datasource definitions are dropped before reading the config file. The config file can be specified with an absolute path or a path relative to the working directory in which the JVM was started or with :: to specify a file in the same directory as the class file. If no classname is given then the DSR class is used (this is how the default configuration file is found).

  Parameters:
    `configFile` - The name of the file to read data source definitions from.
  Throws:
    `java.io.IOException` - If there's a problem reading the file.
    `DSRException` - If there's an error in the configuration file.

### getDataSourceProperty

    public static java.lang.Object getDataSourceProperty(java.lang.String dataSourceName,
                                                         java.lang.String propertyName)
                                                  throws DSRException

  Returns the named property for the named data source as defined in the configuration file.

    `DSRException`

### getDataSourceConnection

    public static java.sql.Connection getDataSourceConnection(java.lang.String name)
                                                       throws java.io.IOException,
                                                              java.sql.SQLException,
                                                              DSRException

  Gets a connection to the named data souce. This method calls `getDataSourceConnection(String name, String username, String password)` supplying as username and password the values defined for the data source or null if they aren't defined.

    `java.io.IOException`
    `java.sql.SQLException`
    `DSRException`
  See Also:
    `getDataSourceConnection(String name, String username, String password)`

### getDataSourceConnection

    public static java.sql.Connection getDataSourceConnection(java.lang.String name,
                                                              java.lang.String username,
                                                              java.lang.String password)
                                                       throws java.io.IOException,
                                                              java.sql.SQLException,
                                                              DSRException

  Gets a connection to the named data souce. If either the username or password are not supplied (i.e. are null) and are relevant to the connection type then the properties defined for the data source are used. If the data source definition doesn't supply thenm either then the user is prompted for them on the standard input.

  Parameters:
    `name` - The name of the data source as defined in the configuration file.
    `username` - The username to use when establishing the connection or null if not required or to use the defined value for the data source or prompt the user if not defined.
    `password` - The password to use when establishing the connection or null if not required or to use the defined value for the data source or to prompt the user if not defined.
  Returns:
    a `Connection` to the named data source.
  Throws:
    `java.ioIOException` - if there's a problem reading input from the user.
    `java.sql.SQLException` - from the `DriverManager.getConnection(String, String, String)`.
    `DSRException` - if there's no definition for the named data source or the connection type is unknown or (for connection type "JDBC") the JdbcDriver can't be found or doesn't implement `Driver`.
    `java.io.IOException`

### executeStatement

    public static java.lang.Object executeStatement(java.lang.String dataSource,
                                                    java.lang.String sql,
                                                    boolean display)
                                             throws DSRException,
                                                    java.io.IOException,
                                                    java.sql.SQLException

    `DSRException`
    `java.io.IOException`
    `java.sql.SQLException`

### executeStatement

    public static java.lang.Object executeStatement(java.lang.String dataSource,
                                                    java.lang.String sql,
                                                    boolean display,
                                                    java.util.Set nullifyZeros)
                                             throws DSRException,
                                                    java.io.IOException,
                                                    java.sql.SQLException

    `DSRException`
    `java.io.IOException`
    `java.sql.SQLException`

### executeStatements

    public static java.lang.Object[] executeStatements(java.lang.String dataSource,
                                                       java.lang.String sql,
                                                       boolean display)
                                                throws DSRException,
                                                       java.io.IOException,
                                                       java.sql.SQLException

    `DSRException`
    `java.io.IOException`
    `java.sql.SQLException`

### executeStatements

    public static java.lang.Object[] executeStatements(java.lang.String dataSource,
                                                       java.lang.String sql,
                                                       boolean display,
                                                       java.util.Set nullifyZeros)
                                                throws DSRException,
                                                       java.io.IOException,
                                                       java.sql.SQLException

    `DSRException`
    `java.io.IOException`
    `java.sql.SQLException`

### main

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

  Provides a simple command line interface to enable the configuration file to be checked.

### dispatchCommand

    public static void dispatchCommand(java.lang.String[] args)
                                throws java.lang.Exception

  Invokes the method registered for the command args[0] with `#addCommand(String, Class)`.

  Throws:
    `DSRException` - if the command is not registered
    `java.lang.Exception` - the target exception if invoke throghs InvocationTargetException

### addCommand

    public static java.lang.reflect.Method addCommand(java.lang.String command,
                                                      java.lang.Class methodClass,
                                                      java.lang.String help)
                                               throws java.lang.NoSuchMethodException

  Looks for a public method with the signature doCommand(String[] args) in the class methodClass and adds it to the commands that can be invoked from the CLI.

  Returns:
    The previously registered method for the command, if any
    `java.lang.NoSuchMethodException`

### doDefaultCommand

    public static void doDefaultCommand(java.lang.String[] args)

### doHelpCommand

    public static void doHelpCommand(java.lang.String[] args)

### doPrintCommand

    public static void doPrintCommand(java.lang.String[] args)

### doReloadCommand

    public static void doReloadCommand(java.lang.String[] args)
                                throws java.io.IOException

    `java.io.IOException`

### doCreatedbCommand

    public static void doCreatedbCommand(java.lang.String[] args)
                                  throws DSRException,
                                         java.io.IOException,
                                         java.sql.SQLException

  Reads the property CreateDB property for the data source and executes the value as an update on the databse connection

    `DSRException`
    `java.io.IOException`
    `java.sql.SQLException`

### doDropdbCommand

    public static void doDropdbCommand(java.lang.String[] args)
                                throws DSRException,
                                       java.io.IOException,
                                       java.sql.SQLException

    `DSRException`
    `java.io.IOException`
    `java.sql.SQLException`

### doDisplayCommand

    public static void doDisplayCommand(java.lang.String[] args)
                                 throws DSRException,
                                        java.io.IOException,
                                        java.sql.SQLException

    `DSRException`
    `java.io.IOException`
    `java.sql.SQLException`

### doPopulatedbCommand

    public static void doPopulatedbCommand(java.lang.String[] args)
                                    throws DSRException,
                                           java.sql.SQLException,
                                           java.io.IOException

    `DSRException`
    `java.sql.SQLException`
    `java.io.IOException`

### doIsCommand

    public static void doIsCommand(java.lang.String[] args)
                            throws java.lang.Exception

    `java.lang.Exception`

### doGetCommand

    public static void doGetCommand(java.lang.String[] args)
                             throws java.lang.Exception

    `java.lang.Exception`

### doSetCommand

    public static void doSetCommand(java.lang.String[] args)
                             throws java.lang.Exception

    `java.lang.Exception`

### doCreateCommand

    public static void doCreateCommand(java.lang.String[] args)
                                throws java.lang.Exception

    `java.lang.Exception`

### doRemoveCommand

    public static void doRemoveCommand(java.lang.String[] args)
                                throws java.lang.Exception

    `java.lang.Exception`

### getConfigFileName

    public static java.lang.String getConfigFileName()

  Returns the name of the file used for data source definitions.

  Returns:
    the name of the file used for data source definitions.

### setConfigFileName

    public static void setConfigFileName(java.lang.String filename)
                                  throws java.io.IOException,
                                         DSRException

  Sets the name of the file used for data source defintiions, this resets any data cached in the MDR or STR and invalidates all objects returned by them prior to this call. This name is set to `~/.automed/data_source_repository.cfg` by default.

  Parameters:
    `filename` - the name of the file used for data source definitions.
    `java.io.IOException`
    `DSRException`

### addReloadHook

    public static void addReloadHook(java.lang.reflect.Method m)

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD