Edit File - File Manager

Edit File: SecondaryKey.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<HTML>
<HEAD>

<TITLE>
SecondaryKey (Oracle - Berkeley DB Java API)
</TITLE>

<SCRIPT type="text/javascript">
function windowTitle()
{
 parent.document.title="SecondaryKey (Oracle - Berkeley DB Java API)";
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>

</HEAD>

<A NAME="navbar_top"></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
 <TR ALIGN="center" VALIGN="top">
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html">Overview</A>&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html">Package</A>&nbsp;</TD>
 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;Class&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/SecondaryKey.html">Use</A>&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html">Tree</A>&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html">Deprecated</A>&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html">Index</A>&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html">Help</A>&nbsp;</TD>
 </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3>
Berkeley DB version 4.7.25
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2">
&nbsp;<A HREF="../../../../com/sleepycat/persist/model/Relationship.html" title="enum in com.sleepycat.persist.model">PREV CLASS</A>&nbsp;
&nbsp;<A HREF="../../../../com/sleepycat/persist/model/SecondaryKeyMetadata.html" title="class in com.sleepycat.persist.model">NEXT CLASS</A></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2">
 <A HREF="../../../../index.html?com/sleepycat/persist/model/SecondaryKey.html" target="_top">FRAMES</A> &nbsp;
&nbsp;<A HREF="SecondaryKey.html" target="_top">NO FRAMES</A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
 
</SCRIPT>
<NOSCRIPT>
 <A HREF="../../../../allclasses-noframe.html">All Classes</A>
</NOSCRIPT>

</TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3">
 SUMMARY:&nbsp;<A HREF="#annotation_type_required_element_summary">REQUIRED</A>&nbsp;|&nbsp;<A HREF="#annotation_type_optional_element_summary">OPTIONAL</A></TD>
<TD VALIGN="top" CLASS="NavBarCell3">
DETAIL:&nbsp;<A HREF="#annotation_type_element_detail">ELEMENT</A></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>

<HR>

<H2>

com.sleepycat.persist.model
 
Annotation Type SecondaryKey</H2>
<HR>
<DL>
<DT><PRE><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>
<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>)
<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>)
public @interface SecondaryKey</DL>
</PRE>

Indicates a secondary key field of an entity class. The value of the
 secondary key field is a unique or non-unique identifier for the entity and
 is accessed via a <A HREF="../../../../com/sleepycat/persist/SecondaryIndex.html" title="class in com.sleepycat.persist"><CODE>SecondaryIndex</CODE></A>.

<code>SecondaryKey</code> may appear on any number of fields in an entity
 class, subclasses and superclasses. For a secondary key field in the entity
 class or one of its superclasses, all entity instances will be indexed by
 that field (if it is non-null). For a secondary key field in an entity
 subclass, only instances of that subclass will be indexed by that field (if
 it is non-null).

If a secondary key field is null, the entity will not be indexed by that
 key. In other words, the entity cannot be queried by that secondary key nor
 can the entity be found by iterating through the secondary index.

For a given entity class and its superclasses and subclasses, no two
 secondary keys may have the same name. By default, the field name
 identifies the secondary key and the secondary index for a given entity
 class. <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#name()"><CODE>name()</CODE></A> may be specified to override this default.

Using <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#relate()"><CODE>relate()</CODE></A>, instances of the entity class are related to
 secondary keys in a many-to-one, one-to-many, many-to-many, or one-to-one
 relationship. This required property specifies the cardinality of
 each side of the relationship.

A secondary key may optionally be used to form a relationship with
 instances of another entity class using <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#relatedEntity()"><CODE>relatedEntity()</CODE></A> and <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#onRelatedEntityDelete()"><CODE>onRelatedEntityDelete()</CODE></A>. This establishes foreign key constraints
 for the secondary key.

The secondary key field type must be an array or collection type when a
 x-to-many relationship is used or a singular type when an
 x-to-one relationship is used; see <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#relate()"><CODE>relate()</CODE></A>.

The field type (or element type, when an array or collection type is
 used) of a secondary key field must follow the same rules as for a <a href="PrimaryKey.html#keyTypes">primary key type</a>. The <a
 href="PrimaryKey.html#sortOrder">key sort order</a> is also the same.

<HR>

<A NAME="annotation_type_required_element_summary"></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2">
Required Element Summary</TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%">
<CODE>&nbsp;<A HREF="../../../../com/sleepycat/persist/model/Relationship.html" title="enum in com.sleepycat.persist.model">Relationship</A></CODE></TD>
<TD><CODE><A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#relate()">relate</A></CODE>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Defines the relationship between instances of the entity class and the
 secondary keys.</TD>
