--- /dev/null
+/*******************************************************************************\r
+ * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
+ * in Industry THTH ry.\r
+ * All rights reserved. This program and the accompanying materials\r
+ * are made available under the terms of the Eclipse Public License v1.0\r
+ * which accompanies this distribution, and is available at\r
+ * http://www.eclipse.org/legal/epl-v10.html\r
+ *\r
+ * Contributors:\r
+ * VTT Technical Research Centre of Finland - initial API and implementation\r
+ *******************************************************************************/\r
+package org.simantics.db;\r
+\r
+import java.util.Properties;\r
+\r
+import org.simantics.db.exception.DatabaseException;\r
+\r
+/**\r
+ * The interface that every driver class must implement.\r
+ *\r
+ * <P>\r
+ * Each driver should supply a class that implements the Driver interface.\r
+ *\r
+ * <P>\r
+ * The {@link Manager} will try to load as many drivers as it can find and then\r
+ * for any given connection request, it will ask each driver in turn to try to\r
+ * connect to the target URL.\r
+ *\r
+ * <P>\r
+ * It is strongly recommended that each Driver class should be small and\r
+ * standalone so that the Driver class can be loaded and queried without\r
+ * bringing in vast quantities of supporting code.\r
+ *\r
+ * <P>\r
+ * When a Driver class is loaded, it should create an instance of itself and\r
+ * register it with the DriverManager. This means that a user can load and\r
+ * register a driver by calling\r
+ *\r
+ * <pre>\r
+ * <code>Class.forName("foo.bah.Driver")</code>\r
+ * </pre>\r
+ *\r
+ * @see Manager\r
+ */\r
+public interface Driver {\r
+ /**\r
+ * Driver name identifies the used database driver.\r
+ * At any time there can be only one implementation registered for each name.\r
+ *\r
+ * @return name of the driver instance.\r
+ */\r
+ public String getName();\r
+ /**\r
+ * @return current database user agent. Can be null.\r
+ */\r
+ public DatabaseUserAgent getDatabaseUserAgent(String address) throws DatabaseException;\r
+ /**\r
+ * Set user agent to be used by other methods. Can be null.\r
+ *\r
+ * @param dbUserAgent defines error recover policy. Database specific.\r
+ */\r
+ public void setDatabaseUserAgent(String address, DatabaseUserAgent dbUserAgent) throws DatabaseException;\r
+ /**\r
+ * Attempts to make a database connection to the given address.\r
+ *\r
+ * <P>\r
+ * The driver should throw a {@link DatabaseException} if it has trouble\r
+ * connecting to the database.\r
+ *\r
+ * <P>\r
+ * The <code>java.util.Properties</code> argument can be used to pass\r
+ * arbitrary string tag/value pairs as connection arguments. Normally at\r
+ * least "user" and "password" properties should be included in the\r
+ * <code>Properties</code> object.\r
+ *\r
+ * Properties:<ol>\r
+ * <li>user</li>\r
+ * <li>password</li>\r
+ * </ol>\r
+ *\r
+ * @param address of the database session. Driver implementation specifies the address format.\r
+ * @param properties a list of arbitrary string tag/value pairs as connection\r
+ * arguments. Normally at least a "user" and "password" property\r
+ * should be included.\r
+ * @return a <code>Session</code> object that represents a connection to the\r
+ * database.\r
+ * @throws DatabaseException TODO: separate possible errors (connection,\r
+ * authentication, initialization)\r
+ */\r
+ Session getSession(String address, Properties properties) throws DatabaseException;\r
+\r
+ /**\r
+ * Return database server that can be used to control a local database process.\r
+ *\r
+ * @param address of the database server. Driver implementation specifies the address format.\r
+ * @param properties a list of arbitrary string tag/value pairs as connection\r
+ * arguments. Normally at least a "user" and "password" property\r
+ * should be included.\r
+ * @return ServerI\r
+ * @throws DatabaseException\r
+ */\r
+ ServerI getServer(String address, Properties properties) throws DatabaseException;\r
+\r
+ /**\r
+ * Return database management object that can be used to control a local database.\r
+ *\r
+ * @param address of the database. Driver implementation specifies the address format.\r
+ * @param properties a list of arbitrary string tag/value pairs as connection\r
+ * arguments. Normally at least a "user" and "password" property\r
+ * should be included.\r
+ * @return Management object for controlling database.\r
+ * @throws DatabaseException\r
+ */\r
+ Management getManagement(String address, Properties properties) throws DatabaseException;\r
+\r
+ interface Management {\r
+ /**\r
+ * Existence of database means that the database has been created.\r
+ *\r
+ * @return true if database exist.\r
+ *\r
+ * @throws DatabaseException\r
+ */\r
+ public boolean exist() throws DatabaseException;\r
+ /**\r
+ * Delete's database. After this {@link #exist()} must return false.\r
+ *\r
+ * @throws DatabaseException if database deletion failed.\r
+ * This may leave the database in an inconsistent state.\r
+ * Recovery from this is implementation specific.\r
+ */\r
+ public void delete() throws DatabaseException;\r
+ /**\r
+ * Creates a new database. After this {@link #exist()} must return false.\r
+ *\r
+ * @throws DatabaseException if database creation failed.\r
+ * This may leave the database in an inconsistent state.\r
+ * Recovery from this is implementation specific.\r
+ */\r
+ public void create() throws DatabaseException;\r
+ /**\r
+ * Removes caching data leaving only persistent data.\r
+ *\r
+ * @throws DatabaseException\r
+ */\r
+ public void purge() throws DatabaseException;\r
+ public void shutdown() throws DatabaseException;\r
+ }\r
+}\r
Code Review / simantics / platform.git / blobdiff