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.config;
022:
023: import java.io.IOException;
024: import java.io.PrintStream;
025:
026: import com.db4o.*;
027: import com.db4o.diagnostic.DiagnosticConfiguration;
028: import com.db4o.foundation.*;
029: import com.db4o.io.IoAdapter;
030: import com.db4o.reflect.Reflector;
031:
032: /**
033: * configuration interface.
034: * <br><br>This interface contains methods to configure db4o.<br><br>
035: * The global Configuration context is available with {@link com.db4o.Db4o#configure()}.
036: * When an ObjectContainer or ObjectServer is opened, the global Configuration
037: * context is cloned and copied into the ObjectContainer/ObjectServer.
038: * That means every ObjectContainer/ObjectServer gets it's own copy of
039: * configuration settings.<br><br>
040: * <b>Most configuration settings should be set before opening an
041: * ObjectContainer/ObjectServer</b>.
042: * <br><br>Some configuration settings can be modified on an open
043: * ObjectContainer/ObjectServer. The local Configuration context is
044: * available with {@link com.db4o.ext.ExtObjectContainer#configure()}
045: * and {@link com.db4o.ext.ExtObjectServer#configure()}.
046: */
047: public interface Configuration {
048:
049: /**
050: * sets the activation depth to the specified value.
051: * <br><br><b>Why activation?</b><br>
052: * When objects are instantiated from the database, the instantiation of member
053: * objects needs to be limited to a certain depth. Otherwise a single object
054: * could lead to loading the complete database into memory, if all objects where
055: * reachable from a single root object.<br><br>
056: * db4o uses the concept "depth", the number of field-to-field hops an object
057: * is away from another object. <b>The preconfigured "activation depth" db4o uses
058: * in the default setting is 5.</b>
059: * <br><br>Whenever an application iterates through the
060: * {@link com.db4o.ObjectSet ObjectSet} of a query result, the result objects
061: * will be activated to the configured activation depth.<br><br>
062: * A concrete example with the preconfigured activation depth of 5:<br>
063: * <pre>
064: * // Object foo is the result of a query, it is delivered by the ObjectSet
065: * Object foo = objectSet.next();</pre>
066: * foo.member1.member2.member3.member4.member5 will be a valid object<br>
067: * foo, member1, member2, member3 and member4 will be activated<br>
068: * member5 will be deactivated, all of it's members will be null<br>
069: * member5 can be activated at any time by calling
070: * {@link com.db4o.ObjectContainer#activate ObjectContainer#activate(member5, depth)}.
071: * <br><br>
072: * Note that raising the global activation depth will consume more memory and
073: * have negative effects on the performance of first-time retrievals. Lowering
074: * the global activation depth needs more individual activation work but can
075: * increase performance of queries.<br><br>
076: * {@link com.db4o.ObjectContainer#deactivate ObjectContainer#deactivate(Object, depth)}
077: * can be used to manually free memory by deactivating objects.<br><br>
078: * In client/server environment the same setting should be used on both
079: * client and server<br><br>.
080: * @param depth the desired global activation depth.
081: * @see ObjectClass#maximumActivationDepth configuring classes individually
082: */
083: public void activationDepth(int depth);
084:
085: /**
086: * gets the configured activation depth.
087: *
088: * @return the configured activation depth.
089: */
090: public int activationDepth();
091:
092: /**
093: * adds ConfigurationItems to be applied when
094: * an ObjectContainer or ObjectServer is opened.
095: * @param configurationItem the ConfigurationItem
096: */
097: public void add(ConfigurationItem configurationItem);
098:
099: /**
100: * adds a new Alias for a class, namespace or package.
101: * <br><br>Aliases can be used to persist classes in the running
102: * application to different persistent classes in a database file
103: * or on a db4o server.
104: * <br><br>Two simple Alias implementations are supplied along with
105: * db4o:<br>
106: * - {@link TypeAlias} provides an #equals() resolver to match
107: * names directly.<br>
108: * - {@link WildcardAlias} allows simple pattern matching
109: * with one single '*' wildcard character.<br>
110: * <br>
111: * It is possible to create
112: * own complex {@link Alias} constructs by creating own resolvers
113: * that implement the {@link Alias} interface.
114: * <br><br>
115: * Examples of concrete usecases:
116: * <br><br>
117: * <code>
118: * <b>// Creating an Alias for a single class</b><br>
119: * Db4o.configure().addAlias(<br>
120: *   new TypeAlias("com.f1.Pilot", "com.f1.Driver"));<br>
121: * <br><br>
122: * <b>// Accessing a .NET assembly from a Java package</b><br>
123: * Db4o.configure().addAlias(<br>
124: *   new WildcardAlias(<br>
125: *     "Tutorial.F1.*, Tutorial",<br>
126: *     "com.f1.*"));<br>
127: * <br><br>
128: * <b>// Mapping a Java package onto another</b><br>
129: * Db4o.configure().addAlias(<br>
130: *   new WildcardAlias(<br>
131: *     "com.f1.*",<br>
132: *     "com.f1.client*"));<br></code>
133: * <br><br>Aliases that translate the persistent name of a class to
134: * a name that already exists as a persistent name in the database
135: * (or on the server) are not permitted and will throw an exception
136: * when the database file is opened.
137: * <br><br>Aliases should be configured before opening a database file
138: * or connecting to a server.<br><br>
139: * In client/server environment this setting should be used on the server side.
140: */
141: public void addAlias(Alias alias);
142:
143: /**
144: * Removes an alias previously added with {@link Configuration#addAlias(Alias)}.
145: *
146: * @param alias the alias to remove
147: */
148: public void removeAlias(Alias alias);
149:
150: /**
151: * turns automatic database file format version updates on.
152: * <br><br>Upon db4o database file format version changes,
153: * db4o can automatically update database files to the
154: * current version. db4objects does not provide functionality
155: * to reverse this process. It is not ensured that updated
156: * database files can be read with older db4o versions.
157: * In some cases (Example: using ObjectManager) it may not be
158: * desirable to update database files automatically therefore
159: * automatic updating is turned off by default for
160: * security reasons.
161: * <br><br>Call this method to turn automatic database file
162: * version updating on.
163: * <br><br>If automatic updating is turned off, db4o will refuse
164: * to open database files that use an older database file format.<br><br>
165: * In client-server environment this setting should be used on both client
166: * and server.
167: */
168: public void allowVersionUpdates(boolean flag);
169:
170: /**
171: * turns automatic shutdown of the engine on and off.
172: * <br><br>Depending on the JDK, db4o uses one of the following
173: * two methods to shut down, if no more references to the ObjectContainer
174: * are being held or the JVM terminates:<br>
175: * - JDK 1.3 and above: <code>Runtime.addShutdownHook()</code><br>
176: * - JDK 1.2 and below: <code>System.runFinalizersOnExit(true)</code> and code
177: * in the finalizer.<br><br>
178: * Some JVMs have severe problems with both methods. For these rare cases the
179: * autoShutDown feature may be turned off.<br><br>
180: * The default and recommended setting is <code>true</code>.<br><br>
181: * In client-server environment this setting should be used on both client
182: * and server.
183: * @param flag whether db4o should shut down automatically.
184: */
185: public void automaticShutDown(boolean flag);
186:
187: /**
188: * sets the storage data blocksize for new ObjectContainers.
189: * <br><br>The standard setting is 1 allowing for a maximum
190: * database file size of 2GB. This value can be increased
191: * to allow larger database files, although some space will
192: * be lost to padding because the size of some stored objects
193: * will not be an exact multiple of the block size. A
194: * recommended setting for large database files is 8, since
195: * internal pointers have this length.<br><br>
196: * This setting is only effective when the database is first created, in
197: * client-server environment in most cases it means that the setting
198: * should be used on the server side.
199: * @param bytes the size in bytes from 1 to 127
200: */
201: public void blockSize(int bytes) throws GlobalOnlyConfigException;
202:
203: /**
204: * configures the size of BTree nodes in indexes.
205: * <br><br>Default setting: 100
206: * <br>Lower values will allow a lower memory footprint
207: * and more efficient reading and writing of small slots.
208: * <br>Higher values will reduce the overall number of
209: * read and write operations and allow better performance
210: * at the cost of more RAM use.<br><br>
211: * This setting should be used on both client and server in
212: * client-server environment.
213: * @param size the number of elements held in one BTree node.
214: */
215: public void bTreeNodeSize(int size);
216:
217: /**
218: * configures caching of BTree nodes.
219: * <br><br>Clean BTree nodes will be unloaded on #commit and
220: * #rollback unless they are configured as cached here.
221: * <br><br>Default setting: 0
222: * <br>Possible settings: 1, 2 or 3
223: * <br><br> The potential number of cached BTree nodes can be
224: * calculated with the following forumula:<br>
225: * maxCachedNodes = bTreeNodeSize ^ bTreeCacheHeight<br><br>
226: * This setting should be used on both client and server in
227: * client-server environment.
228: @param height the height of the cache from the root
229: */
230: public void bTreeCacheHeight(int height);
231:
232: /**
233: * turns callback methods on and off.
234: * <br><br>Callbacks are turned on by default.<br><br>
235: * A tuning hint: If callbacks are not used, you can turn this feature off, to
236: * prevent db4o from looking for callback methods in persistent classes. This will
237: * increase the performance on system startup.<br><br>
238: * In client/server environment this setting should be used on both
239: * client and server.
240: * @param flag false to turn callback methods off
241: * @see com.db4o.ext.ObjectCallbacks Using callbacks
242: */
243: public void callbacks(boolean flag);
244:
245: /**
246: * advises db4o to try instantiating objects with/without calling
247: * constructors.
248: * <br><br>
249: * Not all JDKs / .NET-environments support this feature. db4o will
250: * attempt, to follow the setting as good as the enviroment supports.
251: * In doing so, it may call implementation-specific features like
252: * sun.reflect.ReflectionFactory#newConstructorForSerialization on the
253: * Sun Java 1.4.x/5 VM (not available on other VMs) and
254: * FormatterServices.GetUninitializedObject() on
255: * the .NET framework (not available on CompactFramework).
256: * This setting may also be overridden for individual classes in
257: * {@link ObjectClass#callConstructor(boolean)}.
258: * <br><br>The default setting depends on the features supported by your current environment.<br><br>
259: * In client/server environment this setting should be used on both
260: * client and server.
261: * <br><br>
262: * @param flag - specify true, to request calling constructors, specify
263: * false to request <b>not</b> calling constructors.
264: * @see ObjectClass#callConstructor
265: */
266: public void callConstructors(boolean flag);
267:
268: /**
269: * turns
270: * {@link ObjectClass#maximumActivationDepth individual class activation depth configuration} on
271: * and off.
272: * <br><br>This feature is turned on by default.<br><br>
273: * In client/server environment this setting should be used on both
274: * client and server.<br><br>
275: * @param flag false to turn the possibility to individually configure class
276: * activation depths off
277: * @see Configuration#activationDepth Why activation?
278: */
279: public void classActivationDepthConfigurable(boolean flag);
280:
281: /**
282: * tuning feature: configures whether db4o checks all persistent classes upon system
283: * startup, for added or removed fields.
284: * <br><br>In a production environment this setting can be set to <code>false</code>,
285: * if all necessary classes have been stored to the database file and none of them
286: * have been modified since the last use.<br><br>
287: * In client/server environment this setting should be used on both
288: * client and server.
289: * <br><br>Default value:<br>
290: * <code>true</code>
291: * @param flag the desired setting
292: */
293: public void detectSchemaChanges(boolean flag);
294:
295: /**
296: * returns the configuration interface for diagnostics.
297: * @return the configuration interface for diagnostics.
298: */
299: public DiagnosticConfiguration diagnostic();
300:
301: /**
302: * turns commit recovery off.
303: * <br><br>db4o uses a two-phase commit algorithm. In a first step all intended
304: * changes are written to a free place in the database file, the "transaction commit
305: * record". In a second step the
306: * actual changes are performed. If the system breaks down during commit, the
307: * commit process is restarted when the database file is opened the next time.
308: * On very rare occasions (possibilities: hardware failure or editing the database
309: * file with an external tool) the transaction commit record may be broken. In this
310: * case, this method can be used to try to open the database file without commit
311: * recovery. The method should only be used in emergency situations after consulting
312: * db4o support.
313: */
314: public void disableCommitRecovery();
315:
316: /**
317: * tuning feature: configures the minimum size of free space slots in the database file
318: * that are to be reused.
319: * <br><br>When objects are updated or deleted, the space previously occupied in the
320: * database file is marked as "free", so it can be reused. db4o maintains two lists
321: * in RAM, sorted by address and by size. Adjacent entries are merged. After a large
322: * number of updates or deletes have been executed, the lists can become large, causing
323: * RAM consumption and performance loss for maintenance. With this method you can
324: * specify an upper bound for the byte slot size to discard.
325: * <br><br>Pass <code>Integer.MAX_VALUE</code> to this method to discard all free slots for
326: * the best possible startup time.<br><br>
327: * The downside of setting this value: Database files will necessarily grow faster.
328: * <br><br>Default value:<br>
329: * <code>0</code> all space is reused
330: * @param byteCount Slots with this size or smaller will be lost.
331: * @deprecated please call Db4o.configure().freespace().discardSmallerThan()
332: */
333: public void discardFreeSpace(int byteCount);
334:
335: /**
336: * configures the use of encryption.
337: * <br><br>This method needs to be called <b>before</b> a database file
338: * is created with the first
339: * {@link com.db4o.Db4o#openFile(java.lang.String)}.
340: * <br><br>If encryption is set to true,
341: * you need to supply a password to seed the encryption mechanism.<br><br>
342: * db4o database files keep their encryption format after creation.<br><br>
343: *
344: * @deprecated use a custom encrypting {@link IoAdapter} instead
345:
346: * @param flag true for turning encryption on, false for turning encryption
347: * off.
348: * @see #password
349: */
350: public void encrypt(boolean flag) throws GlobalOnlyConfigException;
351:
352: /**
353: * configures whether Exceptions are to be thrown, if objects can not be stored.
354: * <br><br>db4o requires the presence of a constructor that can be used to
355: * instantiate objects. If no default public constructor is present, all
356: * available constructors are tested, whether an instance of the class can
357: * be instantiated. Null is passed to all constructor parameters.
358: * The first constructor that is successfully tested will
359: * be used throughout the running db4o session. If an instance of the class
360: * can not be instantiated, the object will not be stored. By default,
361: * execution will continue without any message or error. This method can
362: * be used to configure db4o to throw an
363: * {@link com.db4o.ext.ObjectNotStorableException ObjectNotStorableException}
364: * if an object can not be stored.
365: * <br><br>
366: * The default for this setting is <b>false</b>.<br><br>
367: * In client/server environment this setting should be used on both
368: * client and server.<br><br>
369: * @param flag true to throw Exceptions if objects can not be stored.
370: */
371: public void exceptionsOnNotStorable(boolean flag);
372:
373: /**
374: * configures file buffers to be flushed during transaction commits.
375: * <br><br>
376: * db4o uses a resume-commit-on-crash strategy to ensure ACID transactions.
377: * When a transaction commits,<br>
378: * - (1) a list "pointers that are to be modified" is written to the database file,<br>
379: * - (2) the database file is switched into "in-commit" mode, <br>
380: * - (3) the pointers are actually modified in the database file,<br>
381: * - (4) the database file is switched to "not-in-commit" mode.<br>
382: * If the system is halted by a hardware or power failure <br>
383: * - before (2)<br>
384: * all objects will be available as before the commit<br>
385: * - between (2) and (4)
386: * the commit is restarted when the database file is opened the next time, all pointers
387: * will be read from the "pointers to be modified" list and all of them will be modified
388: * to the state they are intended to have after commit<br>
389: * - after (4)
390: * no work is necessary, the transaction is committed.
391: * <br><br>
392: * In order for the above to be 100% failsafe, the order of writes to the
393: * storage medium has to be obeyed. On operating systems that use in-memory
394: * file caching, the OS cache may revert the order of writes to optimize
395: * file performance.<br><br>
396: * db4o enforces the correct write order by flushing file
397: * buffers after every single one of the above steps during transaction
398: * commit. Flush calls have a strong impact on performance. It is possible to
399: * tune an application by turning flushing off, at the risc of less security
400: * for hardware-, power- or operating system failures.<br><br>
401: * In client/server environment this setting should be used on both
402: * client and server.<br><br>
403: * @param flag true for flushing file buffers
404: */
405: public void flushFileBuffers(boolean flag);
406:
407: /**
408: * returns the freespace configuration interface.
409: */
410: public FreespaceConfiguration freespace();
411:
412: /**
413: * configures db4o to generate UUIDs for stored objects.
414: *
415: * @param setting one of the following values:<br>
416: * -1 - off<br>
417: * 1 - configure classes individually<br>
418: * Integer.MAX_Value - on for all classes<br><br>
419: * This setting should be used when the database is first created.
420: * @deprecated Use {@link #generateUUIDs(ConfigScope)} instead.
421: */
422: public void generateUUIDs(int setting);
423:
424: /**
425: * configures db4o to generate UUIDs for stored objects.
426: *
427: * This setting should be used when the database is first created.<br><br>
428: * @param setting the scope for UUID generation: disabled, generate for all classes, or configure individually
429: */
430: public void generateUUIDs(ConfigScope setting);
431:
432: /**
433: * configures db4o to generate version numbers for stored objects.
434: *
435: * @param setting one of the following values:<br>
436: * -1 - off<br>
437: * 1 - configure classes individually<br>
438: * Integer.MAX_Value - on for all classes<br><br>
439: * This setting should be used when the database is first created.
440: * @deprecated Use {@link #generateVersionNumbers(ConfigScope)} instead.
441: */
442: public void generateVersionNumbers(int setting);
443:
444: /**
445: * configures db4o to generate version numbers for stored objects.
446: *
447: * This setting should be used when the database is first created.
448: * @param setting the scope for version number generation: disabled, generate for all classes, or configure individually
449: */
450: public void generateVersionNumbers(ConfigScope setting);
451:
452: /**
453: * configures db4o to call #intern() on strings upon retrieval.
454: * In client/server environment the setting should be used on both
455: * client and server.
456: * @param flag true to intern strings
457: */
458: public void internStrings(boolean flag);
459:
460: /**
461: * returns true if strings will be interned.
462: */
463: public boolean internStrings();
464:
465: /**
466: * allows to configure db4o to use a customized byte IO adapter.
467: * <br><br>Derive from the abstract class {@link IoAdapter} to
468: * write your own. Possible usecases could be improved performance
469: * with a native library, mirrored write to two files, encryption or
470: * read-on-write fail-safety control.<br><br>An example of a custom
471: * io adapter can be found in xtea_db4o community project:<br>
472: * http://developer.db4o.com/ProjectSpaces/view.aspx/XTEA<br><br>
473: * In client-server environment this setting should be used on the server
474: * (adapter class must be available)<br><br>
475: * @param adapter - the IoAdapter
476: */
477: public void io(IoAdapter adapter) throws GlobalOnlyConfigException;
478:
479: /**
480: * allows to mark fields as transient with custom attributes.
481: * <br><br>.NET only: Call this method with the attribute name that you
482: * wish to use to mark fields as transient. Multiple transient attributes
483: * are possible by calling this method multiple times with different
484: * attribute names.<br><br>
485: * In client/server environment the setting should be used on both
486: * client and server.<br><br>
487: * @param attributeName - the fully qualified name of the attribute, including
488: * it's namespace
489: */
490: public void markTransient(String attributeName);
491:
492: /**
493: * sets the detail level of db4o messages. Messages will be output to the
494: * configured output {@link java.io.PrintStream PrintStream}.
495: * <br><br>
496: * Level 0 - no messages<br>
497: * Level 1 - open and close messages<br>
498: * Level 2 - messages for new, update and delete<br>
499: * Level 3 - messages for activate and deactivate<br><br>
500: * When using client-server and the level is set to 0, the server will override this and set it to 1. To get around this you can set the level to -1. This has the effect of not returning any messages.<br><br>
501: * In client-server environment this setting can be used on client or on server
502: * depending on which information do you want to track (server side provides more
503: * detailed information).<br><br>
504: * @param level integer from 0 to 3
505: * @see #setOut
506: */
507: public void messageLevel(int level);
508:
509: /**
510: * can be used to turn the database file locking thread off.
511: * <br><br>Since Java does not support file locking up to JDK 1.4,
512: * db4o uses an additional thread per open database file to prohibit
513: * concurrent access to the same database file by different db4o
514: * sessions in different VMs.<br><br>
515: * To improve performance and to lower ressource consumption, this
516: * method provides the possibility to prevent the locking thread
517: * from being started.<br><br><b>Caution!</b><br>If database file
518: * locking is turned off, concurrent write access to the same
519: * database file from different JVM sessions will <b>corrupt</b> the
520: * database file immediately.<br><br> This method
521: * has no effect on open ObjectContainers. It will only affect how
522: * ObjectContainers are opened.<br><br>
523: * The default setting is <code>true</code>.<br><br>
524: * In client-server environment this setting should be used on both client and server.<br><br>
525: * @param flag <code>false</code> to turn database file locking off.
526: */
527: public void lockDatabaseFile(boolean flag);
528:
529: /**
530: * returns an {@link ObjectClass ObjectClass} object
531: * to configure the specified class.
532: * <br><br>
533: * The clazz parameter can be any of the following:<br>
534: * - a fully qualified classname as a String.<br>
535: * - a Class object.<br>
536: * - any other object to be used as a template.<br><br>
537: * @param clazz class name, Class object, or example object.<br><br>
538: * @return an instance of an {@link ObjectClass ObjectClass}
539: * object for configuration.
540: */
541: public ObjectClass objectClass(Object clazz);
542:
543: /**
544: * If set to true, db4o will try to optimize native queries
545: * dynamically at query execution time, otherwise it will
546: * run native queries in unoptimized mode as SODA evaluations.
547: * On the Java platform the jars needed for native query
548: * optimization (db4o-X.x-nqopt.jar, bloat-X.x.jar) have to be
549: * on the classpath at runtime for this
550: * switch to have effect.
551: * <br><br>The default setting is <code>true</code>.<br><br>
552: * In client-server environment this setting should be used on both client and server.<br><br>
553: * @param optimizeNQ true, if db4o should try to optimize
554: * native queries at query execution time, false otherwise
555: */
556: public void optimizeNativeQueries(boolean optimizeNQ);
557:
558: /**
559: * indicates whether Native Queries will be optimized dynamically.
560: * @return boolean true if Native Queries will be optimized
561: * dynamically.
562: * @see #optimizeNativeQueries
563: */
564: public boolean optimizeNativeQueries();
565:
566: /**
567: * protects the database file with a password.
568: * <br><br>To set a password for a database file, this method needs to be
569: * called <b>before</b> a database file is created with the first
570: * {@link com.db4o.Db4o#openFile}.
571: * <br><br>All further attempts to open
572: * the file, are required to set the same password.<br><br>The password
573: * is used to seed the encryption mechanism, which makes it impossible
574: * to read the database file without knowing the password.<br><br>
575: *
576: * @deprecated use a custom encrypting {@link IoAdapter} instead
577: *
578: * @param pass the password to be used.
579: */
580: public void password(String pass) throws GlobalOnlyConfigException;
581:
582: /**
583: * returns the Query configuration interface.
584: */
585: public QueryConfiguration queries();
586:
587: /**
588: * turns readOnly mode on and off.
589: * <br><br>This method configures the mode in which subsequent calls to
590: * {@link com.db4o.Db4o#openFile Db4o.openFile()} will open files.
591: * <br><br>Readonly mode allows to open an unlimited number of reading
592: * processes on one database file. It is also convenient
593: * for deploying db4o database files on CD-ROM.<br><br>
594: * In client-server environment this setting should be used on the server side
595: * in embedded mode and ONLY on client side in networked mode.<br><br>
596: * @param flag <code>true</code> for configuring readOnly mode for subsequent
597: * calls to {@link com.db4o.Db4o#openFile Db4o.openFile()}.
598: */
599: public void readOnly(boolean flag);
600:
601: /**
602: * configures the use of a specially designed reflection implementation.
603: * <br><br>
604: * db4o internally uses java.lang.reflect.* by default. On platforms that
605: * do not support this package, customized implementations may be written
606: * to supply all the functionality of the interfaces in the com.db4o.reflect
607: * package. This method can be used to install a custom reflection
608: * implementation.<br><br>
609: * In client-server environment this setting should be used on the server side
610: * (reflector class must be available)<br><br>
611: */
612: public void reflectWith(Reflector reflector);
613:
614: /**
615: * forces analysis of all Classes during a running session.
616: * <br><br>
617: * This method may be useful in combination with a modified ClassLoader and
618: * allows exchanging classes during a running db4o session.<br><br>
619: * Calling this method on the global Configuration context will refresh
620: * the classes in all db4o sessions in the running VM. Calling this method
621: * in an ObjectContainer Configuration context, only the classes of the
622: * respective ObjectContainer will be refreshed.<br><br>
623: * @see #setClassLoader
624: */
625: public void refreshClasses();
626:
627: /**
628: * tuning feature only: reserves a number of bytes in database files.
629: * <br><br>The global setting is used for the creation of new database
630: * files. Continous calls on an ObjectContainer Configuration context
631: * (see {@link com.db4o.ext.ExtObjectContainer#configure()}) will
632: * continually allocate space.
633: * <br><br>The allocation of a fixed number of bytes at one time
634: * makes it more likely that the database will be stored in one
635: * chunk on the mass storage. Less read/write head movevement can result
636: * in improved performance.<br><br>
637: * <b>Note:</b><br> Allocated space will be lost on abnormal termination
638: * of the database engine (hardware crash, VM crash). A Defragment run
639: * will recover the lost space. For the best possible performance, this
640: * method should be called before the Defragment run to configure the
641: * allocation of storage space to be slightly greater than the anticipated
642: * database file size.
643: * <br><br>
644: * In client-server environment this setting should be used on the server side. <br><br>
645: * Default configuration: 0<br><br>
646: * @param byteCount the number of bytes to reserve
647: */
648: public void reserveStorageSpace(long byteCount)
649: throws DatabaseReadOnlyException, NotSupportedException;
650:
651: /**
652: * configures the path to be used to store and read
653: * Blob data.
654: * <br><br>
655: * In client-server environment this setting should be used on the
656: * server side. <br><br>
657: * @param path the path to be used
658: */
659: public void setBlobPath(String path) throws IOException;
660:
661: /**
662: * configures db4o to use a custom ClassLoader.
663: * <br><br>
664: * @param classLoader the ClassLoader to be used
665: * @deprecated use reflectWith(new JdkReflector(classLoader)) instead
666: */
667: public void setClassLoader(Object classLoader);
668:
669: /**
670: * Assigns a {@link java.io.PrintStream PrintStream} where db4o is to print its event messages.
671: * <br><br>Messages are useful for debugging purposes and for learning
672: * to understand, how db4o works. The message level can be raised with
673: * {@link Configuration#messageLevel(int)}
674: * to produce more detailed messages.
675: * <br><br>Use <code>setOut(System.out)</code> to print messages to the
676: * console.<br><br>
677: * In client-server environment this setting should be used on the same side
678: * where {@link Configuration#messageLevel(int)} is used.<br><br>
679: * @param outStream the new <code>PrintStream</code> for messages.
680: * @see #messageLevel
681: */
682: public void setOut(PrintStream outStream);
683:
684: /**
685: * tuning feature: configures whether db4o should try to instantiate one instance
686: * of each persistent class on system startup.
687: * <br><br>In a production environment this setting can be set to <code>false</code>,
688: * if all persistent classes have public default constructors.
689: * <br><br>
690: * In client-server environment this setting should be used on both client and server
691: * side. <br><br>
692: * Default value:<br>
693: * <code>true</code>
694: * @param flag the desired setting
695: */
696: public void testConstructors(boolean flag);
697:
698: /**
699: * configures the storage format of Strings.
700: * <br><br>This method needs to be called <b>before</b> a database file
701: * is created with the first
702: * {@link com.db4o.Db4o#openFile} or {@link com.db4o.Db4o#openServer}.
703: * db4o database files keep their string format after creation.<br><br>
704: * Turning Unicode support off reduces the file storage space for strings
705: * by factor 2 and improves performance.<br><br>
706: * Default setting: <b>true</b><br><br>
707: * @param flag <code>true</code> for turning Unicode support on, <code>false</code> for turning
708: * Unicode support off.
709: */
710: public void unicode(boolean flag);
711:
712: /**
713: * specifies the global updateDepth.
714: * <br><br>see the documentation of
715: * {@link com.db4o.ObjectContainer#set }
716: * for further details.<br><br>
717: * The value be may be overridden for individual classes.<br><br>
718: * The default setting is 1: Only the object passed to
719: * {@link com.db4o.ObjectContainer#set}
720: * will be updated.<br><br>
721: * In client-server environment this setting should be used on both client and
722: * server sides.<br><br>
723: * @param depth the depth of the desired update.
724: * @see ObjectClass#updateDepth
725: * @see ObjectClass#cascadeOnUpdate
726: * @see com.db4o.ext.ObjectCallbacks Using callbacks
727: */
728: public void updateDepth(int depth);
729:
730: /**
731: * turns weak reference management on or off.
732: * <br><br>
733: * This method must be called before opening a database.
734: * <br><br>
735: * Performance may be improved by running db4o without using weak
736: * references durring memory management at the cost of higher
737: * memory consumption or by alternatively implementing a manual
738: * memory management scheme using
739: * {@link com.db4o.ext.ExtObjectContainer#purge(java.lang.Object)}
740: * <br><br>Setting the value to <code>false</code> causes db4o to use hard
741: * references to objects, preventing the garbage collection process
742: * from disposing of unused objects.
743: * <br><br>The default setting is <code>true</code>.
744: * <br><br>Ignored on JDKs before 1.2.
745: */
746: public void weakReferences(boolean flag);
747:
748: /**
749: * configures the timer for WeakReference collection.
750: * <br><br>The default setting is 1000 milliseconds.
751: * <br><br>Configure this setting to zero to turn WeakReference
752: * collection off.
753: * <br><br>Ignored on JDKs before 1.2.<br><br>
754: * @param milliseconds the time in milliseconds
755: */
756: public void weakReferenceCollectionInterval(int milliseconds);
757:
758: /**
759: * returns client/server configuration interface.
760: */
761: public ClientServerConfiguration clientServer();
762: }
|