org.exist.fluent
Class Database

java.lang.Object
  org.exist.fluent.Database

public class Database
extends Object

The global entry point to an embedded instance of the eXist database. The static methods on this class control the lifecycle of the database connection. It follows that there can be only one embedded database running in the JVM (or rather one per classloader, but that would probably be a bit confusing). To gain access to the contents of the database, you need to acquire a handle instance by logging in. All operations performed based on that instance will be executed using the permissions of the user associated with that instance. You can have any number of instances (including multiple ones for the same user), but cannot mix resources obtained from different instances. There is no need to explicitly release instances.

Here's a short example of how to start up the database, perform a query, and shut down:

 Database.startup(new File("conf.xml"));
 Database db = Database.login("admin", null);
 for (String name : db.getFolder("/").query().all("//user/@name").values())
   System.out.println("user: " + name);
 Database.shutdown();

Version:

$Revision: 1.26 $ ($Date: 2006/09/04 06:09:05 $)

Author:

Piotr Kaminski

Field Summary

static String

ROOT_PREFIX

Method Summary

ItemList	adopt(Node node)
static boolean	checkConsistency() Verify the internal consistency of the database's data structures.
boolean	contains(String path) Check whether the database contains a document or a folder with the given absolute path.
Folder	createFolder(String path) Create the folder for the given path.
static void	ensureStarted(File configFile) Deprecated. Please use a combination of isStarted() and startup(File).
static void	flush() Flush the contents of the database to disk.
Document	getDocument(String path) Get the document for the given absolute path.
Folder	getFolder(String path) Get the folder for the given path.
static boolean	isStarted() Return whether the database has been started and is currently running in this JVM.
static Database	login(String username, String password) Login to obtain access to the database.
NamespaceMap	namespaceBindings() Return the namespace bindings for this database instance.
QueryService	query(Collection<? extends Resource> context) Return a query service that runs queries over the given list of resources.
QueryService	query(Resource... context) Return a query service that runs queries over the given list of resources.
static void	remove(Listener listener) Remove the given listener from all trigger points on all sources.
void	setDefaultCharacterEncoding(String encoding) Set the default character encoding to be used when exporting XML files from the database.
void	setDefaultExportEncoding(String encoding) Deprecated. Renamed to setDefaultCharacterEncoding(String).
static void	shutdown() Shut down the database connection.
static void	startup(File configFile) Start up the database, configured using the given config file.

Methods inherited from class java.lang.Object

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

Field Detail

ROOT_PREFIX

public static final String ROOT_PREFIX

See Also:

Constant Field Values

Method Detail

startup

public static void startup(File configFile)

Start up the database, configured using the given config file. This method must be called precisely once before making use of any facilities offered in this package. The configuration file is typically called 'conf.xml' and you can find a sample one in the root directory of eXist's distribution.

Parameters:

configFile - the config file that specifies the database to use

Throws:

IllegalStateException - if the database has already been started

shutdown

public static void shutdown()

Shut down the database connection. If the database is not started, do nothing.

ensureStarted

@Deprecated
public static void ensureStarted(File configFile)

Deprecated. Please use a combination of isStarted() and startup(File).

Ensure the database is started. If the database is not started, start it with the given config file. If it is already started, make sure it was started with the same config file.

Parameters:

configFile - the config file that specifies the database to use

Throws:

IllegalStateException - if the database was already started with a different config file

isStarted

public static boolean isStarted()

Return whether the database has been started and is currently running in this JVM. This will be the case if startup(File) or ensureStarted(File) was previously called successfully and shutdown() was not yet called.

Returns:

true if the database has been started with any configuration file

flush

public static void flush()

Flush the contents of the database to disk. This ensures that all transactions are written out and the state of the database is synced. It shouldn't be necessary any more with the newly implemented transaction recovery and this method will probably be deprecated in the future.

checkConsistency

public static boolean checkConsistency()

Verify the internal consistency of the database's data structures. Log a fatal message if the database is corrupted, as well as error-level messages for all the problems found. If the database is corrupted, you can try using admin tools to reindex it, or back it up and restore it. However, there's a good chance it's unrecoverable.

Returns:

true if the database's internal data structures are consistent, false if the database is corrupted

login

public static Database login(String username,
                             String password)

Login to obtain access to the database. The password should be passed in the clear. If a user does not have a password set, pass in null. Note that all newly created databases have a user admin with no password set.

Parameters:

username - the username of the user being logged in

password - the password corresponding to that user name, or null if none

Returns:

an instance of the database configured for access by the given user

Throws:

DatabaseException - if the user could not be logged in

remove

public static void remove(Listener listener)

Remove the given listener from all trigger points on all sources.

Parameters:

listener - the listener to remove

setDefaultExportEncoding

@Deprecated
public void setDefaultExportEncoding(String encoding)

Deprecated. Renamed to setDefaultCharacterEncoding(String).

setDefaultCharacterEncoding

public void setDefaultCharacterEncoding(String encoding)

Set the default character encoding to be used when exporting XML files from the database. If not explicitly set, it defaults to UTF-8.

Parameters:

encoding -

namespaceBindings

public NamespaceMap namespaceBindings()

Return the namespace bindings for this database instance. They will be inherited by all resources derived from this instance.

Returns:

the namespace bindings for this database instance

adopt

public ItemList adopt(Node node)

contains

public boolean contains(String path)

Check whether the database contains a document or a folder with the given absolute path.

Parameters:

path - the absolute path of the document or folder to check

Returns:

true if there is a document or folder at the given path, false otherwise

getDocument

public Document getDocument(String path)

Get the document for the given absolute path. Namespace bindings will be inherited from this database.

Parameters:

path - the absolute path of the desired document

Returns:

the document at the given path

Throws:

DatabaseException - if the document is not found or something else goes wrong

getFolder

public Folder getFolder(String path)

Get the folder for the given path. Namespace mappings will be inherited from this database.

Parameters:

path - the address of the desired collection

Returns:

a collection bound to the given path

Throws:

DatabaseException - if the path does not identify a valid collection

createFolder

public Folder createFolder(String path)

Create the folder for the given path. Namespace mappings will be inherited from this database. If the folder does not exist, it is created along with all required ancestors.

Parameters:

path - the address of the desired collection

Returns:

a collection bound to the given path

query

public QueryService query(Resource... context)

Return a query service that runs queries over the given list of resources. The resources can be of different kinds, and come from different locations in the folder hierarchy. The service will inherit the database's namespace bindings, rather than the bindings of any given context resource.

Parameters:

context - the arbitrary collection of database objects over which to query

Returns:

a query service over the given resources

query

public QueryService query(Collection<? extends Resource> context)

Return a query service that runs queries over the given list of resources. The resources can be of different kinds, and come from different locations in the folder hierarchy. The service will inherit the database's namespace bindings, rather than the bindings of any given context resource.

Parameters:

context - the arbitrary collection of database objects over which to query; the collection is not copied, and the collection's contents are re-read every time the query is performed

Returns:

a query service over the given resources