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;
022:
023: import com.db4o.config.*;
024: import com.db4o.ext.*;
025: import com.db4o.foundation.*;
026: import com.db4o.foundation.network.*;
027: import com.db4o.internal.*;
028: import com.db4o.internal.cs.*;
029: import com.db4o.reflect.*;
030:
031: /**
032: * factory class to start db4o database engines.
033: * <br><br>This class provides static methods to<br>
034: * - open single-user databases {@link #openFile(String)} <br>
035: * - open db4o servers {@link #openServer(String, int)} <br>
036: * - connect to db4o servers {@link #openClient(String, int, String, String)} <br>
037: * - provide access to the global configuration context {@link #configure()} <br>
038: * - print the version number of this db4o version {@link #main(String[])}
039: * @see ExtDb4o ExtDb4o for extended functionality.
040: *
041: * @sharpen.rename Db4oFactory
042: */
043: public class Db4o {
044:
045: static final Config4Impl i_config = new Config4Impl();
046:
047: static {
048: Platform4.getDefaultConfiguration(i_config);
049: }
050:
051: /**
052: * prints the version name of this db4o version to <code>System.out</code>.
053: */
054: public static void main(String args[]) {
055: System.out.println(version());
056: }
057:
058: /**
059: * returns the global db4o
060: * {@link Configuration Configuration} context
061: * for the running JVM session.
062: * <br><br>
063: * The {@link Configuration Configuration}
064: * can be overriden in each
065: * {@link com.db4o.ext.ExtObjectContainer#configure ObjectContainer}.<br><br>
066: * @return the global {@link Configuration configuration} context
067: */
068: public static Configuration configure() {
069: return i_config;
070: }
071:
072: /**
073: * Creates a fresh {@link Configuration Configuration} instance.
074: *
075: * @return a fresh, independent configuration with all options set to their default values
076: */
077: public static Configuration newConfiguration() {
078: Config4Impl config = new Config4Impl();
079: Platform4.getDefaultConfiguration(config);
080: return config;
081: }
082:
083: /**
084: * Creates a clone of the global db4o {@link Configuration Configuration}.
085: *
086: * @return a fresh configuration with all option values set to the values
087: * currently configured for the global db4o configuration context
088: */
089: public static Configuration cloneConfiguration() {
090: return (Config4Impl) ((DeepClone) Db4o.configure())
091: .deepClone(null);
092: }
093:
094: /**
095: * Operates just like {@link Db4o#openClient(Configuration, String, int, String, String)}, but uses
096: * the global db4o {@link Configuration Configuration} context.
097: *
098: * opens an {@link ObjectContainer ObjectContainer}
099: * client and connects it to the specified named server and port.
100: * <br><br>
101: * The server needs to
102: * {@link ObjectServer#grantAccess allow access} for the specified user and password.
103: * <br><br>
104: * A client {@link ObjectContainer ObjectContainer} can be cast to
105: * {@link ExtClient ExtClient} to use extended
106: * {@link ExtObjectContainer ExtObjectContainer}
107: * and {@link ExtClient ExtClient} methods.
108: * <br><br>
109: * @param hostName the host name
110: * @param port the port the server is using
111: * @param user the user name
112: * @param password the user password
113: * @return an open {@link ObjectContainer ObjectContainer}
114: * @see ObjectServer#grantAccess
115: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
116: * @throws OldFormatException open operation failed because the database file
117: * is in old format and {@link com.db4o.config.Configuration#allowVersionUpdates(boolean)}
118: * is set to false.
119: * @throws InvalidPasswordException password supplied for the connection is
120: * invalid.
121: */
122: public static ObjectContainer openClient(String hostName, int port,
123: String user, String password) throws Db4oIOException,
124: OldFormatException, InvalidPasswordException {
125: return openClient(Db4o.cloneConfiguration(), hostName, port,
126: user, password);
127: }
128:
129: /**
130: * opens an {@link ObjectContainer ObjectContainer}
131: * client and connects it to the specified named server and port.
132: * <br><br>
133: * The server needs to
134: * {@link ObjectServer#grantAccess allow access} for the specified user and password.
135: * <br><br>
136: * A client {@link ObjectContainer ObjectContainer} can be cast to
137: * {@link ExtClient ExtClient} to use extended
138: * {@link ExtObjectContainer ExtObjectContainer}
139: * and {@link ExtClient ExtClient} methods.
140: * <br><br>
141: * @param config a custom {@link Configuration Configuration} instance to be obtained via {@link Db4o#newConfiguration()}
142: * @param hostName the host name
143: * @param port the port the server is using
144: * @param user the user name
145: * @param password the user password
146: * @return an open {@link ObjectContainer ObjectContainer}
147: * @see ObjectServer#grantAccess
148: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
149: * @throws OldFormatException open operation failed because the database file
150: * is in old format and {@link com.db4o.config.Configuration#allowVersionUpdates(boolean)}
151: * is set to false.
152: * @throws InvalidPasswordException password supplied for the connection is
153: * invalid.
154: */
155: public static ObjectContainer openClient(Configuration config,
156: String hostName, int port, String user, String password)
157: throws Db4oIOException, OldFormatException,
158: InvalidPasswordException {
159: return openClient(config, hostName, port, user, password,
160: new PlainSocketFactory());
161: }
162:
163: /**
164: * opens an {@link ObjectContainer ObjectContainer}
165: * client and connects it to the specified named server and port.
166: * <br><br>
167: * The server needs to
168: * {@link ObjectServer#grantAccess allow access} for the specified user and password.
169: * <br><br>
170: * A client {@link ObjectContainer ObjectContainer} can be cast to
171: * {@link ExtClient ExtClient} to use extended
172: * {@link ExtObjectContainer ExtObjectContainer}
173: * and {@link ExtClient ExtClient} methods.
174: * <br><br>
175: * @param config a custom {@link Configuration Configuration} instance to be obtained via {@link Db4o#newConfiguration()}
176: * @param hostName the host name
177: * @param port the port the server is using
178: * @param user the user name
179: * @param password the user password
180: * @return an open {@link ObjectContainer ObjectContainer}
181: * @see ObjectServer#grantAccess
182: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
183: * @throws OldFormatException open operation failed because the database file
184: * is in old format and {@link com.db4o.config.Configuration#allowVersionUpdates(boolean)}
185: * is set to false.
186: * @throws InvalidPasswordException password supplied for the connection is
187: * invalid.
188: */
189: public static ObjectContainer openClient(Configuration config,
190: String hostName, int port, String user, String password,
191: NativeSocketFactory socketFactory) throws Db4oIOException,
192: OldFormatException, InvalidPasswordException {
193: if (user == null || password == null) {
194: throw new InvalidPasswordException();
195: }
196: NetworkSocket networkSocket = new NetworkSocket(socketFactory,
197: hostName, port);
198: return new ClientObjectContainer(config, networkSocket, user,
199: password, true);
200: }
201:
202: /**
203: * Operates just like {@link Db4o#openFile(Configuration, String)}, but uses
204: * the global db4o {@link Configuration Configuration} context.
205: *
206: * opens an {@link ObjectContainer ObjectContainer}
207: * on the specified database file for local use.
208: * <br><br>A database file can only be opened once, subsequent attempts to open
209: * another {@link ObjectContainer ObjectContainer} against the same file will result in
210: * a {@link DatabaseFileLockedException DatabaseFileLockedException}.<br><br>
211: * Database files can only be accessed for readwrite access from one process
212: * (one Java VM) at one time. All versions except for db4o mobile edition use an
213: * internal mechanism to lock the database file for other processes.
214: * <br><br>
215: * @param databaseFileName an absolute or relative path to the database file
216: * @return an open {@link ObjectContainer ObjectContainer}
217: * @see Configuration#readOnly
218: * @see Configuration#encrypt
219: * @see Configuration#password
220: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
221: * @throws DatabaseFileLockedException the required database file is locked by
222: * another process.
223: * @throws IncompatibleFileFormatException runtime
224: * {@link com.db4o.config.Configuration configuration} is not compatible
225: * with the configuration of the database file.
226: * @throws OldFormatException open operation failed because the database file
227: * is in old format and {@link com.db4o.config.Configuration#allowVersionUpdates(boolean)}
228: * is set to false.
229: * @throws DatabaseReadOnlyException database was configured as read-only.
230: */
231: public static final ObjectContainer openFile(String databaseFileName)
232: throws Db4oIOException, DatabaseFileLockedException,
233: IncompatibleFileFormatException, OldFormatException,
234: DatabaseReadOnlyException {
235: return openFile(cloneConfiguration(), databaseFileName);
236: }
237:
238: /**
239: * opens an {@link ObjectContainer ObjectContainer}
240: * on the specified database file for local use.
241: * <br><br>A database file can only be opened once, subsequent attempts to open
242: * another {@link ObjectContainer ObjectContainer} against the same file will result in
243: * a {@link DatabaseFileLockedException DatabaseFileLockedException}.<br><br>
244: * Database files can only be accessed for readwrite access from one process
245: * (one Java VM) at one time. All versions except for db4o mobile edition use an
246: * internal mechanism to lock the database file for other processes.
247: * <br><br>
248: * @param config a custom {@link Configuration Configuration} instance to be obtained via {@link Db4o#newConfiguration()}
249: * @param databaseFileName an absolute or relative path to the database file
250: * @return an open {@link ObjectContainer ObjectContainer}
251: * @see Configuration#readOnly
252: * @see Configuration#encrypt
253: * @see Configuration#password
254: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
255: * @throws DatabaseFileLockedException the required database file is locked by
256: * another process.
257: * @throws IncompatibleFileFormatException runtime
258: * {@link com.db4o.config.Configuration configuration} is not compatible
259: * with the configuration of the database file.
260: * @throws OldFormatException open operation failed because the database file
261: * is in old format and {@link com.db4o.config.Configuration#allowVersionUpdates(boolean)}
262: * is set to false.
263: * @throws DatabaseReadOnlyException database was configured as read-only.
264: */
265: public static final ObjectContainer openFile(Configuration config,
266: String databaseFileName) throws Db4oIOException,
267: DatabaseFileLockedException,
268: IncompatibleFileFormatException, OldFormatException,
269: DatabaseReadOnlyException {
270: return ObjectContainerFactory.openObjectContainer(config,
271: databaseFileName);
272: }
273:
274: protected static final ObjectContainer openMemoryFile1(
275: Configuration config, MemoryFile memoryFile)
276: throws Db4oIOException, DatabaseFileLockedException,
277: OldFormatException {
278: if (memoryFile == null) {
279: memoryFile = new MemoryFile();
280: }
281:
282: if (Deploy.debug) {
283: System.out.println("db4o Debug is ON");
284: }
285:
286: ObjectContainer oc = new InMemoryObjectContainer(config,
287: memoryFile);
288: Messages.logMsg(i_config, 5, "Memory File");
289: return oc;
290: }
291:
292: /**
293: * Operates just like {@link Db4o#openServer(Configuration, String, int)}, but uses
294: * the global db4o {@link Configuration Configuration} context.
295: *
296: * opens an {@link ObjectServer ObjectServer}
297: * on the specified database file and port.
298: * <br><br>
299: * If the server does not need to listen on a port because it will only be used
300: * in embedded mode with {@link ObjectServer#openClient}, specify '0' as the
301: * port number.
302: * @param databaseFileName an absolute or relative path to the database file
303: * @param port the port to be used, or 0, if the server should not open a port,
304: * because it will only be used with {@link ObjectServer#openClient()}.
305: * Specify a value < 0 if an arbitrary free port should be chosen - see {@link ExtObjectServer#port()}.
306: * @return an {@link ObjectServer ObjectServer} listening
307: * on the specified port.
308: * @see Configuration#readOnly
309: * @see Configuration#encrypt
310: * @see Configuration#password
311: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
312: * @throws DatabaseFileLockedException the required database file is locked by
313: * another process.
314: * @throws IncompatibleFileFormatException runtime
315: * {@link com.db4o.config.Configuration configuration} is not compatible
316: * with the configuration of the database file.
317: * @throws OldFormatException open operation failed because the database file
318: * is in old format and {@link com.db4o.config.Configuration#allowVersionUpdates(boolean)}
319: * is set to false.
320: * @throws DatabaseReadOnlyException database was configured as read-only.
321: */
322: public static final ObjectServer openServer(
323: String databaseFileName, int port) throws Db4oIOException,
324: IncompatibleFileFormatException, OldFormatException,
325: DatabaseFileLockedException, DatabaseReadOnlyException {
326: return openServer(cloneConfiguration(), databaseFileName, port);
327: }
328:
329: /**
330: * opens an {@link ObjectServer ObjectServer}
331: * on the specified database file and port.
332: * <br><br>
333: * If the server does not need to listen on a port because it will only be used
334: * in embedded mode with {@link ObjectServer#openClient}, specify '0' as the
335: * port number.
336: * @param config a custom {@link Configuration Configuration} instance to be obtained via {@link Db4o#newConfiguration()}
337: * @param databaseFileName an absolute or relative path to the database file
338: * @param port the port to be used, or 0, if the server should not open a port,
339: * because it will only be used with {@link ObjectServer#openClient()}.
340: * Specify a value < 0 if an arbitrary free port should be chosen - see {@link ExtObjectServer#port()}.
341: * @return an {@link ObjectServer ObjectServer} listening
342: * on the specified port.
343: * @see Configuration#readOnly
344: * @see Configuration#encrypt
345: * @see Configuration#password
346: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
347: * @throws DatabaseFileLockedException the required database file is locked by
348: * another process.
349: * @throws IncompatibleFileFormatException runtime
350: * {@link com.db4o.config.Configuration configuration} is not compatible
351: * with the configuration of the database file.
352: * @throws OldFormatException open operation failed because the database file
353: * is in old format and {@link com.db4o.config.Configuration#allowVersionUpdates(boolean)}
354: * is set to false.
355: * @throws DatabaseReadOnlyException database was configured as read-only.
356: */
357: public static final ObjectServer openServer(Configuration config,
358: String databaseFileName, int port) throws Db4oIOException,
359: IncompatibleFileFormatException, OldFormatException,
360: DatabaseFileLockedException, DatabaseReadOnlyException {
361: return openServer(config, databaseFileName, port,
362: new PlainSocketFactory());
363: }
364:
365: /**
366: * opens an {@link ObjectServer ObjectServer}
367: * on the specified database file and port.
368: * <br><br>
369: * If the server does not need to listen on a port because it will only be used
370: * in embedded mode with {@link ObjectServer#openClient}, specify '0' as the
371: * port number.
372: * @param config a custom {@link Configuration Configuration} instance to be obtained via {@link Db4o#newConfiguration()}
373: * @param databaseFileName an absolute or relative path to the database file
374: * @param port the port to be used, or 0, if the server should not open a port,
375: * because it will only be used with {@link ObjectServer#openClient()}.
376: * Specify a value < 0 if an arbitrary free port should be chosen - see {@link ExtObjectServer#port()}.
377: * @param socketFactory the {@link NativeSocketFactory} to be used for socket creation
378: * @return an {@link ObjectServer ObjectServer} listening
379: * on the specified port.
380: * @see Configuration#readOnly
381: * @see Configuration#encrypt
382: * @see Configuration#password
383: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
384: * @throws DatabaseFileLockedException the required database file is locked by
385: * another process.
386: * @throws IncompatibleFileFormatException runtime
387: * {@link com.db4o.config.Configuration configuration} is not compatible
388: * with the configuration of the database file.
389: * @throws OldFormatException open operation failed because the database file
390: * is in old format and {@link com.db4o.config.Configuration#allowVersionUpdates(boolean)}
391: * is set to false.
392: * @throws DatabaseReadOnlyException database was configured as read-only.
393: */
394: public static final ObjectServer openServer(Configuration config,
395: String databaseFileName, int port,
396: NativeSocketFactory socketFactory) throws Db4oIOException,
397: IncompatibleFileFormatException, OldFormatException,
398: DatabaseFileLockedException, DatabaseReadOnlyException {
399: LocalObjectContainer stream = (LocalObjectContainer) openFile(
400: config, databaseFileName);
401: if (stream == null) {
402: return null;
403: }
404: synchronized (stream.lock()) {
405: return new ObjectServerImpl(stream, port, socketFactory);
406: }
407: }
408:
409: static Reflector reflector() {
410: return i_config.reflector();
411: }
412:
413: /**
414: * returns the version name of the used db4o version.
415: * <br><br>
416: * @return version information as a <code>String</code>.
417: */
418: public static final String version() {
419: return "db4o " + Db4oVersion.NAME;
420: }
421: }
|