Package org.xmldb.api

Class 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.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) static java.util.Map<java.lang.String,​Database> databases  
      (package private) static java.util.concurrent.locks.StampedLock dbLock  
      (package private) static java.util.Properties properties  
      (package private) static boolean strictRegistrationBehavior  
      protected static java.lang.String URI_PREFIX  

    • Constructor Summary

      Constructors 
      Constructor Description
      DatabaseManager()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void deregisterDatabase​(Database database)
      Deregisters a Database implementation from the DatabaseManager.
      static Collection getCollection​(java.lang.String uri)
      Retrieves a Collection instance from the database for the given URI.
      static Collection getCollection​(java.lang.String uri, java.lang.String username, java.lang.String password)
      Retrieves a Collection instance from the database for the given URI.
      static java.lang.String getConformanceLevel​(java.lang.String uri)
      Returns the Core Level conformance value for the provided URI.
      protected static Database getDatabase​(java.lang.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 java.lang.String getProperty​(java.lang.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​(java.lang.String name, java.lang.String value)
      Sets a property for the DatabaseManager.
      protected static java.lang.String stripURIPrefix​(java.lang.String uri)
      Removes the URI_PREFIX from the front of the URI.
      private static void updateDatabases​(java.lang.String databaseName, Database database)  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • properties

        static final java.util.Properties properties

      • dbLock

        static final java.util.concurrent.locks.StampedLock dbLock

      • databases

        static final java.util.Map<java.lang.String,​Database> databases

      • strictRegistrationBehavior

        static boolean strictRegistrationBehavior

    • Constructor Detail

      • DatabaseManager

        public DatabaseManager()

    • Method Detail

      • 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.

      • registerDatabase

        public static void registerDatabase​(Database database)
                             throws XMLDBException
        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.

      • 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.
        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​(java.lang.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.
        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​(java.lang.String uri,
                                       java.lang.String username,
                                       java.lang.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.
        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.
        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. ErrroCodes.PERMISSION_DENIED If the username and password were not accepted by the database.

      • getConformanceLevel

        public static java.lang.String getConformanceLevel​(java.lang.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.
        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.

      • getProperty

        public static java.lang.String getProperty​(java.lang.String name)
        Retrieves a property that has been set for the DatabaseManager.
        Parameters:
        name - The property name
        Returns:
        The property value

      • setProperty

        public static void setProperty​(java.lang.String name,
                               java.lang.String value)
        Sets a property for the DatabaseManager.
        Parameters:
        name - The property name
        value - The value to set.

      • getDatabase

        protected static Database getDatabase​(java.lang.String uri)
                               throws XMLDBException
        Retrieves the registered Database instance associated with the provided URI.
        Parameters:
        uri - The uri containing the database reference.
        Returns:
        the requested Database instance.
        Throws:
        XMLDBException - if an error occurs whilst getting the database

      • stripURIPrefix

        protected static java.lang.String stripURIPrefix​(java.lang.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.
        Parameters:
        uri - The full URI to strip.
        Returns:
        The database specific portion of the URI.
        Throws:
        XMLDBException - if an error occurs whilst stripping the URI prefix