org.xmldb.api

Class DatabaseManager

public class DatabaseManager extends Object

DatabaseManager is the entry point for the API and enables you to get the initial Collection references necessary to do anything useful with the API. DatabaseManager is intended to be provided as a concrete implementation in a particular programming language. Individual language mappings should define the exact syntax and semantics of its use.

Field Summary
protected static String	URI_PREFIX

Method Summary
static void	deregisterDatabase(Database database) Deregisters a `Database` implementation from the `DatabaseManager`.
static Collection	getCollection(String uri) Retrieves a `Collection` instance from the database for the given URI.
static Collection	getCollection(String uri, String username, String password) Retrieves a `Collection` instance from the database for the given URI.
static String	getConformanceLevel(String uri) Returns the Core Level conformance value for the provided URI.
protected static Database	getDatabase(String uri) Retrieves the registered `Database` instance associated with the provided URI.
static Database[]	getDatabases() Returns a list of all available `Database` implementations that have been registered with this `DatabaseManager`.
static String	getProperty(String name) Retrieves a property that has been set for the `DatabaseManager`.
static void	registerDatabase(Database database) Registers a new `Database` implementation with the `DatabaseManager`.
static void	setProperty(String name, String value) Sets a property for the `DatabaseManager`.
protected static String	stripURIPrefix(String uri) Removes the URI_PREFIX from the front of the URI.

Field Detail

URI_PREFIX

protected static final String URI_PREFIX

Method Detail

deregisterDatabase

public static void deregisterDatabase(Database database)

Deregisters a Database implementation from the DatabaseManager. Once a Database has been deregistered it can no longer be used to handle requests.

Parameters: database The Database instance to deregister.

Throws: XMLDBException with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.

getCollection

public static Collection getCollection(String uri)

Retrieves a Collection instance from the database for the given URI. The format of the majority of the URI is database implementation specific however the uri must begin with characters xmldb: and be followed by the name of the database instance as returned by Database.getName() and a colon character. An example would be for the database named "vendordb" the URI handed to getCollection would look something like the following. xmldb:vendordb://host:port/path/to/collection. The xmldb: prefix will be removed from the URI prior to handing the URI to the Database instance for handling.

This method is called when no authentication is necessary for the database.

Parameters: uri The database specific URI to use to locate the collection.

Returns: A Collection instance for the requested collection or null if the collection could not be found.

Throws: XMLDBException with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.
ErrroCodes.INVALID_URI If the URI is not in a valid format.
ErrroCodes.NO_SUCH_DATABASE If a Database instance could not be found to handle the provided URI.

getCollection

public static Collection getCollection(String uri, String username, String password)

Parameters: uri The database specific URI to use to locate the collection. username The username to use for authentication to the database or null if the database does not support authentication. password The password to use for authentication to the database or null if the database does not support authentication.

Returns: A Collection instance for the requested collection or null if the collection could not be found.

getConformanceLevel

public static String getConformanceLevel(String uri)

Returns the Core Level conformance value for the provided URI. The current API defines valid resuls of "0" or "1" as defined in the XML:DB API specification.

Parameters: uri The database specific URI to use to locate the collection.

Returns: The XML:DB Core Level conformance for the uri.

Throws: XMLDBException with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur. ErrroCodes.INVALID_URI If the URI is not in a valid format.
ErrroCodes.NO_SUCH_DATABASE If a Database instance could not be found to handle the provided URI.

getDatabase

protected static Database getDatabase(String uri)

Retrieves the registered Database instance associated with the provided URI.

Parameters: uri The uri containing the database reference.

Returns: the requested Database instance.

getDatabases

public static Database[] getDatabases()

Returns a list of all available Database implementations that have been registered with this DatabaseManager.

Returns: An array of Database instances. One for each Database registered with the DatabaseManager. If no Database instances exist then an empty array is returned.

getProperty

public static String getProperty(String name)

Retrieves a property that has been set for the DatabaseManager.

Parameters: name The property name

Returns: The property value

registerDatabase

public static void registerDatabase(Database database)

Registers a new Database implementation with the DatabaseManager.

Parameters: database The database instance to register.

Throws: XMLDBException with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.
ErrorCodes.INVALID_DATABASE if the provided Database instance is invalid.

setProperty

public static void setProperty(String name, String value)

Sets a property for the DatabaseManager.

Parameters: name The property name value The value to set.

stripURIPrefix

protected static String stripURIPrefix(String uri)

Removes the URI_PREFIX from the front of the URI. This is so the database can focus on handling its own URIs.

Parameters: uri The full URI to strip.

Returns: The database specific portion of the URI.