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