db4o 6.1

com.db4o.config
Interface ObjectClass


public interface ObjectClass

configuration interface for classes.

Examples: ../com/db4o/samples/translators/Default.java.

Use the global Configuration object to configure db4o before opening an ObjectContainer.

Example:
Configuration config = Db4o.configure();
ObjectClass oc = config.objectClass("package.className");
oc.updateDepth(3);
oc.minimumActivationDepth(3);


Method Summary
 void callConstructor(boolean flag)
          advises db4o to try instantiating objects of this class with/without calling constructors.
 void cascadeOnActivate(boolean flag)
          sets cascaded activation behaviour.
 void cascadeOnDelete(boolean flag)
          sets cascaded delete behaviour.
 void cascadeOnUpdate(boolean flag)
          sets cascaded update behaviour.
 void compare(ObjectAttribute attributeProvider)
          registers an attribute provider for special query behavior.
 void enableReplication(boolean setting)
          Must be called before databases are created or opened so that db4o will control versions and generate UUIDs for objects of this class, which is required for using replication.
 void generateUUIDs(boolean setting)
          generate UUIDs for stored objects of this class.
 void generateVersionNumbers(boolean setting)
          generate version numbers for stored objects of this class.
 void indexed(boolean flag)
          turns the class index on or off.
 void marshallWith(ObjectMarshaller marshaller)
          registers a custom marshaller for this class.
 void maximumActivationDepth(int depth)
          sets the maximum activation depth to the desired value.
 void minimumActivationDepth(int depth)
          sets the minimum activation depth to the desired value.
 ObjectField objectField(java.lang.String fieldName)
          returns an ObjectField object to configure the specified field.
 void persistStaticFieldValues()
          turns on storing static field values for this class.
 void readAs(java.lang.Object clazz)
          creates a temporary mapping of a persistent class to a different class.
 void rename(java.lang.String newName)
          renames a stored class.
 void storeTransientFields(boolean flag)
          allows to specify if transient fields are to be stored.
 void translate(ObjectTranslator translator)
          registers a translator for this class.
 void updateDepth(int depth)
          specifies the updateDepth for this class.
 

Method Detail

callConstructor

void callConstructor(boolean flag)
advises db4o to try instantiating objects of this class with/without calling constructors.

Not all JDKs / .NET-environments support this feature. db4o will attempt, to follow the setting as good as the enviroment supports. In doing so, it may call implementation-specific features like sun.reflect.ReflectionFactory#newConstructorForSerialization on the Sun Java 1.4.x/5 VM (not available on other VMs) and FormatterServices.GetUninitializedObject() on the .NET framework (not available on CompactFramework).

This setting may also be set globally for all classes in Configuration.callConstructors(boolean).

Parameters:
flag - - specify true, to request calling constructors, specify false to request not calling constructors.
See Also:
Configuration.callConstructors(boolean)

cascadeOnActivate

void cascadeOnActivate(boolean flag)
sets cascaded activation behaviour.

Setting cascadeOnActivate to true will result in the activation of all member objects if an instance of this class is activated.

The default setting is false.

Parameters:
flag - whether activation is to be cascaded to member objects.
See Also:
ObjectField.cascadeOnActivate(boolean), ObjectContainer.activate(java.lang.Object, int), Using callbacks, Why activation?

cascadeOnDelete

void cascadeOnDelete(boolean flag)
sets cascaded delete behaviour.

Setting cascadeOnDelete to true will result in the deletion of all member objects of instances of this class, if they are passed to ObjectContainer.delete(Object).

Caution !
This setting will also trigger deletion of old member objects, on calls to ObjectContainer.set(Object).

An example of the behaviour:
ObjectContainer con;
Bar bar1 = new Bar();
Bar bar2 = new Bar();
foo.bar = bar1;
con.set(foo); // bar1 is stored as a member of foo
foo.bar = bar2;
con.set(foo); // bar2 is stored as a member of foo

The last statement will also delete bar1 from the ObjectContainer, no matter how many other stored objects hold references to bar1.

The default setting is false.

Parameters:
flag - whether deletes are to be cascaded to member objects.
See Also:
ObjectField.cascadeOnDelete(boolean), ObjectContainer.delete(java.lang.Object), Using callbacks

cascadeOnUpdate

void cascadeOnUpdate(boolean flag)
sets cascaded update behaviour.

Setting cascadeOnUpdate to true will result in the update of all member objects if a stored instance of this class is passed to ObjectContainer.set(Object).

The default setting is false.

Parameters:
flag - whether updates are to be cascaded to member objects.
See Also:
ObjectField.cascadeOnUpdate(boolean), ObjectContainer.set(java.lang.Object), Using callbacks

compare

void compare(ObjectAttribute attributeProvider)
registers an attribute provider for special query behavior.

The query processor will compare the object returned by the attribute provider instead of the actual object, both for the constraint and the candidate persistent object.

Preinstalled attribute providers are documented in the sourcecode of com.db4o.samples.translators.Default.java#defaultConfiguration().

