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 }