Schema Update

The <schema> configuration element supports renaming packages, classes and fields in ObjectDB databases as a complementary operation to renaming or moving these elements in the IDE during source code refactoring. Only these schema changes are specified in the configuration file. As explained in chapter 2, other schema changes are handled by ObjectDB automatically.

Note: Extreme caution is required when persistable classes are renamed or moved to another package. Running the application with persistable classes that have been renamed or moved in the IDE, with no matching schema configuration - will create new, separate persistable classes with no instances. Therefore, you should backup your database files before renaming or moving persistable classes and you must verify that after such changes the application is run only with the configuration that matches these changes exactly.

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

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

<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 above, is strict:

• <package> elements are always direct child elements of the <schema> element.
• <class> elements are always direct child elements of <package> elements.
• <field> elements are always direct child elements of <class> elements.

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 the optional new-name attribute is specified, the package name is changed from the original name, which is specified by the required name attribute, to the new name. All the classes in that package are moved to the new package name.

• In addition, whether or not a new-name attribute is specified, a <package> element serves as a container of <class> subelements for renaming classes and fields in that package.

The <package> elements above specify renaming of 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 the optional new-name attribute is specified the class name is changed from the original name, which is specified by the required name attribute, to the new name. The value of the name attribute must be unqualified (with no package name) because the package name is already specified in the containing <package> element. The value of the new-name attribute can be either qualified or unqualified. If it is unqualified (no package name) the new-name value of the containing <package> element is used, if it exists, or if no new-name is specified in the <package> element the name value of the <package> element is used.

• In addition, whether or not a new-name attribute is specified a <class> element serves as a container of <field> subelements for renaming fields in that class.

The <class> elements above specify renaming of the A, C and C.E (which has to be 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 specifies renaming a persistent field (or a property). Both attributes, name (the old name), and new-name (the new name), are required.