Parameters:
attributeProvider - the attribute provider to be used

enableReplication

void enableReplication(boolean setting)
Must be called before databases are created or opened so that db4o will control versions and generate UUIDs for objects of this class, which is required for using replication.

Parameters:
setting -

generateUUIDs

void generateUUIDs(boolean setting)
generate UUIDs for stored objects of this class.

Parameters:
setting -

generateVersionNumbers

void generateVersionNumbers(boolean setting)
generate version numbers for stored objects of this class.

Parameters:
setting -

indexed

void indexed(boolean flag)
turns the class index on or off.

db4o maintains an index for each class to be able to deliver all instances of a class in a query. If the class index is never needed, it can be turned off with this method to improve the performance to create and delete objects of a class.

Common cases where a class index is not needed:
- The application always works with subclasses or superclasses.
- There are convenient field indexes that will always find instances of a class.
- The application always works with IDs.


marshallWith

void marshallWith(ObjectMarshaller marshaller)
registers a custom marshaller for this class.

Custom marshallers can be used for tuning the performance to store and read objects. Instead of letting db4o do all the marshalling by detecting the fields on a class and by using reflection, a custom ObjectMarshaller allows the application developer to write the logic how the fields of an object are converted to a byte[] and back.

Downside:
- Indexes and querying can not be used.

Upsides:
- Not all fields need to be stored.
- Reflection does not need to be called.


As an alternative to using a custom marshallers you may want to consider writing an ObjectTranslator or your own Reflector.

The use of an ObjectMarshaller is not compatible with the use of an ObjectTranslator.

Parameters:
marshaller - to be used for this class
See Also:
ObjectMarshaller

maximumActivationDepth

void maximumActivationDepth(int depth)
sets the maximum activation depth to the desired value.

A class specific setting overrides the global setting

Parameters:
depth - the desired maximum activation depth
See Also:
Why activation?, cascadeOnActivate(boolean)

minimumActivationDepth

void minimumActivationDepth(int depth)
sets the minimum activation depth to the desired value.

A class specific setting overrides the global setting

Parameters:
depth - the desired minimum activation depth
See Also:
Why activation?, cascadeOnActivate(boolean)

objectField

ObjectField objectField(java.lang.String fieldName)
returns an ObjectField object to configure the specified field.

Parameters:
fieldName - the fieldname of the field to be configured.

Returns:
an instance of an ObjectField object for configuration.

persistStaticFieldValues

void persistStaticFieldValues()
turns on storing static field values for this class.

By default, static field values of classes are not stored to the database file. By turning the setting on for a specific class with this switch, all non-simple-typed static field values of this class are stored the first time an object of the class is stored, and restored, every time a database file is opened afterwards, after class meta information is loaded for this class (which can happen by querying for a class or by loading an instance of a class).

To update a static field value, once it is stored, you have to the following in this order:
(1) open the database file you are working agains
(2) make sure the class metadata is loaded
objectContainer.query().constrain(Foo.class); // Java
objectContainer.Query().Constrain(typeof(Foo)); // C#
(3) change the static member
(4) store the static member explicitely
objectContainer.set(Foo.staticMember); // C#

The setting will be ignored for simple types.

Use this setting for constant static object members.

This option will slow down the process of opening database files and the stored objects will occupy space in the database file.


readAs

void readAs(java.lang.Object clazz)
creates a temporary mapping of a persistent class to a different class.

If meta information for this ObjectClass has been stored to the database file, it will be read from the database file as if it was representing the class specified by the clazz parameter passed to this method. The clazz parameter can be any of the following:
- a fully qualified classname as a String.
- a Class object.
- any other object to be used as a template.

This method will be ignored if the database file already contains meta information for clazz.

Parameters:
clazz - class name, Class object, or example object.


rename

void rename(java.lang.String newName)
renames a stored class.

Use this method to refactor classes.

Examples: ../com/db4o/samples/rename.

Parameters:
newName - the new fully qualified classname.

storeTransientFields

void storeTransientFields(boolean flag)
allows to specify if transient fields are to be stored.
The default for every class is false.

Parameters:
flag - whether or not transient fields are to be stored.

translate

void translate(ObjectTranslator translator)
registers a translator for this class.

Preinstalled translators are documented in the sourcecode of com.db4o.samples.translators.Default.java#defaultConfiguration().

Example translators can also be found in this folder.



The use of an ObjectTranslator is not compatible with the use of an ObjectMarshaller.

Parameters:
translator - this may be an ObjectTranslator or an ObjectConstructor
See Also:
ObjectTranslator, ObjectConstructor

updateDepth

void updateDepth(int depth)
specifies the updateDepth for this class.

see the documentation of ObjectContainer.set(Object) for further details.

The default setting is 0: Only the object passed to ObjectContainer.set(Object) will be updated.

Parameters:
depth - the depth of the desired update for this class.
See Also:
Configuration.updateDepth(int), cascadeOnUpdate(boolean), ObjectField.cascadeOnUpdate(boolean), Using callbacks

db4o 6.1