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:50 EDT 2010 --> 6<TITLE> 7KeyField (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="KeyField (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="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> 42 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 43 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/KeyField.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/model/FieldMetadata.html" title="class in com.sleepycat.persist.model"><B>PREV CLASS</B></A> 59 <A HREF="../../../../com/sleepycat/persist/model/ModelInternal.html" title="class in com.sleepycat.persist.model"><B>NEXT CLASS</B></A></FONT></TD> 60<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 61 <A HREF="../../../../index.html?com/sleepycat/persist/model/KeyField.html" target="_top"><B>FRAMES</B></A> 62 <A HREF="KeyField.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<TR> 78<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 79 SUMMARY: <A HREF="#annotation_type_required_element_summary">REQUIRED</A> | OPTIONAL</FONT></TD> 80<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 81DETAIL: <A HREF="#annotation_type_element_detail">ELEMENT</A></FONT></TD> 82</TR> 83</TABLE> 84<A NAME="skip-navbar_top"></A> 85<!-- ========= END OF TOP NAVBAR ========= --> 86 87<HR> 88<!-- ======== START OF CLASS DATA ======== --> 89<H2> 90<FONT SIZE="-1"> 91com.sleepycat.persist.model</FONT> 92<BR> 93Annotation Type KeyField</H2> 94<HR> 95<DL> 96<DT><PRE><FONT SIZE="-1"><A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/annotation/Documented.html?is-external=true" title="class or interface in java.lang.annotation">@Documented</A> 97<A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/annotation/Retention.html?is-external=true" title="class or interface in java.lang.annotation">@Retention</A>(<A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/annotation/Retention.html?is-external=true#value()" title="class or interface in java.lang.annotation">value</A>=<A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/annotation/RetentionPolicy.html?is-external=true#RUNTIME" title="class or interface in java.lang.annotation">RUNTIME</A>) 98<A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/annotation/Target.html?is-external=true" title="class or interface in java.lang.annotation">@Target</A>(<A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/annotation/Target.html?is-external=true#value()" title="class or interface in java.lang.annotation">value</A>=<A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/annotation/ElementType.html?is-external=true#FIELD" title="class or interface in java.lang.annotation">FIELD</A>) 99</FONT>public @interface <B>KeyField</B></DL> 100</PRE> 101 102<P> 103Indicates the sorting position of a key field in a composite key class when 104 the <code>Comparable</code> interface is not implemented. The <code>KeyField</code> 105 integer value specifies the sort order of this field within the set of 106 fields in the composite key. 107 108 <p>If the field type of a <A HREF="../../../../com/sleepycat/persist/model/PrimaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>PrimaryKey</CODE></A> or <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>SecondaryKey</CODE></A> is a 109 composite key class containing more than one key field, then a <code>KeyField</code> annotation must be present on each non-transient instance field of 110 the composite key class. The <code>KeyField</code> value must be a number 111 between one and the number of non-transient instance fields declared in the 112 composite key class.</p> 113 114 <p>Note that a composite key class is a flat container for one or more 115 simple type fields. All non-transient instance fields in the composite key 116 class are key fields, and its superclass must be <code>Object</code>.</p> 117 118 <p>For example:</p> 119 <pre class="code"> 120 @Entity 121 class Animal { 122 @PrimaryKey 123 Classification classification; 124 ... 125 } 126 127 @Persistent 128 class Classification { 129 @KeyField(1) String kingdom; 130 @KeyField(2) String phylum; 131 @KeyField(3) String clazz; 132 @KeyField(4) String order; 133 @KeyField(5) String family; 134 @KeyField(6) String genus; 135 @KeyField(7) String species; 136 @KeyField(8) String subspecies; 137 ... 138 }</pre> 139 140 <p>This causes entities to be sorted first by <code>kingdom</code>, then by 141 <code>phylum</code> within <code>kingdom</code>, and so on.</p> 142 143 <p>The fields in a composite key class may not be null.</p> 144 145 <p><a name="comparable"><strong>Custom Sort Order</strong></a></p> 146 147 <p>To override the default sort order, a composite key class may implement 148 the <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> interface. This allows overriding the sort order and 149 is therefore useful even when there is only one key field in the composite 150 key class. For example, the following class sorts Strings using a Canadian 151 collator:</p> 152 153 <pre class="code"> 154 import java.text.Collator; 155 import java.util.Locale; 156 157 @Entity 158 class Animal { 159 ... 160 @SecondaryKey(relate=ONE_TO_ONE) 161 CollatedString canadianName; 162 ... 163 } 164 165 @Persistent 166 class CollatedString implements Comparable<CollatedString> { 167 168 static Collator collator = Collator.getInstance(Locale.CANADA); 169 170 @KeyField(1) 171 String value; 172 173 CollatedString(String value) { this.value = value; } 174 175 private CollatedString() {} 176 177 public int compareTo(CollatedString o) { 178 return collator.compare(value, o.value); 179 } 180 }</pre> 181 182 <p>Several important rules should be considered when implementing a custom 183 comparison method. Failure to follow these rules may result in the primary 184 or secondary index becoming unusable; in other words, the store will not be 185 able to function.</p> 186 <ol> 187 <li>The comparison method must always return the same result, given the same 188 inputs. The behavior of the comparison method must not change over 189 time.</li> 190 <br> 191 <li>A corollary to the first rule is that the behavior of the comparison 192 method must not be dependent on state which may change over time. For 193 example, if the above collation method used the default Java locale, and the 194 default locale is changed, then the sort order will change.</li> 195 <br> 196 <li>The comparison method must not assume that it is called after the store 197 has been opened. With Berkeley DB Java Edition, the comparison method is 198 called during database recovery, which occurs in the <A HREF="../../../../com/sleepycat/db/Environment.html" title="class in com.sleepycat.db"><CODE>Environment</CODE></A> 199 constructor.</li> 200 <br> 201 <li>The comparison method must not assume that it will only be called with 202 keys that are currently present in the database. The comparison method will 203 occasionally be called with deleted keys or with keys for records that were 204 not part of a committed transaction.</li> 205 </ol> 206<P> 207 208<P> 209<HR> 210 211<P> 212<!-- =========== ANNOTATION TYPE REQUIRED MEMBER SUMMARY =========== --> 213 214<A NAME="annotation_type_required_element_summary"><!-- --></A> 215<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 216<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 217<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> 218<B>Required Element Summary</B></FONT></TH> 219</TR> 220<TR BGCOLOR="white" CLASS="TableRowColor"> 221<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 222<CODE> int</CODE></FONT></TD> 223<TD><CODE><B><A HREF="../../../../com/sleepycat/persist/model/KeyField.html#value()">value</A></B></CODE> 224 225<BR> 226 </TD> 227</TR> 228</TABLE> 229 230<P> 231 232<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== --> 233 234<A NAME="annotation_type_element_detail"><!-- --></A> 235<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 236<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 237<TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2"> 238<B>Element Detail</B></FONT></TH> 239</TR> 240</TABLE> 241 242<A NAME="value()"><!-- --></A><H3> 243value</H3> 244<PRE> 245public abstract int <B>value</B></PRE> 246<DL> 247<DD><DL> 248</DL> 249</DD> 250<DD><DL> 251</DL> 252</DL> 253<!-- ========= END OF CLASS DATA ========= --> 254<HR> 255 256 257<!-- ======= START OF BOTTOM NAVBAR ====== --> 258<A NAME="navbar_bottom"><!-- --></A> 259<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> 260<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 261<TR> 262<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 263<A NAME="navbar_bottom_firstrow"><!-- --></A> 264<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 265 <TR ALIGN="center" VALIGN="top"> 266 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> 267 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> 268 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 269 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/KeyField.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> 270 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 271 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 272 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 273 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 274 </TR> 275</TABLE> 276</TD> 277<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 278<b>Berkeley DB</b><br><font size="-1"> version 4.8.30</font></EM> 279</TD> 280</TR> 281 282<TR> 283<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 284 <A HREF="../../../../com/sleepycat/persist/model/FieldMetadata.html" title="class in com.sleepycat.persist.model"><B>PREV CLASS</B></A> 285 <A HREF="../../../../com/sleepycat/persist/model/ModelInternal.html" title="class in com.sleepycat.persist.model"><B>NEXT CLASS</B></A></FONT></TD> 286<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 287 <A HREF="../../../../index.html?com/sleepycat/persist/model/KeyField.html" target="_top"><B>FRAMES</B></A> 288 <A HREF="KeyField.html" target="_top"><B>NO FRAMES</B></A> 289 <SCRIPT type="text/javascript"> 290 <!-- 291 if(window==top) { 292 document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>'); 293 } 294 //--> 295</SCRIPT> 296<NOSCRIPT> 297 <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A> 298</NOSCRIPT> 299 300 301</FONT></TD> 302</TR> 303<TR> 304<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 305 SUMMARY: <A HREF="#annotation_type_required_element_summary">REQUIRED</A> | OPTIONAL</FONT></TD> 306<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 307DETAIL: <A HREF="#annotation_type_element_detail">ELEMENT</A></FONT></TD> 308</TR> 309</TABLE> 310<A NAME="skip-navbar_bottom"></A> 311<!-- ======== END OF BOTTOM NAVBAR ======= --> 312 313<HR> 314<font size=1>Copyright (c) 1996-2009 Oracle. All rights reserved.</font> 315</BODY> 316</HTML> 317