je/docs/java/com/sleepycat/persist/model/SecondaryKey.html
2021-06-06 13:46:45 -04:00

495 lines
21 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (1.8.0_151) on Tue Oct 31 17:36:47 EDT 2017 -->
<title>SecondaryKey (Oracle - Berkeley DB Java Edition API)</title>
<meta name="date" content="2017-10-31">
<link rel="stylesheet" type="text/css" href="../../../../style.css" title="Style">
<script type="text/javascript" src="../../../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="SecondaryKey (Oracle - Berkeley DB Java Edition API)";
}
}
catch(err) {
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/SecondaryKey.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><b>Berkeley DB Java Edition</b><br><font size=\"-1\"> version 7.5.11</font>
</div>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../com/sleepycat/persist/model/Relationship.html" title="enum in com.sleepycat.persist.model"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../com/sleepycat/persist/model/SecondaryKeyMetadata.html" title="class in com.sleepycat.persist.model"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?com/sleepycat/persist/model/SecondaryKey.html" target="_top">Frames</a></li>
<li><a href="SecondaryKey.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.required.element.summary">Required</a>&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">com.sleepycat.persist.model</div>
<h2 title="Annotation Type SecondaryKey" class="title">Annotation Type SecondaryKey</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre>@Documented
@Retention(value=RUNTIME)
@Target(value=FIELD)
public @interface <span class="memberNameLabel">SecondaryKey</span></pre>
<div class="block">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>.
<p><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).</p>
<p>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.</p>
<p>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.</p>
<p>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 <em>cardinality</em> of
each side of the relationship.</p>
<p>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 <em>foreign key constraints</em>
for the secondary key.</p>
<p>The secondary key field type must be a Set, Collection or array type when
a <em>x-to-many</em> relationship is used or a singular type when an
<em>x-to-one</em> relationship is used; see <a href="../../../../com/sleepycat/persist/model/SecondaryKey.html#relate--"><code>relate()</code></a>.</p>
<p>The field type (or element type, when a Set, Collection or array 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.</p>
<p>For a secondary key field with a collection type, a type parameter must
be used to specify the element type. For example <code>Collection&lt;String&gt;</code>
is allowed but <code>Collection</code> is not.</p></div>
<dl>
<dt><span class="simpleTagLabel">Author:</span></dt>
<dd>Mark Hayes</dd>
</dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- =========== ANNOTATION TYPE REQUIRED MEMBER SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.required.element.summary">
<!-- -->
</a>
<h3>Required Element Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Required Element Summary table, listing required elements, and an explanation">
<caption><span>Required Elements</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Required Element and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code><a href="../../../../com/sleepycat/persist/model/Relationship.html" title="enum in com.sleepycat.persist.model">Relationship</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/SecondaryKey.html#relate--">relate</a></span></code>
<div class="block">Defines the relationship between instances of the entity class and the
secondary keys.</div>
</td>
</tr>
</table>
</li>
</ul>
<!-- =========== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.optional.element.summary">
<!-- -->
</a>
<h3>Optional Element Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Optional Element Summary table, listing optional elements, and an explanation">
<caption><span>Optional Elements</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Optional Element and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/SecondaryKey.html#name--">name</a></span></code>
<div class="block">Specifies the name of the key in order to use a name that is different
than the field name.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="../../../../com/sleepycat/persist/model/DeleteAction.html" title="enum in com.sleepycat.persist.model">DeleteAction</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/SecondaryKey.html#onRelatedEntityDelete--">onRelatedEntityDelete</a></span></code>
<div class="block">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.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>java.lang.Class</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/SecondaryKey.html#relatedEntity--">relatedEntity</a></span></code>
<div class="block">Specifies the entity to which this entity is related, for establishing
foreign key constraints.</div>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.element.detail">
<!-- -->
</a>
<h3>Element Detail</h3>
<a name="relate--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>relate</h4>
<pre>public abstract&nbsp;<a href="../../../../com/sleepycat/persist/model/Relationship.html" title="enum in com.sleepycat.persist.model">Relationship</a>&nbsp;relate</pre>
<div class="block">Defines the relationship between instances of the entity class and the
secondary keys.
<p>The table below summarizes how to create all four variations of
relationships.</p>
<div>
<table border="yes" summary="">
<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>Set/Collection/array</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>Set/Collection/array</td>
<td>Duplicates</td>
<td>A person record with multiple non-unique organization
keys.</td>
</tr>
</table>
</div>
<p>For a <em>many-to-x</em> relationship, the secondary index will
have non-unique keys; in other words, duplicates will be allowed.
Conversely, for <em>one-to-x</em> relationship, the secondary index
will have unique keys.</p>
<p>For a <em>x-to-one</em> relationship, the secondary key field is
singular; in other words, it may not be a Set, Collection or array type.
Conversely, for a <em>x-to-many</em> relationship, the secondary key
field must be a Set, Collection or array type. A collection type is any
implementation of <code>Collection</code>.</p>
<p>For a <em>x-to-many</em> relationship, the field type should normally
be <code>Set</code> (or a subtype of this interface). This
accurately expresses the fact that an Entity may not have two identical
secondary keys. For flexibility, a <code>Collection</code> (or a
subtype of this interface) or an array type may also be used. In that
case, any duplicate key values in the Collection or array are
ignored.</p></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the Relationship.</dd>
</dl>
</li>
</ul>
</li>
</ul>
<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="relatedEntity--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>relatedEntity</h4>
<pre>public abstract&nbsp;java.lang.Class&nbsp;relatedEntity</pre>
<div class="block">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.
<p>The given class must be an entity class. This class is called the
<em>related entity</em> or <em>foreign entity</em>.</p>
<p>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.</p>
<p>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, an exception is thrown by the <a href="../../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist"><code>PrimaryIndex</code></a> <code>put</code> method.
<!-- begin JE only -->
On BDB JE, a <a href="../../../../com/sleepycat/je/ForeignConstraintException.html" title="class in com.sleepycat.je"><code>ForeignConstraintException</code></a> will be
thrown.
<!-- end JE only -->
</p>
<p>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.</p>
<p>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>.</p></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the related entity class, or void.class if none is specified.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>void.class</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="onRelatedEntityDelete--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>onRelatedEntityDelete</h4>
<pre>public abstract&nbsp;<a href="../../../../com/sleepycat/persist/model/DeleteAction.html" title="enum in com.sleepycat.persist.model">DeleteAction</a>&nbsp;onRelatedEntityDelete</pre>
<div class="block">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.
<p><em>Note:</em> 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.</p>
<p>The default action, <a href="../../../../com/sleepycat/persist/model/DeleteAction.html#ABORT"><code>ABORT</code></a>, means that an
exception is thrown in order to abort the current transaction.
<!-- begin JE only -->
On BDB JE, a <a href="../../../../com/sleepycat/je/DeleteConstraintException.html" title="class in com.sleepycat.je"><code>DeleteConstraintException</code></a> is
thrown.
<!-- end JE only -->
</p>
<p>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.</p>
<p>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 <code>Collection.remove</code>).</p></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the DeleteAction, or <a href="../../../../com/sleepycat/persist/model/DeleteAction.html#ABORT"><code>DeleteAction.ABORT</code></a> if none is
specified.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>com.sleepycat.persist.model.DeleteAction.ABORT</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="name--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>name</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;name</pre>
<div class="block">Specifies the name of the key in order to use a name that is different
than the field name.
<p>This is convenient when prefixes or suffices are used on field names.
For example:</p>
<pre class="code">
class Person {
@SecondaryKey(relate=MANY_TO_ONE, relatedEntity=Person.class, name="parentSsn")
String m_parentSsn;
}</pre>
<p>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.</p></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the key name that overrides the field name, or empty string if
none is specified.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>""</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/SecondaryKey.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><b>Berkeley DB Java Edition</b><br><font size=\"-1\"> version 7.5.11</font>
</div>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../com/sleepycat/persist/model/Relationship.html" title="enum in com.sleepycat.persist.model"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../com/sleepycat/persist/model/SecondaryKeyMetadata.html" title="class in com.sleepycat.persist.model"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?com/sleepycat/persist/model/SecondaryKey.html" target="_top">Frames</a></li>
<li><a href="SecondaryKey.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.required.element.summary">Required</a>&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><font size=1>Copyright (c) 2002, 2017 Oracle and/or its affiliates. All rights reserved.</font> </small></p>
</body>
</html>