]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.db/src/org/simantics/db/Driver.java
Amendment to commit 373affcc
[simantics/platform.git] / bundles / org.simantics.db / src / org / simantics / db / Driver.java
1 /*******************************************************************************
2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management
3  * in Industry THTH ry.
4  * All rights reserved. This program and the accompanying materials
5  * are made available under the terms of the Eclipse Public License v1.0
6  * which accompanies this distribution, and is available at
7  * http://www.eclipse.org/legal/epl-v10.html
8  *
9  * Contributors:
10  *     VTT Technical Research Centre of Finland - initial API and implementation
11  *******************************************************************************/
12 package org.simantics.db;
13
14 import java.util.Properties;
15
16 import org.simantics.db.exception.DatabaseException;
17
18 /**
19  * The interface that every driver class must implement.
20  *
21  * <P>
22  * Each driver should supply a class that implements the Driver interface.
23  *
24  * <P>
25  * The {@link Manager} will try to load as many drivers as it can find and then
26  * for any given connection request, it will ask each driver in turn to try to
27  * connect to the target URL.
28  *
29  * <P>
30  * It is strongly recommended that each Driver class should be small and
31  * standalone so that the Driver class can be loaded and queried without
32  * bringing in vast quantities of supporting code.
33  *
34  * <P>
35  * When a Driver class is loaded, it should create an instance of itself and
36  * register it with the DriverManager. This means that a user can load and
37  * register a driver by calling
38  *
39  * <pre>
40  *   &lt;code&gt;Class.forName(&quot;foo.bah.Driver&quot;)&lt;/code&gt;
41  * </pre>
42  *
43  * @see Manager
44  */
45 public interface Driver {
46     /**
47      * Driver name identifies the used database driver.
48      * At any time there can be only one implementation registered for each name.
49      *
50      * @return name of the driver instance.
51      */
52     public String getName();
53     /**
54      * @return current database user agent. Can be null.
55      */
56     public DatabaseUserAgent getDatabaseUserAgent(String address) throws DatabaseException;
57     /**
58      * Set user agent to be used by other methods. Can be null.
59      *
60      * @param dbUserAgent defines error recover policy. Database specific.
61      */
62     public void setDatabaseUserAgent(String address, DatabaseUserAgent dbUserAgent) throws DatabaseException;
63     /**
64      * Attempts to make a database connection to the given address.
65      *
66      * <P>
67      * The driver should throw a {@link DatabaseException} if it has trouble
68      * connecting to the database.
69      *
70      * <P>
71      * The <code>java.util.Properties</code> argument can be used to pass
72      * arbitrary string tag/value pairs as connection arguments. Normally at
73      * least "user" and "password" properties should be included in the
74      * <code>Properties</code> object.
75      *
76      * Properties:<ol>
77      *   <li>user</li>
78      *   <li>password</li>
79      * </ol>
80      *
81      * @param address of the database session. Driver implementation specifies the address format.
82      * @param properties a list of arbitrary string tag/value pairs as connection
83      *        arguments. Normally at least a "user" and "password" property
84      *        should be included.
85      * @return a <code>Session</code> object that represents a connection to the
86      *         database.
87      * @throws DatabaseException TODO: separate possible errors (connection,
88      *         authentication, initialization)
89      */
90     Session getSession(String address, Properties properties) throws DatabaseException;
91
92     /**
93      * Return database server that can be used to control a local database process.
94      *
95      * @param address of the database server. Driver implementation specifies the address format.
96      * @param properties a list of arbitrary string tag/value pairs as connection
97      *        arguments. Normally at least a "user" and "password" property
98      *        should be included.
99      * @return ServerI
100      * @throws DatabaseException
101      */
102     ServerI getServer(String address, Properties properties) throws DatabaseException;
103
104     /**
105      * Return database management object that can be used to control a local database.
106      *
107      * @param address of the database. Driver implementation specifies the address format.
108      * @param properties a list of arbitrary string tag/value pairs as connection
109      *        arguments. Normally at least a "user" and "password" property
110      *        should be included.
111      * @return Management object for controlling database.
112      * @throws DatabaseException
113      */
114     Management getManagement(String address, Properties properties) throws DatabaseException;
115
116     interface Management {
117         /**
118          * Existence of database means that the database has been created.
119          *
120          * @return true if database exist.
121          *
122          * @throws DatabaseException
123          */
124         public boolean exist() throws DatabaseException;
125         /**
126          * Delete's database. After this {@link #exist()} must return false.
127          *
128          * @throws DatabaseException if database deletion failed.
129          * This may leave the database in an inconsistent state.
130          * Recovery from this is implementation specific.
131          */
132         public void delete() throws DatabaseException;
133         /**
134          * Creates a new database. After this {@link #exist()} must return false.
135          *
136          * @throws DatabaseException if database creation failed.
137          * This may leave the database in an inconsistent state.
138          * Recovery from this is implementation specific.
139          */
140         public void create() throws DatabaseException;
141         /**
142          * Removes caching data leaving only persistent data.
143          *
144          * @throws DatabaseException
145          */
146         public void purge() throws DatabaseException;
147         public void shutdown() throws DatabaseException;
148     }
149 }