Difference between revisions of "EclipseLink/UserGuide/JPA/Advanced JPA Development/NoSQL/Mappings"

From Eclipsepedia

Jump to: navigation, search
m
 
(8 intermediate revisions by one user not shown)
Line 1: Line 1:
 +
----
 +
 +
 +
'''[[Image:Elug_draft_icon.png|Warning]] This page is now obsolete. '''
 +
 +
For current information, please see "Using EclipseLink with NoSQL Databases in the ''EclipseLink Solutions Guide'': http://www.eclipse.org/eclipselink/documentation/latest/solutions/nonrelational_db.htm
 +
 +
 +
----
 +
 +
 +
 
{{EclipseLink_UserGuide
 
{{EclipseLink_UserGuide
 
|info=y
 
|info=y
Line 10: Line 22:
 
|nativeapi=y
 
|nativeapi=y
 
|nativeapis=
 
|nativeapis=
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/eis/mappings.html mappings package]}}
+
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/eis/mappings/package-frame.html mappings package]}}
  
 
= Mapping =
 
= Mapping =
NoSQL maps objects to structured data such as XML or JSON.  NoSQL support embedded data and embedded collections.
+
NoSql maps objects to structured data such as XML or JSON.  NoSql supports embedded data and embedded collections.
NoSQL supports all of the existing JPA mapping annotations and XML.  <code>@Column</code> and <code>@JoinColumn</code> should not be used, instead <code>@Field</code> and <code>@JoinField</code> should be used.  <code>@JoinTable</code> and <code>@CollectionTable</code> are not supported, or required.
+
NoSql supports all of the existing JPA mapping annotations and XML.  <code>@Column</code> and <code>@JoinColumn</code> should not be used, instead <code>@Field</code> and <code>@JoinField</code> should be used.  <code>@JoinTable</code> and <code>@CollectionTable</code> are not supported, or required.
  
 
===Id===
 
===Id===
Any entity object must define an Id.  The Id is used by EclipseLink for caching, object identity and to unique identify an object in the data-store.  NoSQL databases may have a concept of an Id, or may not.  The <code>@GeneratedValue</code> option is supported with NoSQL.  It maps to whatever id generating the NoSQL database provides, and if none is provided it makes use of a UUID.  A UUID generated id must be declared as either a <code>String</code> or <code>byte[]</code>.
+
Any entity object must define an Id.  The Id is used by EclipseLink for caching, object identity and to unique identify an object in the data-store.  NoSQL databases may have a concept of an Id, or may not.  The <code>@GeneratedValue</code> option is supported with NoSql.  It maps to whatever id generator the NoSQL database provides, and if none is provided it makes use of a UUID.  A UUID generated id must be declared as either a <code>String</code> or <code>byte[]</code>.
  
 
<blockquote>
 
<blockquote>
Line 28: Line 40:
  
 
===Basic===
 
===Basic===
Basic mappings for NoSQL support all of the same options a regular JPA Basic mappings.  Temporal types, converters, lobs, and enumerated options are supported.  The <code>@Field</code> annotation or <code>field</code> should be used to define the field name.  The field name will be the name of the field used in the object's data structure.
+
Basic mappings for NoSql support all of the same options a regular JPA Basic mappings.  Temporal types, converters, lobs, and enumerated options are supported.  The <code>@Field</code> annotation or <code><field></code> XML element should be used to define the field name.  The field name will be the name of the field used in the object's data structure.
  
 
<blockquote>
 
<blockquote>
Line 38: Line 50:
 
</blockquote>
 
</blockquote>
  
===NoSQL Examples===
+
===Embedded===
 +
Embedded mappings are supported, but are different than relational embedded mappings.  The embedded object is stored nested in the parent object's data-structure, not flattened out as is the case of relational data.  Embedded mappings allow a <code>@Field</code> to define the field element that the embeddable's structure will be stored under.  Attribute and association overrides are not supported, or required, as there is no naming conflict in two embedded objects as they are each nested under their own element.
 +
 
 +
===ElementCollection===
 +
ElementCollection mappings are supported, but are different than relational ElementCollection mappings.  The embeddable object or basic value is stored nested in the parent object's data-structure, not in a separate table out as is the case of relational data.  ElementCollection mappings allow a <code>@Field</code> to define the field element that the collection will be stored under.  Attribute and association overrides are not supported, or required, as there is no naming conflict in two embedded objects as they are each nested under their own element.
 +
 
 +
===Relationships===
 +
