greg/je
1
0
Fork 0
mirror of https://github.com/berkeleydb/je.git synced 2024-11-15 01:46:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
je/docs/java/com/sleepycat/persist/model/Entity.html
Greg Burd 10c9f34f67 Initial import.
2021-06-06 13:46:45 -04:00

447 lines
21 KiB
HTML
Raw Permalink Blame History

<!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:46 EDT 2017 -->
<title>Entity (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="Entity (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/Entity.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/DeleteAction.html" title="enum in com.sleepycat.persist.model"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../com/sleepycat/persist/model/EntityMetadata.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/Entity.html" target="_top">Frames</a></li>
<li><a href="Entity.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>Required&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 Entity" class="title">Annotation Type Entity</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre>@Documented
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface <span class="memberNameLabel">Entity</span></pre>
<div class="block">Indicates a persistent entity class. For each entity class, a <a href="../../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist"><code>PrimaryIndex</code></a> can be used to store and access instances of that class.
Optionally, one or more <a href="../../../../com/sleepycat/persist/SecondaryIndex.html" title="class in com.sleepycat.persist"><code>SecondaryIndex</code></a> objects may be used to access
entity instances by secondary key.
<p><strong>Entity Subclasses and Superclasses</strong></p>
<p>An entity class may have any number of subclasses and superclasses;
however, none of these may themselves be entity classes (annotated with
<code>Entity</code>).</p>
<p>Entity superclasses (which must be annotated with <code>Persistent</code>, not
<code>Entity</code>) are used to share common definitions among entity classes.
Fields in an entity superclass may be defined as primary or secondary keys.
For example, the following <code>BaseClass</code> defines the primary key for any
number of entity classes, using a single sequence to assign primary key
values that will be unique across all entity classes that use it. The
entity class <code>Pet</code> extends the base class, implicitly defining a
primary index</p>
<pre class="code">
@Persistent
class BaseClass {
@PrimaryKey(sequence="ID")
long id;
}
@Entity
class Pet extends BaseClass {
@SecondaryKey(relate=ONE_TO_ONE)
String name;
float height;
float weight;
}</pre>
<p>Entity subclasses (which must be annotated with <code>Persistent</code>, not
<code>Entity</code>) are used to provide polymorphism within a single <code>PrimaryIndex</code>. Instances of the entity class and its subclasses are stored
in the same <code>PrimaryIndex</code>. For example, the entity class <code>Pet</code>
defines a primary index that will contain instances of it and its
subclasses, including <code>Cat</code> which is defined below.</p>
<p>Fields in an entity subclass may be defined as secondary keys, and such
secondary keys can only be used to query instances of the subclass. For
example, although the primary key (<code>id</code>) and secondary key (<code>name</code>) can be used to retrieve any <code>Pet</code> instance, the entity subclass
<code>Cat</code> defines a secondary key (<code>finickyness</code>) that only applies
to <code>Cat</code> instances. Querying by this key will never retrieve a <code>Dog</code> instance, if such a subclass existed, because a <code>Dog</code> instance
will never contain a <code>finickyness</code> key.</p>
<pre class="code">
@Persistent
class Cat extends Pet {
@SecondaryKey(relate=MANY_TO_ONE)
int finickyness;
}</pre>
<p><em>WARNING:</em> Entity subclasses that define secondary keys must be
registered prior to storing an instance of the class. This can be done in
two ways:</p>
<ol>
<li>The <a href="../../../../com/sleepycat/persist/model/EntityModel.html#registerClass-java.lang.Class-"><code>registerClass</code></a> method may be called
to register the subclass before opening the entity store.</li>
<li>The <a href="../../../../com/sleepycat/persist/EntityStore.html#getSubclassIndex-com.sleepycat.persist.PrimaryIndex-java.lang.Class-java.lang.Class-java.lang.String-"><code>getSubclassIndex</code></a> method may be
called to implicitly register the subclass after opening the entity
store.</li>
</ol>
<p><strong>Persistent Fields and Types</strong></p>
<p>All non-transient instance fields of an entity class, as well as its
superclasses and subclasses, are persistent. <code>static</code> and <code>transient</code> fields are not persistent. The persistent fields of a class may
be <code>private</code>, package-private (default access), <code>protected</code> or
<code>public</code>.</p>
<p>It is worthwhile to note the reasons that object persistence is defined
in terms of fields rather than properties (getters and setters). This
allows business methods (getters and setters) to be defined independently of
the persistent state of an object; for example, a setter method may perform
validation that could not be performed if it were called during object
deserialization. Similarly, this allows public methods to evolve somewhat
independently of the (typically non-public) persistent fields.</p>
<p><a name="simpleTypes"><strong>Simple Types</strong></a></p>
<p>Persistent types are divided into simple types, enum types, complex
types, and array types. Simple types and enum types are single valued,
while array types may contain multiple elements and complex types may
contain one or more named fields.</p>
<p>Simple types include:</p>
<ul>
<li>Java primitive types: <code>boolean, char, byte, short, int, long,
float, double</code></li>
<li>The wrapper classes for Java primitive types</li>
<li><code>BigDecimal</code></li>
<li><code>BigInteger</code></li>
<li><code>String</code></li>
<li><code>Date</code></li>
</ul>
<p>When null values are required (for optional key fields, for example),
primitive wrapper classes must be used instead of primitive types.</p>
<p>Simple types, enum types and array types do not require annotations to
make them persistent.</p>
<p><a name="proxyTypes"><strong>Complex and Proxy Types</strong></a></p>
<p>Complex persistent classes must be annotated with <a href="../../../../com/sleepycat/persist/model/Entity.html" title="annotation in com.sleepycat.persist.model"><code>Entity</code></a> or
<a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><code>Persistent</code></a>, or must be proxied by a persistent proxy class
(described below). This includes entity classes, subclasses and
superclasses, and all other complex classes referenced via fields of these
classes.</p>
<p>All complex persistent classes must have a default constructor. The
default constructor may be <code>private</code>, package-private (default
access), <code>protected</code>, or <code>public</code>. Other constructors are
allowed but are not used by the persistence mechanism.</p>
<p>It is sometimes desirable to store instances of a type that is externally
defined and cannot be annotated or does not have a default constructor; for
example, a class defined in the Java standard libraries or a 3rd party
library. In this case, a <a href="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="interface in com.sleepycat.persist.model"><code>PersistentProxy</code></a> class may be used to
represent the stored values for the externally defined type. The proxy
class itself must be annotated with <a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><code>Persistent</code></a> like other persistent
classes, and the <a href="../../../../com/sleepycat/persist/model/Persistent.html#proxyFor--"><code>Persistent.proxyFor()</code></a> property must be specified.</p>
<p>For convenience, built-in proxy classes are included for several common
classes (listed below) in the Java library. If you wish, you may define
your own <a href="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="interface in com.sleepycat.persist.model"><code>PersistentProxy</code></a> to override these built-in proxies.</p>
<ul>
<li><code>HashSet</code></li>
<li><code>TreeSet</code></li>
<li><code>HashMap</code></li>
<li><code>TreeMap</code></li>
<li><code>ArrayList</code></li>
<li><code>LinkedList</code></li>
</ul>
<p>Complex persistent types should in general be application-defined
classes. This gives the application control over the persistent state and
its evolution over time.</p>
<p><strong>Other Type Restrictions</strong></p>
<p>Entity classes and subclasses may not be used in field declarations for
persistent types. Fields of entity classes and subclasses must be simple
types or non-entity persistent types (annotated with <a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><code>Persistent</code></a> not
with <a href="../../../../com/sleepycat/persist/model/Entity.html" title="annotation in com.sleepycat.persist.model"><code>Entity</code></a>).</p>
<p>Entity classes, subclasses and superclasses may be <code>abstract</code> and
may implement arbitrary interfaces. Interfaces do not need to be annotated
with <a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><code>Persistent</code></a> in order to be used in a persistent class, since
interfaces do not contain instance fields.</p>
<p>Persistent instances of static nested classes are allowed, but the nested
class must be annotated with <a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><code>Persistent</code></a> or <a href="../../../../com/sleepycat/persist/model/Entity.html" title="annotation in com.sleepycat.persist.model"><code>Entity</code></a>. Inner
classes (non-static nested classes, including anonymous classes) are not
currently allowed as persistent types.</p>
<p>Arrays of simple and persistent complex types are allowed as fields of
persistent types. Arrays may be multidimensional. However, an array may
not be stored as a top level instance in a primary index. Only instances of
entity classes and subclasses may be top level instances in a primary
index.</p>
<p><strong>Embedded Objects</strong></p>
<p>As stated above, the embedded (or member) non-transient non-static fields
of an entity class are themselves persistent and are stored along with their
parent entity object. This allows embedded objects to be stored in an
entity to an arbitrary depth.</p>
<p>There is no arbitrary limit to the nesting depth of embedded objects
within an entity; however, there is a practical limit. When an entity is
marshalled, each level of nesting is implemented internally via recursive
method calls. If the nesting depth is large enough, a <code>StackOverflowError</code> can occur. In practice, this has been observed with a
nesting depth of 12,000, using the default Java stack size.</p>
<p>This restriction on the nesting depth of embedded objects does not apply
to cyclic references, since these are handled specially as described
below.</p>
<p><strong>Object Graphs</strong></p>
<p>When an entity instance is stored, the graph of objects referenced via
its fields is stored and retrieved as a graph. In other words, if a single
instance is referenced by two or more fields when the entity is stored, the
same will be true when the entity is retrieved.</p>
<p>When a reference to a particular object is stored as a member field
inside that object or one of its embedded objects, this is called a cyclic
reference. Because multiple references to a single object are stored as
such, cycles are also represented correctly and do not cause infinite
recursion or infinite processing loops. If an entity containing a cyclic
reference is stored, the cyclic reference will be present when the entity is
retrieved.</p>
<p>Note that the stored object graph is restricted in scope to a single
entity instance. This is because each entity instance is stored separately.
If two entities have a reference to the same object when stored, they will
refer to two separate instances when the entities are retrieved.</p></div>
<dl>
<dt><span class="simpleTagLabel">Author:</span></dt>
<dd>Mark Hayes</dd>
<dt><span class="seeLabel">See Also:</span></dt>
<dd><a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><code>Persistent</code></a>,
<a href="../../../../com/sleepycat/persist/model/PrimaryKey.html" title="annotation in com.sleepycat.persist.model"><code>PrimaryKey</code></a>,
<a href="../../../../com/sleepycat/persist/model/SecondaryKey.html" title="annotation in com.sleepycat.persist.model"><code>SecondaryKey</code></a>,
<a href="../../../../com/sleepycat/persist/model/KeyField.html" title="annotation in com.sleepycat.persist.model"><code>KeyField</code></a></dd>
</dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- =========== 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>int</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/Entity.html#version--">version</a></span></code>
<div class="block">Identifies a new version of a class when an incompatible class change
has been made.</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="version--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>version</h4>
<pre>public abstract&nbsp;int&nbsp;version</pre>
<div class="block">Identifies a new version of a class when an incompatible class change
has been made. Prior versions of a class are referred to by version
number to perform class evolution and conversion using <a href="../../../../com/sleepycat/persist/evolve/Mutations.html" title="class in com.sleepycat.persist.evolve"><code>Mutations</code></a>.
<p>The first version of a class is version zero, if <a href="../../../../com/sleepycat/persist/model/Entity.html#version--"><code>version()</code></a> is
not specified. When an incompatible class change is made, a version
number must be assigned using <a href="../../../../com/sleepycat/persist/model/Entity.html#version--"><code>version()</code></a> that is higher than the
previous version number for the class. If this is not done, an <a href="../../../../com/sleepycat/persist/evolve/IncompatibleClassException.html" title="class in com.sleepycat.persist.evolve"><code>IncompatibleClassException</code></a> will be thrown when the store is opened.</p></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the version.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>0</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/Entity.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/DeleteAction.html" title="enum in com.sleepycat.persist.model"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../com/sleepycat/persist/model/EntityMetadata.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/Entity.html" target="_top">Frames</a></li>
<li><a href="Entity.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>Required&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>
Reference in a new issue View git blame Copy permalink