1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<!--NewPage--> 3<HTML> 4<HEAD> 5<!-- Generated by javadoc (build 1.6.0_03) on Mon Apr 12 16:25:51 EDT 2010 --> 6<TITLE> 7com.sleepycat.persist.evolve (Oracle - Berkeley DB Java API) 8</TITLE> 9 10<META NAME="date" CONTENT="2010-04-12"> 11 12<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../style.css" TITLE="Style"> 13 14<SCRIPT type="text/javascript"> 15function windowTitle() 16{ 17 if (location.href.indexOf('is-external=true') == -1) { 18 parent.document.title="com.sleepycat.persist.evolve (Oracle - Berkeley DB Java API)"; 19 } 20} 21</SCRIPT> 22<NOSCRIPT> 23</NOSCRIPT> 24 25</HEAD> 26 27<BODY BGCOLOR="white" onload="windowTitle();"> 28<HR> 29 30 31<!-- ========= START OF TOP NAVBAR ======= --> 32<A NAME="navbar_top"><!-- --></A> 33<A HREF="#skip-navbar_top" title="Skip navigation links"></A> 34<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 35<TR> 36<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 37<A NAME="navbar_top_firstrow"><!-- --></A> 38<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 39 <TR ALIGN="center" VALIGN="top"> 40 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> 41 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD> 42 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> 43 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> 44 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 45 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 46 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 47 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 48 </TR> 49</TABLE> 50</TD> 51<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 52<b>Berkeley DB</b><br><font size="-1"> version 4.8.30</font></EM> 53</TD> 54</TR> 55 56<TR> 57<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 58 <A HREF="../../../../com/sleepycat/persist/package-summary.html"><B>PREV PACKAGE</B></A> 59 <A HREF="../../../../com/sleepycat/persist/model/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD> 60<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 61 <A HREF="../../../../index.html?com/sleepycat/persist/evolve/package-summary.html" target="_top"><B>FRAMES</B></A> 62 <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> 63 <SCRIPT type="text/javascript"> 64 <!-- 65 if(window==top) { 66 document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>'); 67 } 68 //--> 69</SCRIPT> 70<NOSCRIPT> 71 <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A> 72</NOSCRIPT> 73 74 75</FONT></TD> 76</TR> 77</TABLE> 78<A NAME="skip-navbar_top"></A> 79<!-- ========= END OF TOP NAVBAR ========= --> 80 81<HR> 82<H2> 83Package com.sleepycat.persist.evolve 84</H2> 85Utilities for managing class evolution of persistent objects. 86<P> 87<B>See:</B> 88<BR> 89 <A HREF="#package_description"><B>Description</B></A> 90<P> 91 92<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 93<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 94<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> 95<B>Interface Summary</B></FONT></TH> 96</TR> 97<TR BGCOLOR="white" CLASS="TableRowColor"> 98<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Conversion.html" title="interface in com.sleepycat.persist.evolve">Conversion</A></B></TD> 99<TD>Converts an old version of an object value to conform to the current class 100 or field definition.</TD> 101</TR> 102<TR BGCOLOR="white" CLASS="TableRowColor"> 103<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EvolveListener.html" title="interface in com.sleepycat.persist.evolve">EvolveListener</A></B></TD> 104<TD>The listener interface called during eager entity evolution.</TD> 105</TR> 106</TABLE> 107 108 109<P> 110 111<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 112<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 113<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> 114<B>Class Summary</B></FONT></TH> 115</TR> 116<TR BGCOLOR="white" CLASS="TableRowColor"> 117<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Converter.html" title="class in com.sleepycat.persist.evolve">Converter</A></B></TD> 118<TD>A mutation for converting an old version of an object value to conform to 119 the current class or field definition.</TD> 120</TR> 121<TR BGCOLOR="white" CLASS="TableRowColor"> 122<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Deleter.html" title="class in com.sleepycat.persist.evolve">Deleter</A></B></TD> 123<TD>A mutation for deleting an entity class or field.</TD> 124</TR> 125<TR BGCOLOR="white" CLASS="TableRowColor"> 126<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EntityConverter.html" title="class in com.sleepycat.persist.evolve">EntityConverter</A></B></TD> 127<TD>A subclass of Converter that allows specifying keys to be deleted.</TD> 128</TR> 129<TR BGCOLOR="white" CLASS="TableRowColor"> 130<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EvolveConfig.html" title="class in com.sleepycat.persist.evolve">EvolveConfig</A></B></TD> 131<TD>Configuration properties for eager conversion of unevolved objects.</TD> 132</TR> 133<TR BGCOLOR="white" CLASS="TableRowColor"> 134<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EvolveEvent.html" title="class in com.sleepycat.persist.evolve">EvolveEvent</A></B></TD> 135<TD>The event passed to the EvolveListener interface during eager entity 136 evolution.</TD> 137</TR> 138<TR BGCOLOR="white" CLASS="TableRowColor"> 139<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EvolveInternal.html" title="class in com.sleepycat.persist.evolve">EvolveInternal</A></B></TD> 140<TD>Internal access class that should not be used by applications.</TD> 141</TR> 142<TR BGCOLOR="white" CLASS="TableRowColor"> 143<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/EvolveStats.html" title="class in com.sleepycat.persist.evolve">EvolveStats</A></B></TD> 144<TD>Statistics accumulated during eager entity evolution.</TD> 145</TR> 146<TR BGCOLOR="white" CLASS="TableRowColor"> 147<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Mutation.html" title="class in com.sleepycat.persist.evolve">Mutation</A></B></TD> 148<TD>The base class for all mutations.</TD> 149</TR> 150<TR BGCOLOR="white" CLASS="TableRowColor"> 151<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Mutations.html" title="class in com.sleepycat.persist.evolve">Mutations</A></B></TD> 152<TD>A collection of mutations for configuring class evolution.</TD> 153</TR> 154<TR BGCOLOR="white" CLASS="TableRowColor"> 155<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/Renamer.html" title="class in com.sleepycat.persist.evolve">Renamer</A></B></TD> 156<TD>A mutation for renaming a class or field without changing the instance or 157 field value.</TD> 158</TR> 159</TABLE> 160 161 162<P> 163 164<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 165<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 166<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> 167<B>Exception Summary</B></FONT></TH> 168</TR> 169<TR BGCOLOR="white" CLASS="TableRowColor"> 170<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/DeletedClassException.html" title="class in com.sleepycat.persist.evolve">DeletedClassException</A></B></TD> 171<TD>While reading from an index, an instance of a deleted class version was 172 encountered.</TD> 173</TR> 174<TR BGCOLOR="white" CLASS="TableRowColor"> 175<TD WIDTH="15%"><B><A HREF="../../../../com/sleepycat/persist/evolve/IncompatibleClassException.html" title="class in com.sleepycat.persist.evolve">IncompatibleClassException</A></B></TD> 176<TD>A class has been changed incompatibly and no mutation has been configured to 177 handle the change or a new class version number has not been assigned.</TD> 178</TR> 179</TABLE> 180 181 182<P> 183<A NAME="package_description"><!-- --></A><H2> 184Package com.sleepycat.persist.evolve Description 185</H2> 186 187<P> 188Utilities for managing class evolution of persistent objects. 189 190<h1>Class Evolution</h1> 191 192<p>For persistent data that is not short lived, changes to persistent classes 193are almost inevitable. Some changes are compatible with existing types, and 194data conversion for these changes is performed automatically and transparently. 195Other changes are not compatible with existing types. Mutations can be used to 196explicitly manage many types of incompatible changes.</p> 197 198<p>Not all incompatible class changes can be handled via mutations. For 199example, complex refactoring may require a transformation that manipulates 200multiple entity instances at once. Such changes are not possible with 201mutations but can be made by performing a <a href="#storeConversion">store 202conversion</a>.</p> 203 204<p>The different categories of type changes are described below.</p> 205 206<h2>Key Field Changes</h2> 207 208<p>Unlike entity data, key data is not versioned. Therefore, the physical key 209format for an index is fixed once the index has been opened, and the changes 210allowed for key fields are very limited. The only changes allowed for key 211fields are:</p> 212<ul> 213<li>The name of a key field may be changed, as long as this change is 214accompanied by a <A HREF="../../../../com/sleepycat/persist/evolve/Renamer.html" title="class in com.sleepycat.persist.evolve"><CODE>Renamer</CODE></A> mutation.</li> 215<li>A primitive type may be changed to its corresponding primitive wrapper 216type. This is a compatible change.</li> 217<li>For primary key fields and fields of a composite key class, a primitive 218wrapper type may be changed to its corresponding primitive type. This is 219allowed because these key fields with reference types may never have null 220values. This is a compatible change.</li> 221</ul> 222 223<p>Any other changes to a key field are incompatible and may be made only by 224performing a <a href="#storeConversion">store conversion</a>.</p> 225 226<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?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 227index. The specifications for key ordering may not be changed, and the 228developer is responsible for not changing the behavior of a <code>Comparable</code> 229key class. <strong>WARNING:</strong>: Changing the behavior of a <code>Comparable</code> key class is likely to make the index unusable.</p> 230 231<h2>Compatible Type Changes</h2> 232 233<p>Entity data, unlike key data, is versioned. Therefore, some changes can be 234made compatibly and other changes can be handled via mutations. Compatible 235changes are defined below. To make a compatible class change, a mutation is 236not required; however, the class version must be assigned a new (greater) 237integer value.</p> 238 239<p>Changes to a class hierarchy are compatible in some cases. A new class may 240be inserted in the hierarchy. A class may be deleted from the hierarchy as 241long as one of the following is true: 1) it contains no persistent fields, 2) 242any persistent fields are deleted with field Deleter mutations, or 3) the class 243is deleted with a class Deleter mutation. Classes in an existing hierarchy may 244not be reordered compatibly, and fields may not moved from one class to another 245compatibly; for such changes a class Converter mutation is required.</p> 246 247<p>Changes to field types in entity class definitions are compatible when they 248conform to the Java Language Specification definitions for <a 249href="http://java.sun.com/docs/books/jls/third_edition/html/conversions.html#5.1.2">Widening 250Primitive Conversions</a> and <a 251href="http://java.sun.com/docs/books/jls/third_edition/html/conversions.html#5.1.5">Widening 252Reference Conversions</a>. For example, a smaller integer 253type may be changed to a larger integer type, and a reference type may be 254changed to one of its supertypes. Automatic widening conversions are performed 255as described in the Java Language Specification.</p> 256 257<p>Primitive types may also be compatibly changed to their corresponding 258primitive wrapper types, or to the wrapper type for a widened primitive type. 259However, changing from a primitive wrapper type to a primitive type is not a 260compatible change since existing null values could not be represented.</p> 261 262<p>Integer primitive types (byte, short, char, int, long) and their primitive 263wrapper types may be compatibly changed to the BigInteger type.</p> 264 265<p>Enum values may be added compatibly, but may not be deleted or renamed. As 266long as new values are declared after existing values, the default sort order 267for enum key fields will match the declaration order, i.e, the default sort 268order will match the enum ordinal order. If a new value is inserted (declared 269before an existing value), it will be sorted after all existing values but 270before newly added values. However, these ordering rules are only guaranteed 271for enums containing up to 631 values and only if existing values are not 272reordered. If more than 631 values are declared or the declarations of 273existing values are reordered, then the default sort order will be arbitrary 274and will not match the declaration (ordinal) order.</p> 275 276<p>In addition, adding fields to a class is a compatible change. When a 277persistent instance of a class is read that does not contain the new field, the 278new field is initialized by the default constructor.</p> 279 280<p>All other changes to instance fields are considered incompatible. 281Incompatible changes may be handled via mutations, as described next.</p> 282 283<p>Note that whenever a class is changed, either compatibly or incompatibly, a 284new (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 285class version numbers.</p> 286 287<h2>Mutations</h2> 288 289<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> 290 291<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 292does not involve conversion of instance data.</p> 293 294<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> 295<ul> 296<li>Deleting an entity class causes removal of the primary and secondary 297indices for the store, on other words, removal of all store entities for that 298class and its subclasses. Removal is performed when the store is opened. A 299<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 300in all of the following circumstances: 301 <ul> 302 <li>When removing the entity class itself.</li> 303 <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 304 to make it non-persistent.</li> 305 <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 306 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 307 embedded persistent class but not an entity class. The version of the class 308 must be incremented in this case.</li> 309 </ul> 310</li> 311 312<li>Deleting a non-entity class does not itself cause deletion of instance 313data, but is needed to inform DPL that the deleted class will not be used. 314Instances of the deleted class must be handled (discarded or converted to 315another 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 316class 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 317all of the following circumstances: 318 <ul> 319 <li>When removing the persistent class itself.</li> 320 <li>When removing <A HREF="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><CODE>Persistent</CODE></A> from the 321 class to make it non-persistent.</li> 322 <li>When removing <A HREF="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><CODE>Persistent</CODE></A> from the 323 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 324 entity class but not an embedded persistent class. The version of the class 325 must be incremented in this case.</li> 326 </ul> 327</li> 328 329<li>Deleting a field causes automatic conversion of the instances containing 330that field, in order to discard the field values.</li> 331</ul> 332 333<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 334manipulates the raw objects and/or simple values directly. The <code>convert</code> 335method is passed an object of the old incompatible type and it returns an 336object of a current type.</p> 337 338<p>Conversions can be specified in two ways: for specific fields or for all 339instances 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. 340Field-specific conversions are used instead of class conversions when both are 341applicable.</p> 342 343<p>Note that a class conversion may be not specified for an enum class. A 344field conversion, or a class conversion for the class declaring the field, may 345be used.</p> 346 347<p>Note that each mutation is applied to a specific class version number. The 348class version must be explicitly specified in a mutation for two reasons:</p> 349<ol> 350<li>This provides safety in the face of multiple unconverted versions of a 351given type. Without a version, a single conversion method would have to handle 352multiple input types, and would have to distinguish between them by examining 353the data or type information.</li> 354<li>This allows arbitrary changes to be made. For example, a series of name 355changes may reuse a given name for more than one version. To identify the 356specific type being converted or renamed, a version number is needed.</li> 357</ol> 358<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 359class version numbers.</p> 360 361<p>Mutations are therefore responsible for converting each existing 362incompatible class version to the current version as defined by a current class 363definition. For example, consider that class-version A-1 is initially changed 364to A-2 and a mutation is added for converting A-1 to A-2. If later changes in 365version A-3 occur before converting all A-1 instances to version A-2, the 366converter for A-1 will have to be changed. Instead of converting from A-1 to 367A-2 it will need to convert from A-1 to A-3. In addition, a mutation 368converting A-2 to A-3 will be needed.</p> 369 370<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 371given object, other mutations that may apply to that object are not 372automatically 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 373the current class definition, including renaming fields and classes. If the 374input object has nested objects or superclasses that also need conversion, the 375converter must perform these nested conversions before returning the final 376converted object. This rule avoids the complexity and potential errors that 377could result if a converter mutation were automatically combined with other 378mutations in an arbitrary manner.</p> 379 380<p>The <A HREF="../../../../com/sleepycat/persist/EntityStore.html#evolve(com.sleepycat.persist.evolve.EvolveConfig)"><CODE>EntityStore.evolve</CODE></A> 381method may optionally be used to ensure that all instances of an old class 382version are converted to the current version.</p> 383 384<h2>Other Metadata Changes</h2> 385 386<p>When a class that happens to be an entity class is renamed, it remains an 387entity class. When a field that happens to be a primary or 388secondary key field is renamed, its metadata remains intact as well.</p> 389 390<p>When the <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>SecondaryKey</CODE></A> annotation is 391added to an <em>existing</em> field, a new index is created automatically. The 392new index will be populated by reading the entire primary index when the 393primary index is opened.</p> 394 395<p>When the <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>SecondaryKey</CODE></A> annotation is 396included with a <em>new</em> field, a new index is created automatically. The 397new field is required to be a reference type (not a primitive) and must be 398initialized to null (the default behavior) in the default constructor. 399Entities will be indexed by the field when they are stored with a non-null key 400value.</p> 401 402<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> 403annotation 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 404without deleting it, the secondary index is removed (dropped). Removal occurs 405when the store is opened.</p> 406 407<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 408<A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>SecondaryKey</CODE></A> may be changed, although 409avoiding changes that cause foreign key integrity errors is the responsibility 410of 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 411not all existing secondary keys reference existing primary keys for the related 412entity, foreign key integrity errors may occur.</p> 413 414<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 415removed from a field in an entity class.</p> 416 417<p>The <A HREF="../../../../com/sleepycat/persist/model/PrimaryKey.html#sequence()"><CODE>PrimaryKey.sequence()</CODE></A> property may be 418added, removed, or changed to a different name.</p> 419 420<p>The <A HREF="../../../../com/sleepycat/persist/model/Persistent.html#proxyFor()"><CODE>Persistent.proxyFor()</CODE></A> property may NOT 421be added, removed, or changed to a different class.</p> 422 423<h2>Warnings on Testing and Backups</h2> 424 425<p>The application developer is responsible for verifying that class evolution 426works properly before deploying with a changed set of persistent classes. The 427DPL will report errors when old class definitions cannot be evolved, for 428example, when a mutation is missing. To test that no such errors will occur, 429application test cases must include instances of all persistent classes.</p> 430 431<p>Converter mutations require special testing. Since the application 432conversion method is allowed to return instances of any type, the DPL cannot 433check that the proper type is returned until the data is accessed. To avoid 434data access errors, application test cases must cover converter mutations for 435all potential input and output types.</p> 436 437<p>When secondary keys are dropped or entity classes are deleted, the 438underlying databases are deleted and cannot be recovered from the store. This 439takes place when the store is opened. It is strongly recommended that a backup 440of the entire store is made before opening the store and causing class 441evolution to proceed.</p> 442 443<h2><a name="storeConversion">Store Conversion<a/></h2> 444 445<p>When mutations are not sufficient for handling class changes, a full store 446conversion may be performed. This is necessary for two particular types of 447class changes:</p> 448<ul> 449<li>A change to a physical key format, for example, a change from type 450<code>int</code> to type <code>long</code>.</li> 451<li>A conversion that involves multiple entities at once, for example, 452combining two separate entity classes into a new single entity class.</li> 453</ul> 454 455<p>To perform a full store conversion, a program is written that performs the 456following steps to copy the data from the old store to a new converted 457store:</p> 458<ol> 459<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 460the new store is opened as an <A HREF="../../../../com/sleepycat/persist/EntityStore.html" title="class in com.sleepycat.persist"><CODE>EntityStore</CODE></A>.</li> 461<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 462compatible class exists.</li> 463<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 464to the format desired. Raw objects can be arbitrarily manipulated as needed. 465The updated raw objects must conform to the new evolved class definitions.</li> 466<li>The updated raw entities are converted to live objects by calling the 467<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 468raw objects obtained from a different store, as long as they conform to the new 469evolved class definitions.</li> 470<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> 471</ol> 472 473<p>To perform such a conversion, two separate stores must be open at once. 474Both stores may be in the same <A HREF="../../../../com/sleepycat/db/Environment.html" title="class in com.sleepycat.db"><CODE>Environment</CODE></A>, if 475desired, by giving them different store names. But since all data is being 476rewritten, there are performance advantages to creating the new store in a new 477fresh environment: the data will be compacted as it is written, and the old 478store can be removed very quickly by deleting the old environment directory 479after the conversion is complete.</p> 480<P> 481 482<P> 483<DL> 484</DL> 485<HR> 486 487 488<!-- ======= START OF BOTTOM NAVBAR ====== --> 489<A NAME="navbar_bottom"><!-- --></A> 490<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> 491<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 492<TR> 493<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 494<A NAME="navbar_bottom_firstrow"><!-- --></A> 495<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 496 <TR ALIGN="center" VALIGN="top"> 497 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> 498 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD> 499 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> 500 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> 501 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 502 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 503 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 504 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 505 </TR> 506</TABLE> 507</TD> 508<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 509<b>Berkeley DB</b><br><font size="-1"> version 4.8.30</font></EM> 510</TD> 511</TR> 512 513<TR> 514<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 515 <A HREF="../../../../com/sleepycat/persist/package-summary.html"><B>PREV PACKAGE</B></A> 516 <A HREF="../../../../com/sleepycat/persist/model/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD> 517<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 518 <A HREF="../../../../index.html?com/sleepycat/persist/evolve/package-summary.html" target="_top"><B>FRAMES</B></A> 519 <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> 520 <SCRIPT type="text/javascript"> 521 <!-- 522 if(window==top) { 523 document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>'); 524 } 525 //--> 526</SCRIPT> 527<NOSCRIPT> 528 <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A> 529</NOSCRIPT> 530 531 532</FONT></TD> 533</TR> 534</TABLE> 535<A NAME="skip-navbar_bottom"></A> 536<!-- ======== END OF BOTTOM NAVBAR ======= --> 537 538<HR> 539<font size=1>Copyright (c) 1996-2009 Oracle. All rights reserved.</font> 540</BODY> 541</HTML> 542