ObjectClass


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  /**
24   * configuration interface for classes.
25   * <br><br><b>Examples: ../com/db4o/samples/translators/Default.java.</b><br><br>
26   * Use the global Configuration object to configure db4o before opening an
27   * {@link com.db4o.ObjectContainer ObjectContainer}.<br><br>
28   * <b>Example:</b><br>
29   * <code>
30   * Configuration config = Db4o.configure();<br>
31   * ObjectClass oc = config.objectClass("package.className");<br>
32   * oc.updateDepth(3);<br>
33   * oc.minimumActivationDepth(3);<br>
34   * </code>
35   */
36  public interface ObjectClass {
37      
38      
39      /**
40       * advises db4o to try instantiating objects of this class with/without
41       * calling constructors.
42       * <br><br>
43       * Not all JDKs / .NET-environments support this feature. db4o will
44       * attempt, to follow the setting as good as the enviroment supports.
45       * In doing so, it may call implementation-specific features like
46       * sun.reflect.ReflectionFactory#newConstructorForSerialization on the
47       * Sun Java 1.4.x/5 VM (not available on other VMs) and 
48       * FormatterServices.GetUninitializedObject() on
49       * the .NET framework (not available on CompactFramework).<br><br>
50       * This setting may also be set globally for all classes in
51       * {@link Configuration#callConstructors(boolean)}.<br><br>
52       * @param flag - specify true, to request calling constructors, specify
53       * false to request <b>not</b> calling constructors.
54       * @see Configuration#callConstructors
55       */
56      public void callConstructor(boolean flag);
57      
58      
59      /**
60       * sets cascaded activation behaviour.
61       * <br><br>
62       * Setting cascadeOnActivate to true will result in the activation
63       * of all member objects if an instance of this class is activated.
64       * <br><br>
65       * The default setting is <b>false</b>.<br><br>
66       * @param flag whether activation is to be cascaded to member objects.
67       * @see ObjectField#cascadeOnActivate
68       * @see com.db4o.ObjectContainer#activate
69       * @see com.db4o.ext.ObjectCallbacks Using callbacks
70       * @see Configuration#activationDepth Why activation?
71       */
72      public void cascadeOnActivate(boolean flag);
73  
74  
75      /**
76       * sets cascaded delete behaviour.
77       * <br><br>
78       * Setting cascadeOnDelete to true will result in the deletion of
79       * all member objects of instances of this class, if they are 
80       * passed to
81       * {@link com.db4o.ObjectContainer#delete(Object)}. 
82       * <br><br>
83       * <b>Caution !</b><br>
84       * This setting will also trigger deletion of old member objects, on
85       * calls to {@link com.db4o.ObjectContainer#set(Object)}.<br><br>
86       * An example of the behaviour:<br>
87       * <code>
88       * ObjectContainer con;<br>
89       * Bar bar1 = new Bar();<br>
90       * Bar bar2 = new Bar();<br>
91       * foo.bar = bar1;<br>
92       * con.set(foo);  // bar1 is stored as a member of foo<br>
93       * foo.bar = bar2;<br>
94       * con.set(foo);  // bar2 is stored as a member of foo
95       * </code><br>The last statement will <b>also</b> delete bar1 from the
96       * ObjectContainer, no matter how many other stored objects hold references
97       * to bar1.
98       * <br><br>
99       * The default setting is <b>false</b>.<br><br>
100      * @param flag whether deletes are to be cascaded to member objects.
101      * @see ObjectField#cascadeOnDelete
102      * @see com.db4o.ObjectContainer#delete
103      * @see com.db4o.ext.ObjectCallbacks Using callbacks
104      */
105     public void cascadeOnDelete(boolean flag);
106     
107     
108     /**
109      * sets cascaded update behaviour.
110      * <br><br>
111      * Setting cascadeOnUpdate to true will result in the update
112      * of all member objects if a stored instance of this class is passed
113      * to {@link com.db4o.ObjectContainer#set(Object)}.<br><br>
114      * The default setting is <b>false</b>.<br><br>
115      * @param flag whether updates are to be cascaded to member objects.
116      * @see ObjectField#cascadeOnUpdate
117      * @see com.db4o.ObjectContainer#set
118      * @see com.db4o.ext.ObjectCallbacks Using callbacks
119      */
120     public void cascadeOnUpdate(boolean flag);
121     
122     
123     /**
124      * registers an attribute provider for special query behavior.
125      * <br><br>The query processor will compare the object returned by the
126      * attribute provider instead of the actual object, both for the constraint
127      * and the candidate persistent object.<br><br> Preinstalled attribute
128      * providers are documented
129      * in the sourcecode of 
130      * com.db4o.samples.translators.Default.java#defaultConfiguration().<br><br>
131      * @param attributeProvider the attribute provider to be used
132      */
133     public void compare(ObjectAttribute attributeProvider);
134     
135     
136     /**
137      * Must be called before databases are created or opened
138      * so that db4o will control versions and generate UUIDs
139      * for objects of this class, which is required for using replication.
140      * 
141      * @param setting 
142      */
143     public void enableReplication(boolean setting);
144 
145     
146     /**
147      * generate UUIDs for stored objects of this class.
148      * 
149      * @param setting 
150      */
151     public void generateUUIDs(boolean setting);
152 
153     
154     /**
155      * generate version numbers for stored objects of this class.
156      * 
157      * @param setting
158      */
159     public void generateVersionNumbers(boolean setting);
160     
161 
162     /**
163      * sets the maximum activation depth to the desired value.
164      * <br><br>A class specific setting overrides the
165      * {@link Configuration#activationDepth(int) global setting}
166      * <br><br>
167      * @param depth the desired maximum activation depth
168      * @see Configuration#activationDepth Why activation?
169      * @see ObjectClass#cascadeOnActivate
170      */
171     public void maximumActivationDepth (int depth);
172 
173 
174 
175     /**
176      * sets the minimum activation depth to the desired value.
177      * <br><br>A class specific setting overrides the
178      * {@link Configuration#activationDepth(int) global setting}
179      * <br><br>
180      * @param depth the desired minimum activation depth
181      * @see Configuration#activationDepth Why activation?
182      * @see ObjectClass#cascadeOnActivate
183      */
184     public void minimumActivationDepth (int depth);
185 
186 
187     /**
188      * returns an {@link ObjectField ObjectField} object
189      * to configure the specified field.
190      * <br><br>
191      * @param fieldName the fieldname of the field to be configured.<br><br>
192      * @return an instance of an {@link ObjectField ObjectField}
193      *  object for configuration.
194      */
195     public ObjectField objectField (String   fieldName);
196     
197     
198     /**
199      * turns on storing static field values for this class.
200      * <br><br>By default, static field values of classes are not stored
201      * to the database file. By turning the setting on for a specific class
202      * with this switch, all <b>non-simple-typed</b> static field values of this
203      * class are stored the first time an object of the class is stored, and
204      * restored, every time a database file is opened afterwards, <b>after 
205      * class meta information is loaded for this class</b> (which can happen
206      * by querying for a class or by loading an instance of a class).<br><br>
207      * To update a static field value, once it is stored, you have to the following
208      * in this order:<br>
209      * (1) open the database file you are working agains<br>
210      * (2) make sure the class metadata is loaded<br>
211      * <code>objectContainer.query().constrain(Foo.class); // Java</code><br>
212      * <code>objectContainer.Query().Constrain(typeof(Foo)); // C#</code><br>
213      * (3) change the static member<br>
214      * (4) store the static member explicitely<br>
215      * <code>objectContainer.set(Foo.staticMember); // C#</code>
216      * <br><br>The setting will be ignored for simple types.
217      * <br><br>Use this setting for constant static object members.
218      * <br><br>This option will slow down the process of opening database
219      * files and the stored objects will occupy space in the database file.
220      */
221     public void persistStaticFieldValues();
222     
223     
224     /**
225      * creates a temporary mapping of a persistent class to a different class.
226      * <br><br>If meta information for this ObjectClass has been stored to
227      * the database file, it will be read from the database file as if it
228      * was representing the class specified by the clazz parameter passed to
229      * this method. 
230      * The clazz parameter can be any of the following:<br>
231      * - a fully qualified classname as a String.<br>
232      * - a Class object.<br>
233      * - any other object to be used as a template.<br><br>
234      * This method will be ignored if the database file already contains meta
235      * information for clazz.
236      * @param clazz class name, Class object, or example object.<br><br>
237      */
238     public void readAs(Object   clazz);
239 
240 
241     /**
242      * renames a stored class.
243      * <br><br>Use this method to refactor classes.
244      * <br><br><b>Examples: ../com/db4o/samples/rename.</b><br><br>
245      * @param newName the new fully qualified classname.
246      */
247     public void rename (String   newName);
248 
249 
250 
251     /**
252      * allows to specify if transient fields are to be stored.
253      * <br>The default for every class is <code>false</code>.<br><br>
254      * @param flag whether or not transient fields are to be stored.
255      */
256     public void storeTransientFields (boolean flag);
257 
258 
259 
260     /**
261      * registers a translator for this class.
262      * <br><br>
263      * Preinstalled translators are documented in the sourcecode of
264      * com.db4o.samples.translators.Default.java#defaultConfiguration().
265      * <br><br>Example translators can also be found in this folder.<br><br>
266      * @param translator this may be an {@link ObjectTranslator ObjectTranslator}
267      *  or an {@link ObjectConstructor ObjectConstructor}
268      * @see ObjectTranslator
269      * @see ObjectConstructor
270      */
271     public void translate (ObjectTranslator translator);
272 
273 
274 
275     /**
276      * specifies the updateDepth for this class.
277      * <br><br>see the documentation of
278      * {@link com.db4o.ObjectContainer#set(Object)}
279      * for further details.<br><br>
280      * The default setting is 0: Only the object passed to
281      * {@link com.db4o.ObjectContainer#set(Object)} will be updated.<br><br>
282      * @param depth the depth of the desired update for this class.
283      * @see Configuration#updateDepth
284      * @see ObjectClass#cascadeOnUpdate
285      * @see ObjectField#cascadeOnUpdate
286      * @see com.db4o.ext.ObjectCallbacks Using callbacks
287      */
288     public void updateDepth (int depth);
289 }
290 
291 
292 
293
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags