001: /* Copyright (C) 2004 - 2007 db4objects Inc. http://www.db4o.com
002:
003: This file is part of the db4o open source object database.
004:
005: db4o is free software; you can redistribute it and/or modify it under
006: the terms of version 2 of the GNU General Public License as published
007: by the Free Software Foundation and as clarified by db4objects' GPL
008: interpretation policy, available at
009: http://www.db4o.com/about/company/legalpolicies/gplinterpretation/
010: Alternatively you can write to db4objects, Inc., 1900 S Norfolk Street,
011: Suite 350, San Mateo, CA 94403, USA.
012:
013: db4o is distributed in the hope that it will be useful, but WITHOUT ANY
014: WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: for more details.
017:
018: You should have received a copy of the GNU General Public License along
019: with this program; if not, write to the Free Software Foundation, Inc.,
020: 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
021: package com.db4o.osgi;
022:
023: import com.db4o.*;
024: import com.db4o.config.*;
025: import com.db4o.ext.*;
026:
027: /**
028: * This API is registered as an OSGi service by the db4o_osgi bundle. It can be accessed like this:
029: * <br><br>
030: * ServiceReference serviceRef = _context.getServiceReference(Db4oService.class.getName());
031: * <code>Db4oService db4oService = (Db4oService)bundleContext.getService(serviceRef);<br>
032: * Configuration config = db4oService.newConfiguration();<br>
033: * // ...<br>
034: * ObjectContainer database = db4oService.openFile(config,fileName);</code>
035: * <br><br>
036: * Subsequently, the database reference can be handled like any other db4o instance.
037: * <br><br>
038: * The main purpose of this service is to configure an OSGi bundle aware reflector for
039: * the database instance, so classes that are owned by the client bundle are accessible
040: * to the db4o engine. To emulate this behavior when using db4o directly through the
041: * exported packages of the db4o_osgi plugin, db4o can be configured like this:
042: * <br><br>
043: * <code>Configuration config = Db4o.newConfiguration();<br>
044: * config.reflectWith(new JdkReflector(SomeData.class.getClassLoader()));<br>
045: * // ...<br>
046: * ObjectContainer database = Db4o.openFile(config,fileName);</code>
047: * <br><br>
048: * Access through the service is recommended over direct usage, though, as the service
049: * may implement further OSGi specific features in the future.
050: *
051: * @see Db4o
052: * @see com.db4o.reflect.Reflector
053: * @see "org.osgi.framework.BundleContext"
054: */
055:
056: public interface Db4oService {
057:
058: /**
059: * Creates a fresh {@link Configuration Configuration} instance.
060: *
061: * @return a fresh, independent configuration with all options set to their default values
062: */
063: Configuration newConfiguration();
064:
065: /**
066: * Operates just like {@link Db4o#openClient(Configuration, String, int, String, String)}, but uses
067: * a newly created, vanilla {@link Configuration Configuration} context.
068: *
069: * opens an {@link ObjectContainer ObjectContainer}
070: * client and connects it to the specified named server and port.
071: * <br><br>
072: * The server needs to
073: * {@link ObjectServer#grantAccess allow access} for the specified user and password.
074: * <br><br>
075: * A client {@link ObjectContainer ObjectContainer} can be cast to
076: * {@link ExtClient ExtClient} to use extended
077: * {@link ExtObjectContainer ExtObjectContainer}
078: * and {@link ExtClient ExtClient} methods.
079: * <br><br>
080: * @param hostName the host name
081: * @param port the port the server is using
082: * @param user the user name
083: * @param password the user password
084: * @return an open {@link ObjectContainer ObjectContainer}
085: * @see ObjectServer#grantAccess
086: * @throws Db4oException
087: */
088:
089: ObjectContainer openClient(String hostName, int port, String user,
090: String password) throws Db4oException;
091:
092: /**
093: * opens an {@link ObjectContainer ObjectContainer}
094: * client and connects it to the specified named server and port.
095: * <br><br>
096: * The server needs to
097: * {@link ObjectServer#grantAccess allow access} for the specified user and password.
098: * <br><br>
099: * A client {@link ObjectContainer ObjectContainer} can be cast to
100: * {@link ExtClient ExtClient} to use extended
101: * {@link ExtObjectContainer ExtObjectContainer}
102: * and {@link ExtClient ExtClient} methods.
103: * <br><br>
104: * @param config a custom {@link Configuration Configuration} instance to be obtained via {@link Db4o#newConfiguration()}
105: * @param hostName the host name
106: * @param port the port the server is using
107: * @param user the user name
108: * @param password the user password
109: * @return an open {@link ObjectContainer ObjectContainer}
110: * @see ObjectServer#grantAccess
111: * @throws Db4oException
112: */
113: ObjectContainer openClient(Configuration config, String hostName,
114: int port, String user, String password)
115: throws Db4oException;
116:
117: /**
118: * Operates just like {@link Db4o#openFile(Configuration, String)}, but uses
119: * a newly created, vanilla {@link Configuration Configuration} context.
120: *
121: * opens an {@link ObjectContainer ObjectContainer}
122: * on the specified database file for local use.
123: * <br><br>A database file can only be opened once, subsequent attempts to open
124: * another {@link ObjectContainer ObjectContainer} against the same file will result in
125: * a {@link DatabaseFileLockedException DatabaseFileLockedException}.<br><br>
126: * Database files can only be accessed for readwrite access from one process
127: * (one Java VM) at one time. All versions except for db4o mobile edition use an
128: * internal mechanism to lock the database file for other processes.
129: * <br><br>
130: * @param databaseFileName an absolute or relative path to the database file
131: * @return an open {@link ObjectContainer ObjectContainer}
132: * @see Configuration#readOnly
133: * @see Configuration#encrypt
134: * @see Configuration#password
135: * @throws Db4oException
136: */
137: ObjectContainer openFile(String databaseFileName)
138: throws Db4oException;
139:
140: /**
141: * opens an {@link ObjectContainer ObjectContainer}
142: * on the specified database file for local use.
143: * <br><br>A database file can only be opened once, subsequent attempts to open
144: * another {@link ObjectContainer ObjectContainer} against the same file will result in
145: * a {@link DatabaseFileLockedException DatabaseFileLockedException}.<br><br>
146: * Database files can only be accessed for readwrite access from one process
147: * (one Java VM) at one time. All versions except for db4o mobile edition use an
148: * internal mechanism to lock the database file for other processes.
149: * <br><br>
150: * @param config a custom {@link Configuration Configuration} instance to be obtained via {@link Db4o#newConfiguration()}
151: * @param databaseFileName an absolute or relative path to the database file
152: * @return an open {@link ObjectContainer ObjectContainer}
153: * @see Configuration#readOnly
154: * @see Configuration#encrypt
155: * @see Configuration#password
156: * @throws Db4oException
157: */
158: ObjectContainer openFile(Configuration config,
159: String databaseFileName) throws Db4oException;
160:
161: /**
162: * Operates just like {@link Db4o#openServer(Configuration, String, int)}, but uses
163: * a newly created, vanilla {@link Configuration Configuration} context.
164: *
165: * opens an {@link ObjectServer ObjectServer}
166: * on the specified database file and port.
167: * <br><br>
168: * If the server does not need to listen on a port because it will only be used
169: * in embedded mode with {@link ObjectServer#openClient}, specify '0' as the
170: * port number.
171: * @param databaseFileName an absolute or relative path to the database file
172: * @param port the port to be used, or 0, if the server should not open a port,
173: * because it will only be used with {@link ObjectServer#openClient()}
174: * @return an {@link ObjectServer ObjectServer} listening
175: * on the specified port.
176: * @see Configuration#readOnly
177: * @see Configuration#encrypt
178: * @see Configuration#password
179: * @throws Db4oException
180: */
181: ObjectServer openServer(String databaseFileName, int port)
182: throws Db4oException;
183:
184: /**
185: * opens an {@link ObjectServer ObjectServer}
186: * on the specified database file and port.
187: * <br><br>
188: * If the server does not need to listen on a port because it will only be used
189: * in embedded mode with {@link ObjectServer#openClient}, specify '0' as the
190: * port number.
191: * @param config a custom {@link Configuration Configuration} instance to be obtained via {@link Db4o#newConfiguration()}
192: * @param databaseFileName an absolute or relative path to the database file
193: * @param port the port to be used, or 0, if the server should not open a port,
194: * because it will only be used with {@link ObjectServer#openClient()}
195: * @return an {@link ObjectServer ObjectServer} listening
196: * on the specified port.
197: * @see Configuration#readOnly
198: * @see Configuration#encrypt
199: * @see Configuration#password
200: * @throws Db4oException
201: */
202: ObjectServer openServer(Configuration config,
203: String databaseFileName, int port) throws Db4oException;
204: }
|