OneToOne, ManyToOne, OneToMany and ManyToMany mappings are supported.  <code>@JoinColumn</code> and <code>@JoinTable</code> are not supported, <code>@JoinField</code> should be used instead.  For a OneToOne and ManyToOne the value of the target object's Id is stored.  For a OneToMany and ManyToMany a nested collection of Id values are stored.  The <code>mappedBy</code> attribute is not supported.
 +
 
 +
It is also possible to define relationships using queries instead of storing the ids.  There is no annotation or XML support for mapping queries, but they can be defined using a <code>DescriptorCustomizer</code>.  The query must be defined using an <code>EISInteraction</code>, such as a <code>MappedInteraction</code> or <code>XMLInteraction</code>.  How the interaction will be defined is dependent on the NoSQL platform.
 +
 
 +
===NoSql Examples===
 
The following provides mappings for an Order model.  The first example uses <code>MAPPED</code> data, such as mapping to a MongoDB JSON document.  The second example uses <code>XML</code> data, such as mapping to XML files.
 
The following provides mappings for an Order model.  The first example uses <code>MAPPED</code> data, such as mapping to a MongoDB JSON document.  The second example uses <code>XML</code> data, such as mapping to XML files.
  
====NoSQL MAPPED example====
+
======''NoSql MAPPED example''======
 
<source lang="java">
 
<source lang="java">
 
@Entity
 
@Entity
@NoSQL(dataFormat=DataFormatType.MAPPED, dataType="orders")
+
@NoSql(dataFormat=DataFormatType.MAPPED, dataType="orders")
 
public class Order {
 
public class Order {
 
   @Id
 
   @Id
Line 85: Line 108:
 
</source>
 
</source>
  
====NoSQL XML example====
+
======''NoSql XML example''======
 
<source lang="java">
 
<source lang="java">
 
@Entity
 
@Entity
@NoSQL(dataType="order")
+
@NoSql(dataType="order")
 
public class Order {
 
public class Order {
 
   @Id
 
   @Id
Line 109: Line 132:
  
 
@Embeddable
 
@Embeddable
@NoSQL(dataFormat=DataFormatType.MAPPED)
+
@NoSql(dataFormat=DataFormatType.MAPPED)
 
public class OrderLine {
 
public class OrderLine {
 
     @Field(name="@line-number")
 
