524 lines
30 KiB
HTML
524 lines
30 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<!--NewPage-->
|
|
<HTML>
|
|
<HEAD>
|
|
<!-- Generated by javadoc (build 1.5.0) on Thu May 15 17:17:33 EDT 2008 -->
|
|
<TITLE>
|
|
com.sleepycat.persist.evolve (Oracle - Berkeley DB Java API)
|
|
</TITLE>
|
|
|
|
<META NAME="keywords" CONTENT="com.sleepycat.persist.evolve package">
|
|
|
|
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../style.css" TITLE="Style">
|
|
|
|
<SCRIPT type="text/javascript">
|
|
function windowTitle()
|
|
{
|
|
parent.document.title="com.sleepycat.persist.evolve (Oracle - Berkeley DB Java API)";
|
|
}
|
|
</SCRIPT>
|
|
<NOSCRIPT>
|
|
</NOSCRIPT>
|
|
|
|
</HEAD>
|
|
|
|
<BODY BGCOLOR="white" onload="windowTitle();">
|
|
|
|
|
|
<!-- ========= START OF TOP NAVBAR ======= -->
|
|
<A NAME="navbar_top"><!-- --></A>
|
|
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
|
|
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
|
|
<TR>
|
|
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
|
|
<A NAME="navbar_top_firstrow"><!-- --></A>
|
|
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
|
|
<TR ALIGN="center" VALIGN="top">
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
|
|
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
|
|
</TR>
|
|
</TABLE>
|
|
</TD>
|
|
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
|
|
<b>Berkeley DB</b><br><font size="-1"> version 4.7.25</font></EM>
|
|
</TD>
|
|
</TR>
|
|
|
|
<TR>
|
|
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
|
<A HREF="../../../../com/sleepycat/persist/package-summary.html"><B>PREV PACKAGE</B></A>
|
|
<A HREF="../../../../com/sleepycat/persist/model/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
|
|
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
|
<A HREF="../../../../index.html?com/sleepycat/persist/evolve/package-summary.html" target="_top"><B>FRAMES</B></A>
|
|
<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>
|
|
<SCRIPT type="text/javascript">
|
|
<!--
|
|
if(window==top) {
|
|
document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>');
|
|
}
|
|
//-->
|
|
</SCRIPT>
|
|
<NOSCRIPT>
|
|
<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>
|
|
</NOSCRIPT>
|
|
|
|
|
|
</FONT></TD>
|
|
</TR>
|
|
</TABLE>
|
|
<A NAME="skip-navbar_top"></A>
|
|
<!-- ========= END OF TOP NAVBAR ========= -->
|
|
|
|
<HR>
|
|
<H2>
|
|
Package com.sleepycat.persist.evolve
|
|
</H2>
|
|
Utilities for managing class evolution of persistent objects.
|
|
<P>
|
|
<B>See:</B>
|
|
<BR>
|
|
<A HREF="#package_description"><B>Description</B></A>
|
|
<P>
|
|
|
|
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
|
|
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
|
|
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
|
|
<B>Interface Summary</B></FONT></TH>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Conversion.html" title="interface in com.sleepycat.persist.evolve">Conversion</A></B></TD>
|
|
<TD>Converts an old version of an object value to conform to the current class
|
|
or field definition.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EvolveListener.html" title="interface in com.sleepycat.persist.evolve">EvolveListener</A></B></TD>
|
|
<TD>The listener interface called during eager entity evolution.</TD>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
|
|
<P>
|
|
|
|
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
|
|
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
|
|
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
|
|
<B>Class Summary</B></FONT></TH>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Converter.html" title="class in com.sleepycat.persist.evolve">Converter</A></B></TD>
|
|
<TD>A mutation for converting an old version of an object value to conform to
|
|
the current class or field definition.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Deleter.html" title="class in com.sleepycat.persist.evolve">Deleter</A></B></TD>
|
|
<TD>A mutation for deleting an entity class or field.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EntityConverter.html" title="class in com.sleepycat.persist.evolve">EntityConverter</A></B></TD>
|
|
<TD>A subclass of Converter that allows specifying keys to be deleted.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EvolveConfig.html" title="class in com.sleepycat.persist.evolve">EvolveConfig</A></B></TD>
|
|
<TD>Configuration properties for eager conversion of unevolved objects.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EvolveEvent.html" title="class in com.sleepycat.persist.evolve">EvolveEvent</A></B></TD>
|
|
<TD>The event passed to the EvolveListener interface during eager entity
|
|
evolution.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EvolveInternal.html" title="class in com.sleepycat.persist.evolve">EvolveInternal</A></B></TD>
|
|
<TD>Internal access class that should not be used by applications.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EvolveStats.html" title="class in com.sleepycat.persist.evolve">EvolveStats</A></B></TD>
|
|
<TD>Statistics accumulated during eager entity evolution.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Mutation.html" title="class in com.sleepycat.persist.evolve">Mutation</A></B></TD>
|
|
<TD>The base class for all mutations.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Mutations.html" title="class in com.sleepycat.persist.evolve">Mutations</A></B></TD>
|
|
<TD>A collection of mutations for configuring class evolution.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Renamer.html" title="class in com.sleepycat.persist.evolve">Renamer</A></B></TD>
|
|
<TD>A mutation for renaming a class or field without changing the instance or
|
|
field value.</TD>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
|
|
<P>
|
|
|
|
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
|
|
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
|
|
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
|
|
<B>Exception Summary</B></FONT></TH>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/DeletedClassException.html" title="class in com.sleepycat.persist.evolve">DeletedClassException</A></B></TD>
|
|
<TD>While reading from an index, an instance of a deleted class version was
|
|
encountered.</TD>
|
|
</TR>
|
|
<TR BGCOLOR="white" CLASS="TableRowColor">
|
|
<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/IncompatibleClassException.html" title="class in com.sleepycat.persist.evolve">IncompatibleClassException</A></B></TD>
|
|
<TD>A class has been changed incompatibly and no mutation has been configured to
|
|
handle the change or a new class version number has not been assigned.</TD>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
|
|
<P>
|
|
<A NAME="package_description"><!-- --></A><H2>
|
|
Package com.sleepycat.persist.evolve Description
|
|
</H2>
|
|
|
|
<P>
|
|
Utilities for managing class evolution of persistent objects.
|
|
|
|
<h1>Class Evolution</h1>
|
|
|
|
<p>For persistent data that is not short lived, changes to persistent classes
|
|
are almost inevitable. Some changes are compatible with existing types, and
|
|
data conversion for these changes is performed automatically and transparently.
|
|
Other changes are not compatible with existing types. Mutations can be used to
|
|
explicitly manage many types of incompatible changes.</p>
|
|
|
|
<p>Not all incompatible class changes can be handled via mutations. For
|
|
example, complex refactoring may require a transformation that manipulates
|
|
multiple entity instances at once. Such changes are not possible with
|
|
mutations but can be made by performing a <a href="#storeConversion">store
|
|
conversion</a>.</p>
|
|
|
|
<p>The different categories of type changes are described below.</p>
|
|
|
|
<h2>Key Field Changes</h2>
|
|
|
|
<p>Unlike entity data, key data is not versioned. Therefore, the physical key
|
|
format for an index is fixed once the index has been opened, and the changes
|
|
allowed for key fields are very limited. The only changes allowed for key
|
|
fields are:</p>
|
|
<ul>
|
|
<li>The name of a key field may be changed, as long as this change is
|
|
accompanied by a <A HREF="../../../../com/sleepycat/persist/evolve/Renamer.html" title="class in com.sleepycat.persist.evolve"><CODE>Renamer</CODE></A> mutation.</li>
|
|
<li>A primitive type may be changed to its corresponding primitive wrapper
|
|
type. This is a compatible change.</li>
|
|
<li>For primary key fields and fields of a composite key class, a primitive
|
|
wrapper type may be changed to its corresponding primitive type. This is
|
|
allowed because these key fields with reference types may never have null
|
|
values. This is a compatible change.</li>
|
|
</ul>
|
|
|
|
<p>Any other changes to a key field are incompatible and may be made only by
|
|
performing a <a href="#storeConversion">store conversion</a>.</p>
|
|
|
|
<p>Key ordering, including the behavior of a custom <A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Comparable.html" title="class or interface in java.lang"><CODE>Comparable</CODE></A>, is also fixed, since keys are stored in order in the
|
|
index. The specifications for key ordering may not be changed, and the
|
|
developer is responsible for not changing the behavior of a <code>Comparable</code>
|
|
key class. <strong>WARNING:</strong>: Changing the behavior of a <code>Comparable</code> key class is likely to make the index unusable.</p>
|
|
|
|
<h2>Compatible Type Changes</h2>
|
|
|
|
<p>Entity data, unlike key data, is versioned. Therefore, some changes can be
|
|
made compatibly and other changes can be handled via mutations. Compatible
|
|
changes are defined below. To make a compatible class change, a mutation is
|
|
not required; however, the class version must be assigned a new (greater)
|
|
integer value.</p>
|
|
|
|
<p>Changes to a class hierarchy are compatible in some cases. A new class may
|
|
be inserted in the hierarchy. A class may be deleted from the hierarchy as
|
|
long as one of the following is true: 1) it contains no persistent fields, 2)
|
|
any persistent fields are deleted with field Deleter mutations, or 3) the class
|
|
is deleted with a class Deleter mutation. Classes in an existing hierarchy may
|
|
not be reordered compatibly, and fields may not moved from one class to another
|
|
compatibly; for such changes a class Converter mutation is required.</p>
|
|
|
|
<p>Changes to field types in entity class definitions are compatible when they
|
|
conform to the Java Language Specification definitions for <a
|
|
href="http://java.sun.com/docs/books/jls/third_edition/html/conversions.html#5.1.2">Widening
|
|
Primitive Conversions</a> and <a
|
|
href="http://java.sun.com/docs/books/jls/third_edition/html/conversions.html#5.1.5">Widening
|
|
Reference Conversions</a>. For example, a smaller integer
|
|
type may be changed to a larger integer type, and a reference type may be
|
|
changed to one of its supertypes. Automatic widening conversions are performed
|
|
as described in the Java Language Specification.</p>
|
|
|
|
<p>Primitive types may also be compatibly changed to their corresponding
|
|
primitive wrapper types, or to the wrapper type for a widened primitive type.
|
|
However, changing from a primitive wrapper type to a primitive type is not a
|
|
compatible change since existing null values could not be represented.</p>
|
|
|
|
<p>Integer primitive types (byte, short, char, int, long) and their primitive
|
|
wrapper types may be compatibly changed to the BigInteger type.</p>
|
|
|
|
<p>In addition, adding fields to a class is a compatible change. When a
|
|
persistent instance of a class is read that does not contain the new field, the
|
|
new field is initialized by the default constructor.</p>
|
|
|
|
<p>All other changes to instance fields are considered incompatible.
|
|
Incompatible changes may be handled via mutations, as described next.</p>
|
|
|
|
<p>Note that whenever a class is changed, either compatibly or incompatibly, a
|
|
new (higher) class version number must be assigned. See <A HREF="../../../../com/sleepycat/persist/model/Entity.html#version()"><CODE>Entity.version()</CODE></A> and <A HREF="../../../../com/sleepycat/persist/model/Persistent.html#version()"><CODE>Persistent.version()</CODE></A> for information on assigning
|
|
class version numbers.</p>
|
|
|
|
<h2>Mutations</h2>
|
|
|
|
<p>There are three types of mutations: <A HREF="../../../../com/sleepycat/persist/evolve/Renamer.html" title="class in com.sleepycat.persist.evolve"><CODE>Renamer</CODE></A>, <A HREF="../../../../com/sleepycat/persist/evolve/Deleter.html" title="class in com.sleepycat.persist.evolve"><CODE>Deleter</CODE></A> and <A HREF="../../../../com/sleepycat/persist/evolve/Converter.html" title="class in com.sleepycat.persist.evolve"><CODE>Converter</CODE></A>.</p>
|
|
|
|
<p>A class or field can be renamed using a <A HREF="../../../../com/sleepycat/persist/evolve/Renamer.html" title="class in com.sleepycat.persist.evolve"><CODE>Renamer</CODE></A>. Renaming is not expensive, since it
|
|
does not involve conversion of instance data.</p>
|
|
|
|
<p>A class or field can be deleted using a <A HREF="../../../../com/sleepycat/persist/evolve/Deleter.html" title="class in com.sleepycat.persist.evolve"><CODE>Deleter</CODE></A>.</p>
|
|
<ul>
|
|
<li>Deleting an entity class causes removal of the primary and secondary
|
|
indices for the store, on other words, removal of all store entities for that
|
|
class and its subclasses. Removal is performed when the store is opened. A
|
|
<A HREF="../../../../com/sleepycat/persist/evolve/Deleter.html" title="class in com.sleepycat.persist.evolve"><CODE>Deleter</CODE></A> should be used for an entity class
|
|
in all of the following circumstances:
|
|
<ul>
|
|
<li>When removing the entity class itself.</li>
|
|
<li>When removing <A HREF="../../../../com/sleepycat/persist/model/Entity.html" title="annotation in com.sleepycat.persist.model"><CODE>Entity</CODE></A> from the class
|
|
to make it non-persistent.</li>
|
|
<li>When removing <A HREF="../../../../com/sleepycat/persist/model/Entity.html" title="annotation in com.sleepycat.persist.model"><CODE>Entity</CODE></A> from the class
|
|
and adding <A HREF="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><CODE>Persistent</CODE></A>, to use it as an
|
|
embedded persistent class but not an entity class. The version of the class
|
|
must be incremented in this case.</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>Deleting a non-entity class does not itself cause deletion of instance
|
|
data, but is needed to inform DPL that the deleted class will not be used.
|
|
Instances of the deleted class must be handled (discarded or converted to
|
|
another class) by <A HREF="../../../../com/sleepycat/persist/evolve/Deleter.html" title="class in com.sleepycat.persist.evolve"><CODE>Deleter</CODE></A> or <A HREF="../../../../com/sleepycat/persist/evolve/Converter.html" title="class in com.sleepycat.persist.evolve"><CODE>Converter</CODE></A> mutations for the field or enclosing
|
|
class that contain embedded instances of the deleted class. A <A HREF="../../../../com/sleepycat/persist/evolve/Deleter.html" title="class in com.sleepycat.persist.evolve"><CODE>Deleter</CODE></A> should be used for a non-entity class in
|
|
all of the following circumstances:
|
|
<ul>
|
|
<li>When removing the persistent class itself.</li>
|
|
<li>When removing <A HREF="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><CODE>Persistent</CODE></A> from the
|
|
class to make it non-persistent.</li>
|
|
<li>When removing <A HREF="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><CODE>Persistent</CODE></A> from the
|
|
class and adding <A HREF="../../../../com/sleepycat/persist/model/Entity.html" title="annotation in com.sleepycat.persist.model"><CODE>Entity</CODE></A>, to use it as an
|
|
entity class but not an embedded persistent class. The version of the class
|
|
must be incremented in this case.</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>Deleting a field causes automatic conversion of the instances containing
|
|
that field, in order to discard the field values.</li>
|
|
</ul>
|
|
|
|
<p>Other incompatible changes are handled by creating a <A HREF="../../../../com/sleepycat/persist/evolve/Converter.html" title="class in com.sleepycat.persist.evolve"><CODE>Converter</CODE></A> mutation and implementing a <A HREF="../../../../com/sleepycat/persist/evolve/Conversion.html#convert(java.lang.Object)"><CODE>Conversion.convert</CODE></A> method that
|
|
manipulates the raw objects and/or simple values directly. The <code>convert</code>
|
|
method is passed an object of the old incompatible type and it returns an
|
|
object of a current type.</p>
|
|
|
|
<p>Conversions can be specified in two ways: for specific fields or for all
|
|
instances of a class. A different <A HREF="../../../../com/sleepycat/persist/evolve/Converter.html" title="class in com.sleepycat.persist.evolve"><CODE>Converter</CODE></A> constructor is used in each case.
|
|
Field-specific conversions are used instead of class conversions when both are
|
|
applicable.</p>
|
|
|
|
<p>Note that each mutation is applied to a specific class version number. The
|
|
class version must be explicitly specified in a mutation for two reasons:</p>
|
|
<ol>
|
|
<li>This provides safety in the face of multiple unconverted versions of a
|
|
given type. Without a version, a single conversion method would have to handle
|
|
multiple input types, and would have to distinguish between them by examining
|
|
the data or type information.</li>
|
|
<li>This allows arbitrary changes to be made. For example, a series of name
|
|
changes may reuse a given name for more than one version. To identify the
|
|
specific type being converted or renamed, a version number is needed.</li>
|
|
</ol>
|
|
<p>See <A HREF="../../../../com/sleepycat/persist/model/Entity.html#version()"><CODE>Entity.version()</CODE></A> and <A HREF="../../../../com/sleepycat/persist/model/Persistent.html#version()"><CODE>Persistent.version()</CODE></A> for information on assigning
|
|
class version numbers.</p>
|
|
|
|
<p>Mutations are therefore responsible for converting each existing
|
|
incompatible class version to the current version as defined by a current class
|
|
definition. For example, consider that class-version A-1 is initially changed
|
|
to A-2 and a mutation is added for converting A-1 to A-2. If later changes in
|
|
version A-3 occur before converting all A-1 instances to version A-2, the
|
|
converter for A-1 will have to be changed. Instead of converting from A-1 to
|
|
A-2 it will need to convert from A-1 to A-3. In addition, a mutation
|
|
converting A-2 to A-3 will be needed.</p>
|
|
|
|
<p>When a <A HREF="../../../../com/sleepycat/persist/evolve/Converter.html" title="class in com.sleepycat.persist.evolve"><CODE>Converter</CODE></A> mutation applies to a
|
|
given object, other mutations that may apply to that object are not
|
|
automatically performed. It is the responsibility of the <A HREF="../../../../com/sleepycat/persist/evolve/Converter.html" title="class in com.sleepycat.persist.evolve"><CODE>Converter</CODE></A> to return an object that conforms to
|
|
the current class definition, including renaming fields and classes. If the
|
|
input object has nested objects or superclasses that also need conversion, the
|
|
converter must perform these nested conversions before returning the final
|
|
converted object. This rule avoids the complexity and potential errors that
|
|
could result if a converter mutation were automatically combined with other
|
|
mutations in an arbitrary manner.</p>
|
|
|
|
<p>The <A HREF="../../../../com/sleepycat/persist/EntityStore.html#evolve(com.sleepycat.persist.evolve.EvolveConfig)"><CODE>EntityStore.evolve</CODE></A>
|
|
method may optionally be used to ensure that all instances of an old class
|
|
version are converted to the current version.</p>
|
|
|
|
<h2>Other Metadata Changes</h2>
|
|
|
|
<p>When a class that happens to be an entity class is renamed, it remains an
|
|
entity class. When a field that happens to be a primary or
|
|
secondary key field is renamed, its metadata remains intact as well.</p>
|
|
|
|
<p>When the <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>SecondaryKey</CODE></A> annotation is
|
|
added to an <em>existing</em> field, a new index is created automatically. The
|
|
new index will be populated by reading the entire primary index when the
|
|
primary index is opened.</p>
|
|
|
|
<p>When the <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>SecondaryKey</CODE></A> annotation is
|
|
included with a <em>new</em> field, a new index is created automatically. The
|
|
new field is required to be a reference type (not a primitive) and must be
|
|
initialized to null (the default behavior) in the default constructor.
|
|
Entities will be indexed by the field when they are stored with a non-null key
|
|
value.</p>
|
|
|
|
<p>When a field with the <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>SecondaryKey</CODE></A>
|
|
annotation is deleted, or when the <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>SecondaryKey</CODE></A> annotation is removed from a field
|
|
without deleting it, the secondary index is removed (dropped). Removal occurs
|
|
when the store is opened.</p>
|
|
|
|
<p>The <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#relate()"><CODE>SecondaryKey.relate</CODE></A> property may NOT be changed. All other properties of a
|
|
<A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>SecondaryKey</CODE></A> may be changed, although
|
|
avoiding changes that cause foreign key integrity errors is the responsibility
|
|
of the application developer. For example, if the <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#relatedEntity()"><CODE>SecondaryKey.relatedEntity()</CODE></A> property is added but
|
|
not all existing secondary keys reference existing primary keys for the related
|
|
entity, foreign key integrity errors may occur.</p>
|
|
|
|
<p>The <A HREF="../../../../com/sleepycat/persist/model/PrimaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>PrimaryKey</CODE></A> annotation may NOT be
|
|
removed from a field in an entity class.</p>
|
|
|
|
<p>The <A HREF="../../../../com/sleepycat/persist/model/PrimaryKey.html#sequence()"><CODE>PrimaryKey.sequence()</CODE></A> property may be
|
|
added, removed, or changed to a different name.</p>
|
|
|
|
<p>The <A HREF="../../../../com/sleepycat/persist/model/Persistent.html#proxyFor()"><CODE>Persistent.proxyFor()</CODE></A> property may be
|
|
NOT be added, removed, or changed to a different class.</p>
|
|
|
|
<h2>Warnings on Testing and Backups</h2>
|
|
|
|
<p>The application developer is responsible for verifying that class evolution
|
|
works properly before deploying with a changed set of persistent classes. The
|
|
DPL will report errors when old class definitions cannot be evolved, for
|
|
example, when a mutation is missing. To test that no such errors will occur,
|
|
application test cases must include instances of all persistent classes.</p>
|
|
|
|
<p>Converter mutations require special testing. Since the application
|
|
conversion method is allowed to return instances of any type, the DPL cannot
|
|
check that the proper type is returned until the data is accessed. To avoid
|
|
data access errors, application test cases must cover converter mutations for
|
|
all potential input and output types.</p>
|
|
|
|
<p>When secondary keys are dropped or entity classes are deleted, the
|
|
underlying databases are deleted and cannot be recovered from the store. This
|
|
takes place when the store is opened. It is strongly recommended that a backup
|
|
of the entire store is made before opening the store and causing class
|
|
evolution to proceed.</p>
|
|
|
|
<h2><a name="storeConversion">Store Conversion<a/></h2>
|
|
|
|
<p>When mutations are not sufficient for handling class changes, a full store
|
|
conversion may be performed. This is necessary for two particular types of
|
|
class changes:</p>
|
|
<ul>
|
|
<li>A change to a physical key format, for example, a change from type
|
|
<code>int</code> to type <code>long</code>.</li>
|
|
<li>A conversion that involves multiple entities at once, for example,
|
|
combining two separate entity classes into a new single entity class.</li>
|
|
</ul>
|
|
|
|
<p>To perform a full store conversion, a program is written that performs the
|
|
following steps to copy the data from the old store to a new converted
|
|
store:</p>
|
|
<ol>
|
|
<li>The old store is opened as a <A HREF="../../../../com/sleepycat/persist/raw/RawStore.html" title="class in com.sleepycat.persist.raw"><CODE>RawStore</CODE></A> and
|
|
the new store is opened as an <A HREF="../../../../com/sleepycat/persist/EntityStore.html" title="class in com.sleepycat.persist"><CODE>EntityStore</CODE></A>.</li>
|
|
<li>All entities are read from the old store. Entities are read using a <A HREF="../../../../com/sleepycat/persist/raw/RawStore.html" title="class in com.sleepycat.persist.raw"><CODE>RawStore</CODE></A> to allow access to entities for which no
|
|
compatible class exists.</li>
|
|
<li>The <A HREF="../../../../com/sleepycat/persist/raw/RawObject.html" title="class in com.sleepycat.persist.raw"><CODE>RawObject</CODE></A> entities are then converted
|
|
to the format desired. Raw objects can be arbitrarily manipulated as needed.
|
|
The updated raw objects must conform to the new evolved class definitions.</li>
|
|
<li>The updated raw entities are converted to live objects by calling the
|
|
<A HREF="../../../../com/sleepycat/persist/model/EntityModel.html#convertRawObject(com.sleepycat.persist.raw.RawObject)"><CODE>EntityModel.convertRawObject</CODE></A> method of the new store. This method converts
|
|
raw objects obtained from a different store, as long as they conform to the new
|
|
evolved class definitions.</li>
|
|
<li>The new live objects are written to the new <A HREF="../../../../com/sleepycat/persist/EntityStore.html" title="class in com.sleepycat.persist"><CODE>EntityStore</CODE></A> using a <A HREF="../../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist"><CODE>PrimaryIndex</CODE></A> as usual.</li>
|
|
</ol>
|
|
|
|
<p>To perform such a conversion, two separate stores must be open at once.
|
|
Both stores may be in the same <A HREF="../../../../com/sleepycat/db/Environment.html" title="class in com.sleepycat.db"><CODE>Environment</CODE></A>, if
|
|
desired, by giving them different store names. But since all data is being
|
|
rewritten, there are performance advantages to creating the new store in a new
|
|
fresh environment: the data will be compacted as it is written, and the old
|
|
store can be removed very quickly by deleting the old environment directory
|
|
after the conversion is complete.</p>
|
|
<P>
|
|
|
|
<P>
|
|
<DL>
|
|
</DL>
|
|
<HR>
|
|
|
|
|
|
<!-- ======= START OF BOTTOM NAVBAR ====== -->
|
|
<A NAME="navbar_bottom"><!-- --></A>
|
|
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
|
|
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
|
|
<TR>
|
|
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
|
|
<A NAME="navbar_bottom_firstrow"><!-- --></A>
|
|
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
|
|
<TR ALIGN="center" VALIGN="top">
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
|
|
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
|
|
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
|
|
</TR>
|
|
</TABLE>
|
|
</TD>
|
|
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
|
|
<b>Berkeley DB</b><br><font size="-1"> version 4.7.25</font></EM>
|
|
</TD>
|
|
</TR>
|
|
|
|
<TR>
|
|
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
|
<A HREF="../../../../com/sleepycat/persist/package-summary.html"><B>PREV PACKAGE</B></A>
|
|
<A HREF="../../../../com/sleepycat/persist/model/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
|
|
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
|
<A HREF="../../../../index.html?com/sleepycat/persist/evolve/package-summary.html" target="_top"><B>FRAMES</B></A>
|
|
<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>
|
|
<SCRIPT type="text/javascript">
|
|
<!--
|
|
if(window==top) {
|
|
document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>');
|
|
}
|
|
//-->
|
|
</SCRIPT>
|
|
<NOSCRIPT>
|
|
<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>
|
|
</NOSCRIPT>
|
|
|
|
|
|
</FONT></TD>
|
|
</TR>
|
|
</TABLE>
|
|
<A NAME="skip-navbar_bottom"></A>
|
|
<!-- ======== END OF BOTTOM NAVBAR ======= -->
|
|
|
|
<HR>
|
|
<font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
|
</BODY>
|
|
</HTML>
|