Jump to: navigation, search

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

(NoSQL Persistence Units)
m
 
(9 intermediate revisions by one other user not shown)
Line 1: Line 1:
 +
----
 +
 +
[[Image:Elug_draft_icon.png|Warning]] For '''EclipseLink 2.4''' (and newer) refer to "Understanding Non-relational Data Sources" in the '''EclipseLink Concepts Guide''': http://www.eclipse.org/eclipselink/documentation/2.4/concepts/nosql.htm and "@NoSQL" in the ''EclipseLink JPA Extensions Reference Guide '': http://www.eclipse.org/eclipselink/documentation/2.4/jpa/extensions/a_nosql.htm
 +
 +
----
 +
 +
 +
 
{{EclipseLink_UserGuide
 
{{EclipseLink_UserGuide
 
|info=y
 
|info=y
Line 6: Line 14:
 
|api=y
 
|api=y
 
|apis=
 
|apis=
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/NoSQL.html @NoSQL]
+
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/NoSql.html @NoSql]
 
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/DataFormatType.html DataFormatType]
 
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/DataFormatType.html DataFormatType]
 
|nativeapi=y
 
|nativeapi=y
 
|nativeapis=
 
|nativeapis=
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/eis/EISDescriptor.html EISDescriptor]
+
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/eis/EISDescriptor.html EISDescriptor]}}
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/eis/EISPlatform.html EISPlatform]}}
+
  
== @NoSQL ==
+
== @NoSql ==
Mapping to NoSQL data is configured through the EclipseLink <code>@NoSQL</code> annotation, and <code><no-sql></code> XML element.
+
Mapping to NoSql data is configured through the EclipseLink <code>@NoSql</code> annotation, and <code><no-sql></code> XML element.
<code>@NoSQL</code> defines the class as mapping to non-relational data.  <code>@NoSQL</code> can be specified with <code>@Entity</code> or <code>@Embeddable</code> classes.
+
<code>@NoSql</code> defines the class as mapping to non-relational data.  <code>@NoSql</code> can be specified with <code>@Entity</code> or <code>@Embeddable</code> classes.
  
The <code>@NoSQL</code> annotation defines a <code>dataType</code> and a <code>dataFormat</code>.  The <code>dataType</code> is name for the entities structure, the meaning of the <code>dataType</code> is dependent on the NoSQL platform.  For MongoDB, it is the collection name that the JSON documents are stored to.  For Oracle NoSQL the <code>dataType</code> is the first part of the major key value.  For the XML file adapter it is the file name.
+
The <code>@NoSql</code> annotation defines a <code>dataType</code> and a <code>dataFormat</code>.  The <code>dataType</code> is name for the entities structure, the meaning of the <code>dataType</code> is dependent on the NoSQL platform.  For MongoDB, it is the collection name that the JSON documents are stored to.  For Oracle NoSQL the <code>dataType</code> is the first part of the major key value.  For the XML file adapter it is the file name.
  
 
The <code>dataFormat</code> specifies the type of structure the data is stored as.  The <code>dataFormat</code> is defined by the <code>DataFormatType</code> enum.
 
The <code>dataFormat</code> specifies the type of structure the data is stored as.  The <code>dataFormat</code> is defined by the <code>DataFormatType</code> enum.
Three types of NoSQL data formats are supported:
+
Three types of NoSql data formats are supported:
 
* <code>XML</code> - maps a class to an XML document, this can be used with XML data-stores, XML files, XML messaging systems, and other XML systems.
 
* <code>XML</code> - maps a class to an XML document, this can be used with XML data-stores, XML files, XML messaging systems, and other XML systems.
 
* <code>MAPPED</code> - maps a class to a set of nested key/value pairs, a value can be an embedded map or list.  This can be used to map to key/value stores, JSON databases, and other structured data systems.
 
* <code>MAPPED</code> - maps a class to a set of nested key/value pairs, a value can be an embedded map or list.  This can be used to map to key/value stores, JSON databases, and other structured data systems.
Line 27: Line 34:
 
The <code>dataFormat</code> is dependent on the NoSQL platform.  MongoDB must use the <code>MAPPED</code> format.  Oracle NoSQL can use either the <code>MAPPED</code> format for key/value data, or the <code>XML</code> format for a single XML document value.  XML files and XML messaging use the <code>XML</code> format.
 
The <code>dataFormat</code> is dependent on the NoSQL platform.  MongoDB must use the <code>MAPPED</code> format.  Oracle NoSQL can use either the <code>MAPPED</code> format for key/value data, or the <code>XML</code> format for a single XML document value.  XML files and XML messaging use the <code>XML</code> format.
  
====NoSQL MAPPED example====
+
======''NoSql MAPPED example''======
 
<source lang="java">
 
<source lang="java">
 
@Entity
 
@Entity
@NoSQL(dataType="orders", dataFormat=DataFormatType.MAPPED)
+
@NoSql(dataType="orders", dataFormat=DataFormatType.MAPPED)
 
