Implementing the Solution

Task 1: Prerequisites

Task 2: Mapping the Data

You can configure mappings to NoSQL data with the EclipseLink @NoSQL annotation and <no-sql> XML element. The @NoSQL annotation defines the class as mapping to non-relational data. You can use @NoSQL with JPA Entity or Embeddable classes.

The @NoSQL annotation allows you to specify the dataType and dataFormat of the data. The dataType will vary, depending on your NoSQL datasource:

• For MongoDB, dataType is the collection name that the JSON documents are stored to.

• For Oracle NoSQL, dataType is the first part of the major key value.

The dataFormat depends on the type structure (data format) of data being stored.

• For MongoDB, use MAPPED for its structured database.

• For Oracle NoSQL, use MAPPED (for key/value data) or XML (for a single XML document).

Example 21-1 illustrates how to use @NoSQL with @Entity and @Embeddable classes.

@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;  
}

Task 3: Defining IDs

With EclipseLink, you can use any field (or set of fields) as your ID when using a non-relational database, just like any other relational Entity. You can use a natural ID (that is, assigned by the application) or a generated ID (that is, assigned by EclipseLink).

MongoDB also requires an _id field in every document. If no _id field is present, Mongo will automatically generate and assign the _id field using an OID (object identifier), which is similar to a UUID (universally unique identifier).

• To use a natural ID as the Mongo ID, simply name the field as _id by using the @Field (or @Column) annotation without any of the relational details.

  For example:

  @Field(name="_id")
  private long id;
  

• To use the generated Mongo OID as your ID, simply include @Id, @GeneratedValue, and @Field(name="_id") annotations in the object's ID field mapping.

  The @GeneratedValue tells EclipseLink to use the Mongo OID to generate this ID value. To use a UUID instead of the Mongo OID, use the @UUIDGenerator annotation.

  
  

  Note: MongoDB does not support @SequenceGenerator or @TableGenerator nor the IDENTITY, TABLE, and SEQUENCE generation types. The ID of the Mongo OID or UUID is not a numerical value; you must map it as a String or byte[].

  
  

  For example:

  @Id
  @GeneratedValue
  @Field(name="_id")
  private String id;
  

Task 4: Defining Mappings

With non-relational databases, EclipseLink maps objects to structured data such as XML or JSON. NoSQL supports all existing JPA mapping annotations and XML, including embedded data and embedded collections. If you do not define a mapping annotation (or XML) for an attribute EclipseLink uses the default mapping.

Basic Mappings

Because the NoSQL defaults follow the JPA defaults, most simple mappings do not require any configuration. Field names used in the Mongo BSON document will mirror the object attribute names (in uppercase). To use a different BSON field name, use the @Field annotation.

Embedded Values

Use the @Embedded annotation to persist embedded values and the @ElementCollection annotation for embedded collections. Because all data is stored in the XML document, no separate table (that is, @CollectionTable) is needed. Additionally, because embedded objects are nested in the document and do not require unique field names, the @AttributeOverride attribute is not needed.

Relationships

You should use the relationship annotations (such as @OneToOne, @ManyToOne, @OneToMany and @ManyToMany) only with external relationships. Relationships within the document should use the Embedded Values.

EclipseLink fully supports external relationships to other documents by using a foreign key. The ID of the target object is stored in the source object's document. For a collection, a collection of IDs is stored. Use the @JoinField annotation to define the name of the foreign key field in the BSON document.

You can also define a relationship mapping by using a query. However you must use a DescriptorCustomizer instead of an annotation.

@Basic
private String description;
@Basic
private double totalCost = 0;
@Embedded
private Address billingAddress;
@Embedded
private Address shippingAddress;
@ElementCollection
private List<OrderLine> orderLines = new ArrayList<OrderLine>();
@ManyToOne(fetch=FetchType.LAZY)
private Customer customer;

Task 5: Using Locking

Locking support is dependent on the NoSQL platform. Some NoSQL platforms may offer support for optimistic version locking.

• Oracle NoSQL – Locking is not supported.

• MongoDB – Version locking is supported.

  
  

  Note: MongoDB does not support transactions. If a lock error occurs during a transaction, any objects that have been previously written will not be rolled back.

  
  

If the NoSQL platform does not support locking, you can use the @Version annotation (as shown in Example 21-3) to validate objects on merge() operations.

@Version
private long version;
...

Task 6: Defining Queries

Querying in NoSQL is dependent on the NoSQL platform. Some NoSQL data-sources may support dynamic querying through their own query language, others may not support querying at all.

Query query = em.createQuery("Select o from Order o where o.totalCost > 1000");
List<Order> orders = query.getResultList();
 

Query query = em.createQuery("Select o from Order o where o.description like 'Pinball%'");
List<Order> orders = query.getResultList();
 

Query query = em.createQuery("Select o from Order o join o.orderLines l where l.description = :desc");
query.setParameter("desc", "shipping");
List<Order> orders = query.getResultList();
 

Query query = em.createQuery("Select o.totalCost from Order o");
List<BigDecimal> orders = query.getResultList();

Query query = em.createNativeQuery("db.ORDER.findOne({\"_id\":\"" + oid + "\"})", Order.class);
Order order = (Order)query.getSingleResult();

Task 7: Connecting to the Database

EclipseLink connects to NoSQL databases through the persistence.xml file. Use the <eclipselink.target-database> property to define the specific NoSQL platform. You must also define a connection with the <eclipselink.nosql.connection-spec> property. Additional connection values (such as the db, port, and host can also be defined.

<persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_2_0.xsd" version="2.0">
    <persistence-unit name="acme" transaction-type="RESOURCE_LOCAL">
        <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="eclipselink.target-database" value="org.eclipse.persistence.nosql.adapters.mongo.MongoPlatform"/>
            <property name="eclipselink.nosql.connection-spec" value="org.eclipse.persistence.nosql.adapters.mongo.MongoConnectionSpec"/>
            <property name="eclipselink.nosql.property.mongo.port" value="27017, 27017"/>
            <property name="eclipselink.nosql.property.mongo.host" value="host1, host2"/>
            <property name="eclipselink.nosql.property.mongo.db" value="acme"/>
        </properties>
    </persistence-unit>
</persistence>