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