public class Order {
 
public class Order {
 
   @Id
 
   @Id
Line 51: Line 58:
  
 
@Embeddable
 
@Embeddable
@NoSQL(dataFormat=DataFormatType.MAPPED)
+
@NoSql(dataFormat=DataFormatType.MAPPED)
 
public class OrderLine {
 
public class OrderLine {
 
     @Field(name="lineNumber")
 
     @Field(name="lineNumber")
Line 82: Line 89:
 
</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 106: Line 113:
  
 
@Embeddable
 
@Embeddable
@NoSQL(dataFormat=DataFormatType.MAPPED)
+
@NoSql
 
public class OrderLine {
 
public class OrderLine {
 
     @Field(name="@line-number")
 
     @Field(name="@line-number")
Line 131: Line 138:
  
 
== Mapping Restrictions ==
 
== Mapping Restrictions ==
NoSQL supports most JPA annotations, but some are not supported, and others have different restrictions than mapping relational data.
+
NoSql supports most JPA annotations, but some are not supported, and others have different restrictions than mapping relational data.
  
 
Supported mapping annotations:
 
Supported mapping annotations:
Line 154: Line 161:
  
 
Unsupported mapping annotations:
 
Unsupported mapping annotations:
* <code>@Table</code>, <code>@SecondaryTable</code> - are not supported with NoSQL, as objects are not mapped to tables, it is replaced by the <code>dataType</code> on the <code>@NoSQL</code> annotation.
+
* <code>@Table</code>, <code>@SecondaryTable</code> - are not supported with NoSQL, as objects are not mapped to tables, it is replaced by the <code>dataType</code> on the <code>@NoSql</code> annotation.
 
* <code>@Column</code> - <code>@Field</code> should be used for NoSQL, as data is not stored in table columns, however <code>@Column</code> is still allowed, but just the <code>name</code> will be used.
 
* <code>@Column</code> - <code>@Field</code> should be used for NoSQL, as data is not stored in table columns, however <code>@Column</code> is still allowed, but just the <code>name</code> will be used.
 
* <code>@JoinColumn</code> - is not supported with NoSQL, it is replaced by <code>@JoinField</code>.
 
* <code>@JoinColumn</code> - is not supported with NoSQL, it is replaced by <code>@JoinField</code>.
Line 165: Line 172:
 
* <code>@JoinFetch</code>, <code>@BatchFetch</code> are not supported.
 
* <code>@JoinFetch</code>, <code>@BatchFetch</code> are not supported.
  
== NoSQL Persistence Units ==
 
NoSQL persistence units are configured the same as JPA persistence units.  The <code>persistence.xml</code> is used to define the persistence unit.  NoSQL persistence units can be application managed, JTA managed, injected, or created through <code>Persistence</code> the same as regular JPA persistence units.  NoSQL persistence units do have some specific persistence unit properties that are required, and have some limitations.
 
 
NoSQL defines the following persistence unit properties:
 
* <code>"eclipselink.nosql.connection-spec"</code> - this specifies an EISConnectionSpec class name that defines how to connect to the NoSQL data-source.
 
* <code>"eclipselink.nosql.connection-factory"</code> - this specifies the JNDI name of a JCA ConnectionFactory, or a JCA ConnectionFactory class name that connects to the NoSQL data-source.
 
* <code>"eclipselink.nosql.property."</code> - this prefix is used to pass driver specific properties to the NoSQL connection spec.
 
 
NoSQL persistence units have the following restrictions:
 
* <code><jta-data-source></code>, <code><non-jta-data-source></code> - these are not supported, as they refer to JDBC DataSources.
 
* <code>JTA</code> - JTA managed persistence units are supported, but XA transactions may not be provided unless the NoSQL JCA resource adapter supports JTA.
 
* <code>"javax.jdbc."</code>, <code>"eclipselink.jdbc."</code> - JDBC specific properties are not supported as NoSQL does not use JDBC.
 
  
 
<br>  
 
<br>  
Line 182: Line 177:
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
|previous=[[EclipseLink/UserGuide/JPA/Advanced JPA Development/NoSQL/About|About NoSQL]]  
+
|previous=[[EclipseLink/UserGuide/JPA/Advanced JPA Development/NoSQL/Persistence Units|NoSQL Persistence Units]]  
|up=[[EclipseLink/UserGuide/JPA/Advanced JPA Development|Advanced JPA Development]]
+
|up=[[EclipseLink/UserGuide/JPA/Advanced JPA Development/NoSQL|NoSQL]]
 
|next=[[EclipseLink/UserGuide/JPA/Advanced JPA Development/NoSQL/Mappings|Mappings]]  
 
|next=[[EclipseLink/UserGuide/JPA/Advanced JPA Development/NoSQL/Mappings|Mappings]]  
 
|version=2.4.0 DRAFT}}
 
|version=2.4.0 DRAFT}}

Latest revision as of 15:21, 15 January 2013


Warning For EclipseLink 2.4 (and newer) refer to "Understanding Non-relational Data Sources" in the EclipseLink Concepts Guide: http://www.eclipse.org/eclipselink/documentation/2.4/concepts/nosql.htm and "@NoSQL" in the EclipseLink JPA Extensions Reference Guide : http://www.eclipse.org/eclipselink/documentation/2.4/jpa/extensions/a_nosql.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 Native API

@NoSql

Mapping to NoSql data is configured through the EclipseLink @NoSql annotation, and <no-sql> XML element. @NoSql defines the class as mapping to non-relational data. @NoSql can be specified with @Entity or @Embeddable classes.

The @NoSql annotation defines a dataType and a dataFormat. The dataType is name for the entities structure, the meaning of the dataType is dependent on the NoSQL platform. For MongoDB, it is the collection name that the JSON documents are stored to. For Oracle NoSQL the dataType is the first part of the major key value. For the XML file adapter it is the file name.

The dataFormat specifies the type of structure the data is stored as. The dataFormat is defined by the DataFormatType enum. Three types of NoSql data formats are supported:

