File: package-summary.html

package info (click to toggle)
db5.3 5.3.28-9
links: PTS, VCS
area: main
in suites: jessie-kfreebsd
size: 163,292 kB
sloc: ansic: 448,411; java: 111,824; tcl: 80,544; sh: 44,326; cs: 33,697; cpp: 21,604; perl: 14,557; xml: 10,799; makefile: 4,104; yacc: 1,003; awk: 965; sql: 801; erlang: 342; python: 216; php: 24; asm: 14
file content (545 lines) | stat: -rw-r--r-- 32,079 bytes
parent folder | download | duplicates (8)
<!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.6.0_51) on Mon Sep 09 11:47:06 EDT 2013 -->
<TITLE>
com.sleepycat.persist.evolve (Oracle - Berkeley DB Java API)
</TITLE>

<META NAME="date" CONTENT="2013-09-09">

<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../style.css" TITLE="Style">

<SCRIPT type="text/javascript">
function windowTitle()
{
    if (location.href.indexOf('is-external=true') == -1) {
        parent.document.title="com.sleepycat.persist.evolve (Oracle - Berkeley DB Java API)";
    }
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>

</HEAD>

<BODY BGCOLOR="white" onload="windowTitle();">
<HR>


<!-- ========= 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>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
<b>Berkeley DB</b><br><font size="-1"> version 5.3.28</font></EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../../com/sleepycat/persist/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
&nbsp;<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>  &nbsp;
&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;

<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/EvolveConfigBeanInfo.html" title="class in com.sleepycat.persist.evolve">EvolveConfigBeanInfo</A></B></TD>
<TD>&nbsp;</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>
&nbsp;

<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>
&nbsp;

<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://download.oracle.com/javase/1.5.0/docs/api/java/lang/Comparable.html?is-external=true" 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>Enum values may be added compatibly, but may not be deleted or renamed.  As
long as new values are declared after existing values, the default sort order
for enum key fields will match the declaration order, i.e, the default sort
order will match the enum ordinal order. If a new value is inserted (declared
before an existing value), it will be sorted after all existing values but
before newly added values.  However, these ordering rules are only guaranteed
for enums containing up to 631 values and only if existing values are not
reordered.  If more than 631 values are declared or the declarations of
existing values are reordered, then the default sort order will be arbitrary
and will not match the declaration (ordinal) order.</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 a class conversion may be not specified for an enum class.  A
field conversion, or a class conversion for the class declaring the field, may
be used.</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 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>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
<b>Berkeley DB</b><br><font size="-1"> version 5.3.28</font></EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../../com/sleepycat/persist/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
&nbsp;<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>  &nbsp;
&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<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, 2013 Oracle and/or its affiliates.  All rights reserved.</font>
</BODY>
</HTML>