KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > db4o > config > Configuration


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