     @Field(name="@line-number")
Line 139: Line 162:
 
|previous=[[EclipseLink/UserGuide/JPA/Advanced JPA Development/NoSQL/Configuring|Configuring]]  
 
|previous=[[EclipseLink/UserGuide/JPA/Advanced JPA Development/NoSQL/Configuring|Configuring]]  
 
|up=[[EclipseLink/UserGuide/JPA/NoSQL|NoSQL]]
 
|up=[[EclipseLink/UserGuide/JPA/NoSQL|NoSQL]]
|next=[[EclipseLink/UserGuide/JPA/Advanced JPA Development/NoSQL/Persistence Units|Querying]]  
+
|next=[[EclipseLink/UserGuide/JPA/Advanced JPA Development/NoSQL/Querying|Querying]]  
 
|version=2.4.0 DRAFT}}
 
|version=2.4.0 DRAFT}}

Latest revision as of 07:15, 17 April 2013



Warning This page is now obsolete.

For current information, please see "Using EclipseLink with NoSQL Databases in the EclipseLink Solutions Guide: http://www.eclipse.org/eclipselink/documentation/latest/solutions/nonrelational_db.htm





EclipseLink JPA

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Elug api package icon.png Key API

Elug api package icon.png Native API

Contents


[edit] Mapping

NoSql maps objects to structured data such as XML or JSON. NoSql supports embedded data and embedded collections. NoSql supports all of the existing JPA mapping annotations and XML. @Column and @JoinColumn should not be used, instead @Field and @JoinField should be used. @JoinTable and @CollectionTable are not supported, or required.

[edit] Id

Any entity object must define an Id. The Id is used by EclipseLink for caching, object identity and to unique identify an object in the data-store. NoSQL databases may have a concept of an Id, or may not. The @GeneratedValue option is supported with NoSql. It maps to whatever id generator the NoSQL database provides, and if none is provided it makes use of a UUID. A UUID generated id must be declared as either a String or byte[].

MongoDB - every document is required to have an _id field. If the document does not have the field, then one will be generated by the database using an OID, which is similar to a UUID. An OID must be declared as either a String or byte[]. The application can define its own value for the _id, or can use a generated value. The entity Id is not required to match the MongoDB _id, and composite IDs are supported, but this is recommended to use _id as the Id field name.
Oracle NoSQL - defines major keys and minor keys. By default EclipseLink will create the major key as a composite key of the entity name and each of the entities Id values. Generated id values are supported using UUID.

[edit] Basic

Basic mappings for NoSql support all of the same options a regular JPA Basic mappings. Temporal types, converters, lobs, and enumerated options are supported. The @Field annotation or <field> XML element should be used to define the field name. The field name will be the name of the field used in the object's data structure.

XML - field name can use XPath expressions. These include using '@' for attributes, '/' for nested elements, '[1]' for positional elements, and 'text()' for element text.
Oracle NoSQL - field names map to the minor keys in the key/value store.

[edit] Embedded

Embedded mappings are supported, but are different than relational embedded mappings. The embedded object is stored nested in the parent object's data-structure, not flattened out as is the case of relational data. Embedded mappings allow a @Field to define the field element that the embeddable's structure will be stored under. Attribute and association overrides are not supported, or required, as there is no naming conflict in two embedded objects as they are each nested under their own element.

[edit] ElementCollection

ElementCollection mappings are supported, but are different than relational ElementCollection mappings. The embeddable object or basic value is stored nested in the parent object's data-structure, not in a separate table out as is the case of relational data. ElementCollection mappings allow a @Field to define the field element that the collection will be stored under. Attribute and association overrides are not supported, or required, as there is no naming conflict in two embedded objects as they are each nested under their own element.

[edit] Relationships

OneToOne, ManyToOne, OneToMany and ManyToMany mappings are supported. @JoinColumn and @JoinTable are not supported, @JoinField should be used instead. For a OneToOne and ManyToOne the value of the target object's Id is stored. For a OneToMany and ManyToMany a nested collection of Id values are stored. The mappedBy attribute is not supported.

It is also possible to define relationships using queries instead of storing the ids. There is no annotation or XML support for mapping queries, but they can be defined using a DescriptorCustomizer. The query must be defined using an EISInteraction, such as a MappedInteraction or XMLInteraction. How the interaction will be defined is dependent on the NoSQL platform.

[edit] NoSql Examples

The following provides mappings for an Order model. The first example uses MAPPED data, such as mapping to a MongoDB JSON document. The second example uses XML data, such as mapping to XML files.

[edit] NoSql MAPPED example
@Entity
@NoSql(dataFormat=DataFormatType.MAPPED, dataType="orders")
public class Order {
  @Id
  @GeneratedValue
  @Field(name="_id")
  private long id;
  @Basic
  @Field(name="description")
  private String description;
  @Embedded
  @Field(name="deliveryAddress")
  private Address deliveryAddress
  @ElementCollection
  @Field(name="orderLines")
  private List<OrderLine> orderLines;
  @ManyToOne
  @JoinField(name="customerId")
  private Customer customer;
}

This would produce the following mapped data. The mapped format could map to many different structures, this example shows it as a JSON document.

{
  "_id": "4F99702B271B1948027FAF06",
  "description": "widget order",
  "deliveryAddress": {
      "street": "1712 Hasting Street",
      "city": "Ottawa",
      "province": "ON",
      "postalCode": "L5J1H5",
  },
  "orderLines": [
      {"lineNumber": "1", "itemName": "widget A", "quantity": "5"},
      {"lineNumber": "2", "itemName": "widget B", "quantity": "1"},
      {"lineNumber": "3", "itemName": "widget C", "quantity": "2"}
  ],
  "customerId": "4F99702B271B1948027FAF08",
}
[edit] NoSql XML example
@Entity
@NoSql(dataType="order")
public class Order {
  @Id
  @GeneratedValue
  @Field(name="@id")
  private long id;
  @Basic
  @Field(name="@description")
  private String description;
  @Embedded
  @Field(name="delivery-address")
  private Address deliveryAddress
  @ElementCollection
  @Field(name="orderLines/order-line")
  private List<OrderLine> orderLines;
  @ManyToOne
  @JoinField(name="customer-id")
  private Customer customer;
}
 
@Embeddable
@NoSql(dataFormat=DataFormatType.MAPPED)
public class OrderLine {
    @Field(name="@line-number")
    private int lineNumber;
    @Field(name="@item-name")
    private String itemName;
    @Field(name="@quantity")
    private int quantity;  
}

This would produce the following XML data.

<order id="4F99702B271B1948027FAF06" description="widget order">
  <deliveryAddress street="1712 Hasting Street" city="Ottawa" province="ON" postalCode="L5J1H5"/>
  <order-lines>
      <order-line lineNumber="1" itemName="widget A" quantity="5"/>
      <order-line lineNumber="2" itemName="widget B" quantity="1"/>
      <order-line lineNumber="3" itemName="widget C" quantity="2"/>
  <order-lines>
  <customer-id>4F99702B271B1948027FAF08</customer-id>
<order>



Eclipselink-logo.gif
Version: 2.4.0 DRAFT
Other versions...