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: /**
024: * configuration interface for classes.
025: * <br><br>
026: * Use the global Configuration object to configure db4o before opening an
027: * {@link com.db4o.ObjectContainer ObjectContainer}.<br><br>
028: * <b>Example:</b><br>
029: * <code>
030: * Configuration config = Db4o.configure();<br>
031: * ObjectClass oc = config.objectClass("package.className");<br>
032: * oc.updateDepth(3);<br>
033: * oc.minimumActivationDepth(3);<br>
034: * </code>
035: */
036: public interface ObjectClass {
037:
038: /**
039: * advises db4o to try instantiating objects of this class with/without
040: * calling constructors.
041: * <br><br>
042: * Not all JDKs / .NET-environments support this feature. db4o will
043: * attempt, to follow the setting as good as the enviroment supports.
044: * In doing so, it may call implementation-specific features like
045: * sun.reflect.ReflectionFactory#newConstructorForSerialization on the
046: * Sun Java 1.4.x/5 VM (not available on other VMs) and
047: * FormatterServices.GetUninitializedObject() on
048: * the .NET framework (not available on CompactFramework).<br><br>
049: * This setting may also be set globally for all classes in
050: * {@link Configuration#callConstructors(boolean)}.<br><br>
051: * In client-server environment this setting should be used on both
052: * client and server. <br><br>
053: * @param flag - specify true, to request calling constructors, specify
054: * false to request <b>not</b> calling constructors.
055: * @see Configuration#callConstructors
056: */
057: public void callConstructor(boolean flag);
058:
059: /**
060: * sets cascaded activation behaviour.
061: * <br><br>
062: * Setting cascadeOnActivate to true will result in the activation
063: * of all member objects if an instance of this class is activated.
064: * <br><br>
065: * The default setting is <b>false</b>.<br><br>
066: * In client-server environment this setting should be used on both
067: * client and server. <br><br>
068: * @param flag whether activation is to be cascaded to member objects.
069: * @see ObjectField#cascadeOnActivate
070: * @see com.db4o.ObjectContainer#activate
071: * @see com.db4o.ext.ObjectCallbacks Using callbacks
072: * @see Configuration#activationDepth Why activation?
073: */
074: public void cascadeOnActivate(boolean flag);
075:
076: /**
077: * sets cascaded delete behaviour.
078: * <br><br>
079: * Setting cascadeOnDelete to true will result in the deletion of
080: * all member objects of instances of this class, if they are
081: * passed to
082: * {@link com.db4o.ObjectContainer#delete(Object)}.
083: * <br><br>
084: * <b>Caution !</b><br>
085: * This setting will also trigger deletion of old member objects, on
086: * calls to {@link com.db4o.ObjectContainer#set(Object)}.<br><br>
087: * An example of the behaviour:<br>
088: * <code>
089: * ObjectContainer con;<br>
090: * Bar bar1 = new Bar();<br>
091: * Bar bar2 = new Bar();<br>
092: * foo.bar = bar1;<br>
093: * con.set(foo); // bar1 is stored as a member of foo<br>
094: * foo.bar = bar2;<br>
095: * con.set(foo); // bar2 is stored as a member of foo
096: * </code><br>The last statement will <b>also</b> delete bar1 from the
097: * ObjectContainer, no matter how many other stored objects hold references
098: * to bar1.
099: * <br><br>
100: * The default setting is <b>false</b>.<br><br>
101: * In client-server environment this setting should be used on both
102: * client and server. <br><br>
103: * @param flag whether deletes are to be cascaded to member objects.
104: * @see ObjectField#cascadeOnDelete
105: * @see com.db4o.ObjectContainer#delete
106: * @see com.db4o.ext.ObjectCallbacks Using callbacks
107: */
108: public void cascadeOnDelete(boolean flag);
109:
110: /**
111: * sets cascaded update behaviour.
112: * <br><br>
113: * Setting cascadeOnUpdate to true will result in the update
114: * of all member objects if a stored instance of this class is passed
115: * to {@link com.db4o.ObjectContainer#set(Object)}.<br><br>
116: * The default setting is <b>false</b>.<br><br>
117: * In client-server environment this setting should be used on both
118: * client and server. <br><br>
119: * @param flag whether updates are to be cascaded to member objects.
120: * @see ObjectField#cascadeOnUpdate
121: * @see com.db4o.ObjectContainer#set
122: * @see com.db4o.ext.ObjectCallbacks Using callbacks
123: */
124: public void cascadeOnUpdate(boolean flag);
125:
126: /**
127: * registers an attribute provider for special query behavior.
128: * <br><br>The query processor will compare the object returned by the
129: * attribute provider instead of the actual object, both for the constraint
130: * and the candidate persistent object.<br><br>
131: * In client-server environment this setting should be used on both
132: * client and server. <br><br>
133: * @param attributeProvider the attribute provider to be used
134: */
135: public void compare(ObjectAttribute attributeProvider);
136:
137: /**
138: * Must be called before databases are created or opened
139: * so that db4o will control versions and generate UUIDs
140: * for objects of this class, which is required for using replication.
141: *
142: * @param setting
143: */
144: public void enableReplication(boolean setting);
145:
146: /**
147: * generate UUIDs for stored objects of this class.
148: * This setting should be used before the database is first created.<br><br>
149: * @param setting
150: */
151: public void generateUUIDs(boolean setting);
152:
153: /**
154: * generate version numbers for stored objects of this class.
155: * This setting should be used before the database is first created.<br><br>
156: * @param setting
157: */
158: public void generateVersionNumbers(boolean setting);
159:
160: /**
161: * turns the class index on or off.
162: * <br><br>db4o maintains an index for each class to be able to
163: * deliver all instances of a class in a query. If the class
164: * index is never needed, it can be turned off with this method
165: * to improve the performance to create and delete objects of
166: * a class.
167: * <br><br>Common cases where a class index is not needed:<br>
168: * - The application always works with subclasses or superclasses.<br>
169: * - There are convenient field indexes that will always find instances
170: * of a class.<br>
171: * - The application always works with IDs.<br><br>
172: * In client-server environment this setting should be used on both
173: * client and server. <br><br>
174: */
175: public void indexed(boolean flag);
176:
177: /**
178: * sets the maximum activation depth to the desired value.
179: * <br><br>A class specific setting overrides the
180: * {@link Configuration#activationDepth(int) global setting}
181: * <br><br>
182: * In client-server environment this setting should be used on both
183: * client and server. <br><br>
184: * @param depth the desired maximum activation depth
185: * @see Configuration#activationDepth Why activation?
186: * @see ObjectClass#cascadeOnActivate
187: */
188: public void maximumActivationDepth(int depth);
189:
190: /**
191: * sets the minimum activation depth to the desired value.
192: * <br><br>A class specific setting overrides the
193: * {@link Configuration#activationDepth(int) global setting}
194: * <br><br>
195: * In client-server environment this setting should be used on both
196: * client and server. <br><br>
197: * @param depth the desired minimum activation depth
198: * @see Configuration#activationDepth Why activation?
199: * @see ObjectClass#cascadeOnActivate
200: */
201: public void minimumActivationDepth(int depth);
202:
203: /**
204: * gets the configured minimum activation depth.
205: * In client-server environment this setting should be used on both
206: * client and server. <br><br>
207: * @return the configured minimum activation depth.
208: */
209: public int minimumActivationDepth();
210:
211: /**
212: * returns an {@link ObjectField ObjectField} object
213: * to configure the specified field.
214: * <br><br>
215: * @param fieldName the fieldname of the field to be configured.<br><br>
216: * @return an instance of an {@link ObjectField ObjectField}
217: * object for configuration.
218: */
219: public ObjectField objectField(String fieldName);
220:
221: /**
222: * turns on storing static field values for this class.
223: * <br><br>By default, static field values of classes are not stored
224: * to the database file. By turning the setting on for a specific class
225: * with this switch, all <b>non-simple-typed</b> static field values of this
226: * class are stored the first time an object of the class is stored, and
227: * restored, every time a database file is opened afterwards, <b>after
228: * class meta information is loaded for this class</b> (which can happen
229: * by querying for a class or by loading an instance of a class).<br><br>
230: * To update a static field value, once it is stored, you have to the following
231: * in this order:<br>
232: * (1) open the database file you are working agains<br>
233: * (2) make sure the class metadata is loaded<br>
234: * <code>objectContainer.query().constrain(Foo.class); // Java</code><br>
235: * <code>objectContainer.Query().Constrain(typeof(Foo)); // C#</code><br>
236: * (3) change the static member<br>
237: * (4) store the static member explicitely<br>
238: * <code>objectContainer.set(Foo.staticMember); // C#</code>
239: * <br><br>The setting will be ignored for simple types.
240: * <br><br>Use this setting for constant static object members.
241: * <br><br>This option will slow down the process of opening database
242: * files and the stored objects will occupy space in the database file.
243: * <br><br>In client-server environment this setting should be used on both
244: * client and server. <br><br>
245: */
246: public void persistStaticFieldValues();
247:
248: /**
249: * creates a temporary mapping of a persistent class to a different class.
250: * <br><br>If meta information for this ObjectClass has been stored to
251: * the database file, it will be read from the database file as if it
252: * was representing the class specified by the clazz parameter passed to
253: * this method.
254: * The clazz parameter can be any of the following:<br>
255: * - a fully qualified classname as a String.<br>
256: * - a Class object.<br>
257: * - any other object to be used as a template.<br><br>
258: * This method will be ignored if the database file already contains meta
259: * information for clazz.
260: * @param clazz class name, Class object, or example object.<br><br>
261: */
262: public void readAs(Object clazz);
263:
264: /**
265: * renames a stored class.
266: * <br><br>Use this method to refactor classes.
267: * <br><br>In client-server environment this setting should be used on both
268: * client and server. <br><br>
269: * @param newName the new fully qualified classname.
270: */
271: public void rename(String newName);
272:
273: /**
274: * allows to specify if transient fields are to be stored.
275: * <br>The default for every class is <code>false</code>.<br><br>
276: * In client-server environment this setting should be used on both
277: * client and server. <br><br>
278: * @param flag whether or not transient fields are to be stored.
279: */
280: public void storeTransientFields(boolean flag);
281:
282: /**
283: * registers a translator for this class.
284: * <br><br>
285: * <br><br>The use of an {@link ObjectTranslator ObjectTranslator} is not
286: * compatible with the use of an
287: * internal class ObjectMarshaller.<br><br>
288: * In client-server environment this setting should be used on both
289: * client and server. <br><br>
290: * @param translator this may be an {@link ObjectTranslator ObjectTranslator}
291: * or an {@link ObjectConstructor ObjectConstructor}
292: * @see ObjectTranslator
293: * @see ObjectConstructor
294: */
295: public void translate(ObjectTranslator translator);
296:
297: /**
298: * specifies the updateDepth for this class.
299: * <br><br>see the documentation of
300: * {@link com.db4o.ObjectContainer#set(Object)}
301: * for further details.<br><br>
302: * The default setting is 0: Only the object passed to
303: * {@link com.db4o.ObjectContainer#set(Object)} will be updated.<br><br>
304: * In client-server environment this setting should be used on both
305: * client and server. <br><br>
306: * @param depth the depth of the desired update for this class.
307: * @see Configuration#updateDepth
308: * @see ObjectClass#cascadeOnUpdate
309: * @see ObjectField#cascadeOnUpdate
310: * @see com.db4o.ext.ObjectCallbacks Using callbacks
311: */
312: public void updateDepth(int depth);
313:
314: }
|