  • XML - maps a class to an XML document, this can be used with XML data-stores, XML files, XML messaging systems, and other XML systems.
  • MAPPED - maps a class to a set of nested key/value pairs, a value can be an embedded map or list. This can be used to map to key/value stores, JSON databases, and other structured data systems.
  • INDEXED - maps a class to an array of values.

The dataFormat is dependent on the NoSQL platform. MongoDB must use the MAPPED format. Oracle NoSQL can use either the MAPPED format for key/value data, or the XML format for a single XML document value. XML files and XML messaging use the XML format.

NoSql MAPPED example
@Entity
@NoSql(dataType="orders", dataFormat=DataFormatType.MAPPED)
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;
}
 
@Embeddable
@NoSql(dataFormat=DataFormatType.MAPPED)
public class OrderLine {
    @Field(name="lineNumber")
    private int lineNumber;
    @Field(name="itemName")
    private String itemName;
    @Field(name="quantity")
    private int quantity;  
}

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",
}
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
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>

Mapping Restrictions

NoSql supports most JPA annotations, but some are not supported, and others have different restrictions than mapping relational data.

Supported mapping annotations:

  • @Entity - defines a root level object in the NoSQL data-store.
  • @Embeddable - defines an object embedded in another object's data structure.
  • @Basic, @Temporal, @Enumerated, @Lob - are supported.
  • @Convert, @Converter, @TypeConverter, @ObjectTypeConverter - are supported.
  • @Access, @Transient, @Mutable - are supported.
  • @Id, @EmbeddedId - are supported.
  • @GeneratedValue, @UuidGenerator - are supported.
  • @Version - is supported, but dependent on the NoSQL data-source to validate version write conflicts.
  • @Embedded - defines a reference that will be embedded in the parent's data structure as a nested structure.
  • @ElementCollection - defines a collection of values or embeddables that will be embedded in the parent's data structure as a list of nested structures.
  • @OneToOne, @ManyToOne - define a relationship to another root level object stored as a foreign key in the source object's data structure.
  • @OneToMany, @ManyToMany - define a relationship to a collection of other root level object stored as a list of foreign keys in the source object's data structure.
  • @Inheritance, @MappedSuperclass, @ClassExtractor - are supported.
  • @Cacheable, @Cache, @ReadOnly, @Noncacheable - are supported.
  • @NamedQuery - is supported on NoSQL data-sources that support querying.
  • @NamedNativeQuery - is supported on NoSQL data-sources that support native querying. The query language is not SQL, but specific to the NoSQL data-store.
  • @EntityListeners, @PrePersist, @PreUpdate, @PreRemove, @PreLoad, @PostPersist, @PostUpdate, @PostRemove, @PostLoad - are supported.
  • @Customizer - is supported.

Unsupported mapping annotations:

  • @Table, @SecondaryTable - are not supported with NoSQL, as objects are not mapped to tables, it is replaced by the dataType on the @NoSql annotation.
  • @Column - @Field should be used for NoSQL, as data is not stored in table columns, however @Column is still allowed, but just the name will be used.
  • @JoinColumn - is not supported with NoSQL, it is replaced by @JoinField.
  • @JoinTable - is not required or supported with NoSQL, OneToManys and ManyToManys are stored as collections of ids embedded in the source object's data structure.
  • @CollectionTable - is not required or supported with NoSQL, ElementCollections are embedded in the parent object's data structure.
  • @MapKeyColumn, @MapKeyClass, @MapKeyJoinColumn - are not currently supported.
  • @OrderBy, @OrderColumn - are not normally required or supported, as order in normally maintained by the object's data structure.
  • @SequenceGenerator, @TableGenerator - are not directly supported.
  • @AttributeOverride, @AssociationOverride - are supported with inheritance, but are not supported or required with embedded relationships as embedded objects are nested in their parent object's data structure, not flatten as in the case of relational data.
  • @JoinFetch, @BatchFetch are not supported.




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