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