bundles/org.simantics.db/src/org/simantics/db/Driver.java

   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
   8  *\r
   9  * Contributors:\r
  10  *     VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.db;\r
  13 \r
  14 import java.util.Properties;\r
  15 \r
  16 import org.simantics.db.exception.DatabaseException;\r
  17 \r
  18 /**\r
  19  * The interface that every driver class must implement.\r
  20  *\r
  21  * <P>\r
  22  * Each driver should supply a class that implements the Driver interface.\r
  23  *\r
  24  * <P>\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
  28  *\r
  29  * <P>\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
  33  *\r
  34  * <P>\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
  38  *\r
  39  * <pre>\r
  40  *   &lt;code&gt;Class.forName(&quot;foo.bah.Driver&quot;)&lt;/code&gt;\r
  41  * </pre>\r
  42  *\r
  43  * @see Manager\r
  44  */\r
  45 public interface Driver {\r
  46     /**\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
  49      *\r
  50      * @return name of the driver instance.\r
  51      */\r
  52     public String getName();\r
  53     /**\r
  54      * @return current database user agent. Can be null.\r
  55      */\r
  56     public DatabaseUserAgent getDatabaseUserAgent(String address) throws DatabaseException;\r
  57     /**\r
  58      * Set user agent to be used by other methods. Can be null.\r
  59      *\r
  60      * @param dbUserAgent defines error recover policy. Database specific.\r
  61      */\r
  62     public void setDatabaseUserAgent(String address, DatabaseUserAgent dbUserAgent) throws DatabaseException;\r
  63     /**\r
  64      * Attempts to make a database connection to the given address.\r
  65      *\r
  66      * <P>\r
  67      * The driver should throw a {@link DatabaseException} if it has trouble\r
  68      * connecting to the database.\r
  69      *\r
  70      * <P>\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
  75      *\r
  76      * Properties:<ol>\r
  77      *   <li>user</li>\r
  78      *   <li>password</li>\r
  79      * </ol>\r
  80      *\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
  86      *         database.\r
  87      * @throws DatabaseException TODO: separate possible errors (connection,\r
  88      *         authentication, initialization)\r
  89      */\r
  90     Session getSession(String address, Properties properties) throws DatabaseException;\r
  91 \r
  92     /**\r
  93      * Return database server that can be used to control a local database process.\r
  94      *\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
  99      * @return ServerI\r
 100      * @throws DatabaseException\r
 101      */\r
 102     ServerI getServer(String address, Properties properties) throws DatabaseException;\r
 103 \r
 104     /**\r
 105      * Return database management object that can be used to control a local database.\r
 106      *\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
 113      */\r
 114     Management getManagement(String address, Properties properties) throws DatabaseException;\r
 115 \r
 116     interface Management {\r
 117         /**\r
 118          * Existence of database means that the database has been created.\r
 119          *\r
 120          * @return true if database exist.\r
 121          *\r
 122          * @throws DatabaseException\r
 123          */\r
 124         public boolean exist() throws DatabaseException;\r
 125         /**\r
 126          * Delete's database. After this {@link #exist()} must return false.\r
 127          *\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
 131          */\r
 132         public void delete() throws DatabaseException;\r
 133         /**\r
 134          * Creates a new database. After this {@link #exist()} must return false.\r
 135          *\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
 139          */\r
 140         public void create() throws DatabaseException;\r
 141         /**\r
 142          * Removes caching data leaving only persistent data.\r
 143          *\r
 144          * @throws DatabaseException\r
 145          */\r
 146         public void purge() throws DatabaseException;\r
 147         public void shutdown() throws DatabaseException;\r
 148     }\r
 149 }\r