1 /*******************************************************************************
\r
2 * Copyright (c) 2007, 2010 Association for Decentralized Information Management
\r
3 * in Industry THTH ry.
\r
4 * All rights reserved. This program and the accompanying materials
\r
5 * are made available under the terms of the Eclipse Public License v1.0
\r
6 * which accompanies this distribution, and is available at
\r
7 * http://www.eclipse.org/legal/epl-v10.html
\r
10 * VTT Technical Research Centre of Finland - initial API and implementation
\r
11 *******************************************************************************/
\r
12 package org.simantics.db;
\r
14 import java.util.Properties;
\r
16 import org.simantics.db.exception.DatabaseException;
\r
19 * The interface that every driver class must implement.
\r
22 * Each driver should supply a class that implements the Driver interface.
\r
25 * The {@link Manager} will try to load as many drivers as it can find and then
\r
26 * for any given connection request, it will ask each driver in turn to try to
\r
27 * connect to the target URL.
\r
30 * It is strongly recommended that each Driver class should be small and
\r
31 * standalone so that the Driver class can be loaded and queried without
\r
32 * bringing in vast quantities of supporting code.
\r
35 * When a Driver class is loaded, it should create an instance of itself and
\r
36 * register it with the DriverManager. This means that a user can load and
\r
37 * register a driver by calling
\r
40 * <code>Class.forName("foo.bah.Driver")</code>
\r
45 public interface Driver {
\r
47 * Driver name identifies the used database driver.
\r
48 * At any time there can be only one implementation registered for each name.
\r
50 * @return name of the driver instance.
\r
52 public String getName();
\r
54 * @return current database user agent. Can be null.
\r
56 public DatabaseUserAgent getDatabaseUserAgent(String address) throws DatabaseException;
\r
58 * Set user agent to be used by other methods. Can be null.
\r
60 * @param dbUserAgent defines error recover policy. Database specific.
\r
62 public void setDatabaseUserAgent(String address, DatabaseUserAgent dbUserAgent) throws DatabaseException;
\r
64 * Attempts to make a database connection to the given address.
\r
67 * The driver should throw a {@link DatabaseException} if it has trouble
\r
68 * connecting to the database.
\r
71 * The <code>java.util.Properties</code> argument can be used to pass
\r
72 * arbitrary string tag/value pairs as connection arguments. Normally at
\r
73 * least "user" and "password" properties should be included in the
\r
74 * <code>Properties</code> object.
\r
81 * @param address of the database session. Driver implementation specifies the address format.
\r
82 * @param properties a list of arbitrary string tag/value pairs as connection
\r
83 * arguments. Normally at least a "user" and "password" property
\r
84 * should be included.
\r
85 * @return a <code>Session</code> object that represents a connection to the
\r
87 * @throws DatabaseException TODO: separate possible errors (connection,
\r
88 * authentication, initialization)
\r
90 Session getSession(String address, Properties properties) throws DatabaseException;
\r
93 * Return database server that can be used to control a local database process.
\r
95 * @param address of the database server. Driver implementation specifies the address format.
\r
96 * @param properties a list of arbitrary string tag/value pairs as connection
\r
97 * arguments. Normally at least a "user" and "password" property
\r
98 * should be included.
\r
100 * @throws DatabaseException
\r
102 ServerI getServer(String address, Properties properties) throws DatabaseException;
\r
105 * Return database management object that can be used to control a local database.
\r
107 * @param address of the database. Driver implementation specifies the address format.
\r
108 * @param properties a list of arbitrary string tag/value pairs as connection
\r
109 * arguments. Normally at least a "user" and "password" property
\r
110 * should be included.
\r
111 * @return Management object for controlling database.
\r
112 * @throws DatabaseException
\r
114 Management getManagement(String address, Properties properties) throws DatabaseException;
\r
116 interface Management {
\r
118 * Existence of database means that the database has been created.
\r
120 * @return true if database exist.
\r
122 * @throws DatabaseException
\r
124 public boolean exist() throws DatabaseException;
\r
126 * Delete's database. After this {@link #exist()} must return false.
\r
128 * @throws DatabaseException if database deletion failed.
\r
129 * This may leave the database in an inconsistent state.
\r
130 * Recovery from this is implementation specific.
\r
132 public void delete() throws DatabaseException;
\r
134 * Creates a new database. After this {@link #exist()} must return false.
\r
136 * @throws DatabaseException if database creation failed.
\r
137 * This may leave the database in an inconsistent state.
\r
138 * Recovery from this is implementation specific.
\r
140 public void create() throws DatabaseException;
\r
142 * Removes caching data leaving only persistent data.
\r
144 * @throws DatabaseException
\r
146 public void purge() throws DatabaseException;
\r
147 public void shutdown() throws DatabaseException;
\r