</TR>
</TABLE>
&nbsp;

<A NAME="annotation_type_optional_element_summary"></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2">
Optional Element Summary</TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%">
<CODE>&nbsp;<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></TD>
<TD><CODE><A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#name()">name</A></CODE>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the key in order to use a name that is different
 than the field name.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%">
<CODE>&nbsp;<A HREF="../../../../com/sleepycat/persist/model/DeleteAction.html" title="enum in com.sleepycat.persist.model">DeleteAction</A></CODE></TD>
<TD><CODE><A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#onRelatedEntityDelete()">onRelatedEntityDelete</A></CODE>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Specifies the action to take when a related entity is deleted having a
 primary key value that exists as a secondary key value for this entity.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%">
<CODE>&nbsp;<A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Class.html" title="class or interface in java.lang">Class</A></CODE></TD>
<TD><CODE><A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#relatedEntity()">relatedEntity</A></CODE>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Specifies the entity to which this entity is related, for establishing
 foreign key constraints.</TD>
</TR>
</TABLE>
&nbsp;

<A NAME="annotation_type_element_detail"></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="1">
Element Detail</TH>
</TR>
</TABLE>

<A NAME="relate()"></A><H3>
relate</H3>
<PRE>
public abstract <A HREF="../../../../com/sleepycat/persist/model/Relationship.html" title="enum in com.sleepycat.persist.model">Relationship</A> relate</PRE>
<DL>
<DD>Defines the relationship between instances of the entity class and the
 secondary keys.

The table below summarizes how to create all four variations of
 relationships.
 <div>
 <table border="yes">
 <tr><th>Relationship</th>
 <th>Field type</th>
 <th>Key type</th>
 <th>Example</th>
 </tr>
 <tr><td><A HREF="../../../../com/sleepycat/persist/model/Relationship.html#ONE_TO_ONE"><CODE>Relationship.ONE_TO_ONE</CODE></A></td>
 <td>Singular</td>
 <td>Unique</td>
 <td>A person record with a unique social security number
 key.</td>
 </tr>
 <tr><td><A HREF="../../../../com/sleepycat/persist/model/Relationship.html#MANY_TO_ONE"><CODE>Relationship.MANY_TO_ONE</CODE></A></td>
 <td>Singular</td>
 <td>Duplicates</td>
 <td>A person record with a non-unique employer key.</td>
 </tr>
 <tr><td><A HREF="../../../../com/sleepycat/persist/model/Relationship.html#ONE_TO_MANY"><CODE>Relationship.ONE_TO_MANY</CODE></A></td>
 <td>Array/Collection</td>
 <td>Unique</td>
 <td>A person record with multiple unique email address keys.</td>
 </tr>
 <tr><td><A HREF="../../../../com/sleepycat/persist/model/Relationship.html#MANY_TO_MANY"><CODE>Relationship.MANY_TO_MANY</CODE></A></td>
 <td>Array/Collection</td>
 <td>Duplicates</td>
 <td>A person record with multiple non-unique organization
 keys.</td>
 </tr>
 </table>
 </div>

For a many-to-x relationship, the secondary index will
 have non-unique keys; in other words, duplicates will be allowed.
 Conversely, for one-to-x relationship, the secondary index
 will have unique keys.

For a x-to-one relationship, the secondary key field is
 singular; in other words, it may not be an array or collection type.
 Conversely, for a x-to-many relationship, the secondary key
 field must be an array or collection type. A collection type is any
 implementation of <A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html" title="class or interface in java.util"><CODE>Collection</CODE></A>.

<DD><DL>
</DL>
</DD>
<DD><DL>
</DL>
</DL>
<A NAME="relatedEntity()"></A><H3>
relatedEntity</H3>
<PRE>
public abstract <A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Class.html" title="class or interface in java.lang">Class</A> relatedEntity</PRE>
<DL>
<DD>Specifies the entity to which this entity is related, for establishing
 foreign key constraints. Values of this secondary key will be
 constrained to the set of primary key values for the given entity class.

The given class must be an entity class. This class is called the
 related entity or foreign entity.

When a related entity class is specified, a check (foreign key
 constraint) is made every time a new secondary key value is stored for
 this entity, and every time a related entity is deleted.

Whenever a new secondary key value is stored for this entity, it is
 checked to ensure it exists as a primary key value of the related
 entity. If it does not, a <A HREF="../../../../com/sleepycat/db/DatabaseException.html" title="class in com.sleepycat.db"><CODE>DatabaseException</CODE></A> will be thrown
 by the <A HREF="../../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist"><CODE>PrimaryIndex</CODE></A> <code>put</code> method.

