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> 7PrimaryKey (Oracle - Berkeley DB Java API) 8</TITLE> 9 10<META NAME="keywords" CONTENT="com.sleepycat.persist.model.PrimaryKey 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="PrimaryKey (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/PrimaryKey.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/PersistentProxy.html" title="interface in com.sleepycat.persist.model"><B>PREV CLASS</B></A> 56 <A HREF="../../../../com/sleepycat/persist/model/PrimaryKeyMetadata.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/PrimaryKey.html" target="_top"><B>FRAMES</B></A> 59 <A HREF="PrimaryKey.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: REQUIRED | <A HREF="#annotation_type_optional_element_summary">OPTIONAL</A></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 PrimaryKey</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>PrimaryKey</B></DL> 97</PRE> 98 99<P> 100Indicates the primary key field of an entity class. The value of the 101 primary key field is the unique identifier for the entity in a <A HREF="../../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist"><CODE>PrimaryIndex</CODE></A>. 102 103 <p><A HREF="../../../../com/sleepycat/persist/model/PrimaryKey.html" title="annotation in com.sleepycat.persist.model"><CODE>PrimaryKey</CODE></A> may appear on at most one declared field per 104 class.</p> 105 106 <p>Primary key values may be automatically assigned as sequential integers 107 using a <A HREF="../../../../com/sleepycat/persist/model/PrimaryKey.html#sequence()"><CODE>sequence()</CODE></A>. In this case the type of the key field is 108 restricted to a simple integer type.</p> 109 110 <p>A primary key field may not be null, unless it is being assigned from a 111 sequence.</p> 112 113 <p><a name="keyTypes"><strong>Key Field Types</strong></a></p> 114 115 <p>The type of a key field must either be one of the following:</p> 116 <ul> 117 <li>Any of the <a href="Entity.html#simpleTypes">simple 118 types</a>.</li> 119 <li>A composite key class containing one or more simple type fields.</li> 120 </ul> 121 <p>Enum types and array types are not allowed.</p> 122 123 <p>When using a composite key class containing more than one key field, each 124 field of the composite key class must be annotated with <A HREF="../../../../com/sleepycat/persist/model/KeyField.html" title="annotation in com.sleepycat.persist.model"><CODE>KeyField</CODE></A> to 125 identify the storage order and default sort order. See <A HREF="../../../../com/sleepycat/persist/model/KeyField.html" title="annotation in com.sleepycat.persist.model"><CODE>KeyField</CODE></A> for 126 an example and more information on composite keys.</p> 127 128 <p><a name="sortOrder"><strong>Key Sort Order</strong></a></p> 129 130 <p>Key field types, being simple types, have a well defined and reasonable 131 default sort order, described below. This sort order is based on a storage 132 encoding that allows a fast byte-by-byte comparison.</p> 133 <ul> 134 <li>All simple types except for <code>String</code> are encoded so that they are 135 sorted as expected, that is, as if the <A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Comparable.html#compareTo(T)" title="class or interface in java.lang"><CODE>Comparable.compareTo(T)</CODE></A> method 136 of their class (or, for primitives, their wrapper class) is called.</li> 137 <br> 138 <li>Strings are encoded as UTF-8 byte arrays. Zero (0x0000) character 139 values are UTF encoded as non-zero values, and therefore embedded zeros in 140 the string are supported. The sequence {0xC0,0x80} is used to 141 encode a zero character. This UTF encoding is the same one used by native 142 Java UTF libraries. However, this encoding of zero does impact the 143 lexicographical ordering, and zeros will not be sorted first (the natural 144 order) or last. For all character values other than zero, the default UTF 145 byte ordering is the same as the Unicode lexicographical character 146 ordering.</li> 147 </ul> 148 149 <p>To override the default sort order, you can use a composite key class 150 that implements <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>. This allows overriding the sort order 151 and is therefore useful even when there is only one key field in the 152 composite key class. See <a href="KeyField.html#comparable">Custom 153 Sort Order</a> for more information on sorting of composite keys.</p> 154 155 <p><a name="inherit"><strong>Inherited Primary Key</strong></a></p> 156 157 <p>If it does not appear on a declared field in the entity class, <code>PrimaryKey</code> must appear on a field of an entity superclass. In the 158 following example, the primary key on the base class is used:</p> 159 160 <pre class="code"> 161 @Persistent 162 class BaseClass { 163 @PrimaryKey 164 long id; 165 ... 166 } 167 @Entity 168 class Employee extends BaseClass { 169 // inherits id primary key 170 ... 171 }</pre> 172 173 <p>If more than one class with <code>PrimaryKey</code> is present in a class 174 hierarchy, the key in the most derived class is used. In this case, primary 175 key fields in superclasses are "shadowed" and are not persistent. In the 176 following example, the primary key in the base class is not used and is not 177 persistent:</p> 178 <pre class="code"> 179 @Persistent 180 class BaseClass { 181 @PrimaryKey 182 long id; 183 ... 184 } 185 @Entity 186 class Employee extends BaseClass { 187 // overrides id primary key 188 @PrimaryKey 189 String uuid; 190 ... 191 }</pre> 192 193 <p>Note that a <code>PrimaryKey</code> is not allowed on entity subclasses. The 194 following is illegal and will cause an <code>IllegalArgumentException</code> when 195 trying to store an <code>Employee</code> instance:</p> 196 <pre class="code"> 197 @Entity 198 class Person { 199 @PrimaryKey 200 long id; 201 ... 202 } 203 @Entity 204 class Employee extends Person { 205 @PrimaryKey 206 String uuid; 207 ... 208 }</pre> 209<P> 210 211<P> 212<HR> 213 214<P> 215<!-- =========== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY =========== --> 216 217<A NAME="annotation_type_optional_element_summary"><!-- --></A> 218<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 219<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 220<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> 221<B>Optional Element Summary</B></FONT></TH> 222</TR> 223<TR BGCOLOR="white" CLASS="TableRowColor"> 224<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 225<CODE> <A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A></CODE></FONT></TD> 226<TD><CODE><B><A HREF="../../../../com/sleepycat/persist/model/PrimaryKey.html#sequence()">sequence</A></B></CODE> 227 228<BR> 229 The name of a sequence from which to assign primary key values 230 automatically.</TD> 231</TR> 232</TABLE> 233 234<P> 235<A NAME="sequence()"><!-- --></A><H3> 236sequence</H3> 237<PRE> 238public abstract <A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A> <B>sequence</B></PRE> 239<DL> 240<DD>The name of a sequence from which to assign primary key values 241 automatically. If a non-empty string is specified, sequential integers 242 will be assigned from the named sequence. 243 244 <p>A single sequence may be used for more than one entity class by 245 specifying the same sequence name for each <code>PrimaryKey</code>. For 246 each named sequence, a <A HREF="../../../../com/sleepycat/db/Sequence.html" title="class in com.sleepycat.db"><CODE>Sequence</CODE></A> will be used to 247 assign key values. For more information on configuring sequences, see 248 <A HREF="../../../../com/sleepycat/persist/EntityStore.html#setSequenceConfig(java.lang.String, com.sleepycat.db.SequenceConfig)"><CODE>EntityStore.setSequenceConfig</CODE></A>.</p> 249 250 <p>To use a sequence, the type of the key field must be a primitive 251 integer type (<code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code>) 252 or the primitive wrapper class for one of these types. A composite key 253 class may also be used to override sort order, but it may contain only a 254 single key field that has one of the types previously mentioned.</p> 255 256 <p>When an entity with a primary key sequence is stored using one of the 257 <code>put</code> methods in the <A HREF="../../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist"><CODE>PrimaryIndex</CODE></A>, a new key will be 258 assigned if the primary key field in the entity instance is null (for a 259 reference type) or zero (for a primitive integer type). Specifying zero 260 for a primitive integer key field is allowed because the initial value 261 of the sequence is one (not zero) by default. If the sequence 262 configuration is changed such that zero is part of the sequence, then 263 the field type must be a primitive wrapper class and the field value 264 must be null to cause a new key to be assigned.</p> 265 266 <p>When one of the <code>put</code> methods in the <A HREF="../../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist"><CODE>PrimaryIndex</CODE></A> 267 is called and a new key is assigned, the assigned value is returned to 268 the caller via the key field of the entity object that is passed as a 269 parameter.</p> 270<P> 271<DD><DL> 272</DL> 273</DD> 274<DD><DL> 275</DL> 276<DL> 277<DT><B>Default:</B><DD>""</DD> 278</DL> 279</DL> 280<!-- ========= END OF CLASS DATA ========= --> 281<HR> 282 283 284<!-- ======= START OF BOTTOM NAVBAR ====== --> 285<A NAME="navbar_bottom"><!-- --></A> 286<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> 287<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 288<TR> 289<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 290<A NAME="navbar_bottom_firstrow"><!-- --></A> 291<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 292 <TR ALIGN="center" VALIGN="top"> 293 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> 294 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> 295 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 296 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/PrimaryKey.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> 297 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 298 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 299 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 300 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 301 </TR> 302</TABLE> 303</TD> 304<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 305<b>Berkeley DB</b><br><font size="-1"> version 4.7.25</font></EM> 306</TD> 307</TR> 308 309<TR> 310<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 311 <A HREF="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="interface in com.sleepycat.persist.model"><B>PREV CLASS</B></A> 312 <A HREF="../../../../com/sleepycat/persist/model/PrimaryKeyMetadata.html" title="class in com.sleepycat.persist.model"><B>NEXT CLASS</B></A></FONT></TD> 313<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 314 <A HREF="../../../../index.html?com/sleepycat/persist/model/PrimaryKey.html" target="_top"><B>FRAMES</B></A> 315 <A HREF="PrimaryKey.html" target="_top"><B>NO FRAMES</B></A> 316 <SCRIPT type="text/javascript"> 317 <!-- 318 if(window==top) { 319 document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>'); 320 } 321 //--> 322</SCRIPT> 323<NOSCRIPT> 324 <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A> 325</NOSCRIPT> 326 327 328</FONT></TD> 329</TR> 330<TR> 331<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 332 SUMMARY: REQUIRED | <A HREF="#annotation_type_optional_element_summary">OPTIONAL</A></FONT></TD> 333<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 334DETAIL: <A HREF="#annotation_type_element_detail">ELEMENT</A></FONT></TD> 335</TR> 336</TABLE> 337<A NAME="skip-navbar_bottom"></A> 338<!-- ======== END OF BOTTOM NAVBAR ======= --> 339 340<HR> 341<font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 342</BODY> 343</HTML> 344