org.xmldb.api
Class DatabaseManager
java.lang.Object
org.xmldb.api.DatabaseManager
public class DatabaseManager
extends java.lang.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.
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.
|
URI_PREFIX
protected static final String URI_PREFIX
deregisterDatabase
public static void deregisterDatabase(Database database)
throws XMLDBException
Deregisters a Database
implementation from the DatabaseManager
. Once a
Database
has been deregistered it can no longer be used to handle
requests.
database
- The Database
instance to deregister.
XMLDBException
- with expected error codes.
ErrorCodes.VENDOR_ERROR
for any vendor
specific errors that occur.
getCollection
public static Collection getCollection(String uri)
throws XMLDBException
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.
uri
- The database specific URI to use to locate the collection.
- A
Collection
instance for the requested collection or
null if the collection could not be found.
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)
throws XMLDBException
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.
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.
- A
Collection
instance for the requested collection or
null if the collection could not be found.
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.
ErrroCodes.PERMISSION_DENIED
If the username
and password
were not accepted by the database.
getConformanceLevel
public static String getConformanceLevel(String uri)
throws XMLDBException
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.
uri
- The database specific URI to use to locate the collection.
- The XML:DB Core Level conformance for the uri.
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)
throws XMLDBException
Retrieves the registered Database
instance associated with the provided
URI.
uri
- The uri containing the database reference.
- the requested
Database
instance.
getDatabases
public static Database[] getDatabases()
Returns a list of all available Database
implementations
that have been registered with this DatabaseManager
.
- 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
.
registerDatabase
public static void registerDatabase(Database database)
throws XMLDBException
Registers a new Database
implementation with the
DatabaseManager
.
database
- The database instance to register.
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
.
name
- The property namevalue
- The value to set.
stripURIPrefix
protected static String stripURIPrefix(String uri)
throws XMLDBException
Removes the URI_PREFIX from the front of the URI. This is so the database
can focus on handling its own URIs.
uri
- The full URI to strip.
- The database specific portion of the URI.