Whenever a related entity is deleted and its primary key value exists
 as a secondary key value for this entity, the action is taken that is
 specified using the <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#onRelatedEntityDelete()"><CODE>onRelatedEntityDelete()</CODE></A> property.

Together, these two checks guarantee that a secondary key value for
 this entity will always exist as a primary key value for the related
 entity. Note, however, that a transactional store must be configured
 to guarantee this to be true in the face of a crash; see <A HREF="../../../../com/sleepycat/persist/StoreConfig.html#setTransactional(boolean)"><CODE>StoreConfig.setTransactional(boolean)</CODE></A>.

<DD><DL>
</DL>
</DD>
<DD><DL>
</DL>
<DL>
<DT>Default:<DD>void.class</DD>
</DL>
</DL>
<HR>

<A NAME="onRelatedEntityDelete()"></A><H3>
onRelatedEntityDelete</H3>
<PRE>
public abstract <A HREF="../../../../com/sleepycat/persist/model/DeleteAction.html" title="enum in com.sleepycat.persist.model">DeleteAction</A> onRelatedEntityDelete</PRE>
<DL>
<DD>Specifies the action to take when a related entity is deleted having a
 primary key value that exists as a secondary key value for this entity.

Note: This property only applies when <A HREF="../../../../com/sleepycat/persist/model/SecondaryKey.html#relatedEntity()"><CODE>relatedEntity()</CODE></A>
 is specified to define the related entity.

The default action, <A HREF="../../../../com/sleepycat/persist/model/DeleteAction.html#ABORT"><CODE>ABORT</CODE></A>, means that a
 <A HREF="../../../../com/sleepycat/db/DatabaseException.html" title="class in com.sleepycat.db"><CODE>DatabaseException</CODE></A> is thrown in order to abort the current
 transaction.

If <A HREF="../../../../com/sleepycat/persist/model/DeleteAction.html#CASCADE"><CODE>CASCADE</CODE></A> is specified, then this
 entity will be deleted also. This in turn could trigger further
 deletions, causing a cascading effect.

If <A HREF="../../../../com/sleepycat/persist/model/DeleteAction.html#NULLIFY"><CODE>NULLIFY</CODE></A> is specified, then the
 secondary key in this entity is set to null and this entity is updated.
 If the key field type is singular, the field value is set to null;
 therefore, to specify <code>NULLIFY</code> for a singular key field type, a
 primitive wrapper type must be used instead of a primitive type. If the
 key field type is an array or collection type, the key is deleted from
 the array (the array is resized) or from the collection (using <A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html#remove(java.lang.Object)" title="class or interface in java.util"><CODE>Collection.remove</CODE></A>).

<DD><DL>
</DL>
</DD>
<DD><DL>
</DL>
<DL>
<DT>Default:<DD>ABORT</DD>
</DL>
</DL>
<HR>

<A NAME="name()"></A><H3>
name</H3>
<PRE>
public 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> name</PRE>
<DL>
<DD>Specifies the name of the key in order to use a name that is different
 than the field name.

This is convenient when prefixes or suffices are used on field names.
 For example:
 <pre class="code">
 class Person {
 @SecondaryKey(relate=MANY_TO_ONE, relatedEntity=Person.class, name="parentSsn")
 String m_parentSsn;
 }</pre>

It can also be used to uniquely name a key when multiple secondary
 keys for a single entity class have the same field name. For example,
 an entity class and its subclass may both have a field named 'date',
 and both fields are used as secondary keys. The <code>name</code> property
 can be specified for one or both fields to give each key a unique
 name.

<DD><DL>
</DL>
</DD>
<DD><DL>
</DL>
<DL>
<DT>Default:<DD>""</DD>
</DL>
</DL>

<HR>

<A NAME="navbar_bottom"></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
 <TR ALIGN="center" VALIGN="top">
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html">Overview</A>&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html">Package</A>&nbsp;</TD>
 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;Class&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/SecondaryKey.html">Use</A>&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html">Tree</A>&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html">Deprecated</A>&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html">Index</A>&nbsp;</TD>
 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html">Help</A>&nbsp;</TD>
 </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3>
Berkeley DB version 4.7.25
</TD>
</TR>

</TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3">
 SUMMARY:&nbsp;<A HREF="#annotation_type_required_element_summary">REQUIRED</A>&nbsp;|&nbsp;<A HREF="#annotation_type_optional_element_summary">OPTIONAL</A></TD>
<TD VALIGN="top" CLASS="NavBarCell3">
DETAIL:&nbsp;<A HREF="#annotation_type_element_detail">ELEMENT</A></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>

Back to File Manager