Schema Update

The <schema> configuration element supports renaming packages, classes, and fields in ObjectDB databases. This is a complementary operation to renaming or moving these elements in your IDE during source code refactoring. You specify only these schema changes in the configuration file. As explained in Chapter 2, ObjectDB handles other schema changes automatically.

Note: Use extreme caution when you rename or move persistable classes to another package. If you run the application with persistable classes that have been renamed or moved in the IDE without a matching schema configuration, ObjectDB creates new, separate persistable classes with no instances. Therefore, you should back up your database files before renaming or moving persistable classes. You must also verify that after making these changes, the application runs only with a configuration that matches them exactly.

The default configuration file contains an empty <schema> element. If this element is not empty, ObjectDB tries to apply the specified schema updates every time a database is opened. When you use client-server mode, the <schema> instructions should usually be on the client side, where the up-to-date classes are located.

The following <schema> element demonstrates the supported schema update capabilities:

<schema>
  <package name="com.example.old1" new-name="com.example.new1" />
  <package name="com.example.old2" new-name="com.example.new2">
    <class name="A" new-name="NewA" />
    <class name="B">
      <field name="f1" new-name="newF1" />
      <field name="f2" new-name="newF2" />
    </class>
  </package>
  <package name="com.example.old3">
    <class name="C" new-name="NewC" >
      <field name="f3" new-name="newF3" />
    </class>
    <class name="C$E" new-name="NewC$E" />
  </package>
</schema>

The hierarchy, as demonstrated in the preceding example, is strict:

• A <package> element must be a direct child of the <schema> element.
• A <class> element must be a direct child of a <package> element.
• A <field> element must be a direct child of a <class> element.

The <package> elements

  <package name="com.example.old1" new-name="com.example.new1" />
  <package name="com.example.old2" new-name="com.example.new2">
     ...
  </package>
  <package name="com.example.old3">
    ...
  </package>

A <package> element has two roles:

• If you specify the optional new-name attribute, the package name changes from the original name (specified by the required name attribute) to the new name. All classes in that package are moved to the new package.
• Additionally, regardless of whether a new-name attribute is specified, a <package> element serves as a container for <class> child elements to rename classes and fields within that package.

The <package> elements in the example rename the com.example.old1 and com.example.old2 packages. The com.example.old3 package is not renamed, but rename operations are specified for some of its classes.

The <class> elements

    <class name="A" new-name="NewA" />
    <class name="B">
      ...
    </class>
    <class name="C" new-name="NewC" >
      ...
    </class>
    <class name="C$E" new-name="NewC$E" />

A <class> element has two roles:

• If you specify the optional new-name attribute, the class name changes from the original name (specified by the required name attribute) to the new name.
  • The value of the name attribute must be unqualified (without a package name) because the package is already specified in the parent <package> element.
  • The value of the new-name attribute can be either qualified or unqualified. If it is unqualified, ObjectDB uses the new-name value from the parent <package> element as the package name. If the parent <package> element has no new-name attribute, ObjectDB uses its name value instead.
• Additionally, regardless of whether a new-name attribute is specified, a <class> element serves as a container for <field> child elements to rename fields in that class.

The <class> elements in the example rename the A, C, and C.E (written as C$E) classes. Class B is not renamed but rename operations are specified for some of its fields.

The <field> elements

      <field name="f1" new-name="newF1" />
      <field name="f2" new-name="newF2" />
      <field name="f3" new-name="newF3" />

The <field> element renames a persistent field or property. Both the name (old name) and new-name (new name) attributes are required.