View source for EclipseLink/UserGuide/JPA/NoSQL

{{EclipseLink_UserGuide
|info=y
|toc=y
|eclipselink=y
|eclipselinktype=JPA
|api=y
|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/DataFormatType.html DataFormatType]
|nativeapi=y
|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/EISPlatform.html EISPlatform]}}

= NoSQL =

NoSQL is a classification of database systems that do not support the SQL standard.  These include document databases, key-value stores, and various other non-standard databases.  EclipseLink supports persistence of Java objects to NoSQL databases through the Java Persistence API (JPA).  EclipseLink's native API is also supported with NoSQL databases.

The NoSQL classification can also be expanded to include Enterprise Information Systems (EIS) including application databases, legacy databases, messaging systems, and transaction processing monitors.

EclipseLink's NoSQL support includes:
* MongoDB
* Oracle NoSQL
* XML files
* JMS
* Oracle AQ

== @NoSQL ==
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.

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.
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>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>INDEXED</code> - maps a class to an array of values.

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====
<source lang="java">
@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;  
}
</source>

This would produce the following mapped data.  The mapped format could map to many different structures, this example shows it as a JSON document.
<source lang="xml">
{
  "_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",
}
</source>

====NoSQL XML example====
<source lang="java">
@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;  
}
</source>

This would produce the following XML data.
<source lang="xml">
<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>
</source>

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

Supported mapping annotations:
* <code>@Entity</code> - defines a root level object in the NoSQL data-store.
* <code>@Embeddable</code> - defines an object embedded in another object's data structure.
* <code>@Basic</code>, <code>@Temporal</code>, <code>@Enumerated</code>, <code>@Lob</code>  - are supported.
* <code>@Access</code>, <code>@Transient</code>  - are supported.
* <code>@Id</code>, <code>@EmbeddedId</code> - are supported.
* <code>@Version</code> - is supported, but dependent on the NoSQL data-source to validate version write conflicts.
* <code>@Embedded</code> - defines a reference that will be embedded in the parent's data structure as a nested structure.
* <code>@ElementCollection</code> - defines a collection of values or embeddables that will be embedded in the parent's data structure as a list of nested structures.
* <code>@OneToOne</code>, <code>@ManyToOne</code> - define a relationship to another root level object stored as a foreign key in the source object's data structure.
* <code>@OneToMany</code>, <code>@ManyToMany</code> - 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.

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>@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 the <code>@JoinField</code>.
* <code>@JoinTable</code> - is not required or supported with NoSQL, OneToManys and ManyToManys are stored as collections of ids embedded in the parent object's data structure.
* <code>@CollectionTable</code> - is not required or supported with NoSQL, ElementCollections are embedded in the parent object's data structure.
* <code>@MapKeyColumn</code>, <code>@MapKeyClass</code>, <code>@MapKeyJoinColumn</code> - are not currently supported.
* <code>@OrderBy</code>, <code>@OrderColumn</code> - are not normally required or supported, as order in normally maintained by the object's data structure.
* <code>@SequenceGenerator</code>, <code>@TableGenerator</code> - are not directly supported.
* <code>@AttributeOverride</code>, <code>@AssociationOverride</code> - 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.

<br> 
<br> 

{{EclipseLink_JPA
|previous=
|up=[[EclipseLink/UserGuide/JPA/Advanced JPA Development|Advanced JPA Development]]
|next=[[EclipseLink/UserGuide/JPA/NoSQL/Mappings|Mappings]] 
|version=2.4.0 DRAFT}}