This chapter describes how to set up your JPA applications to work with a non-relational data source. There are many types of non-relational data sources. These include document databases, key-value stores, and various other non-standard databases, such as MongoDB, Cassandra, and Google BigTable. This chapter focuses on the NoSQL data source. NoSQL is a classification of database systems that do not support the SQL standard. EclipseLink supports persistence of Java objects to NoSQL databases through the Java Persistence API (JPA). EclipseLink native API is also supported with NoSQL databases.
This chapter contains the following sections:
NoSQL is a classification of database systems that do not support the SQL standard.The NoSQL classification can be expanded to include Enterprise Information Systems (EIS) including application databases, legacy databases, messaging systems, and transaction processing monitors, such as IMS, VSAM, and ADABASE.
EclipseLink's NoSQL support includes:
MongoDB
Oracle NoSQL
XML files
JMS
Oracle AQ
A complete description of EclipseLink support for NoSQL is described in Section A.3, "Non-SQL Standard Database Support: NoSQL."
NoSQL and EIS data-sources have a Java Connector Architecture (JCA) resource adapter that supports the Java Connector Architecture Common Client Interface (JCA CCI).
There are many different ways to access NoSQL and EIS data-sources. Many NoSQL data-sources provide a Java API. For EIS data-sources, there are many third party and custom Java adapters. These APIs are normally non-standard, and low-level, similar to JDBC. EclipseLink NoSQL support is built on top of such APIs, and offers the rich, high-level and standard JPA API.
Some NoSQL data-sources support the JDBC API and a subset of the SQL language. Many third-party vendors provide JDBC drivers for EIS data-sources. EclipseLink regular JPA support can be used with any compliant JDBC driver. So, if JDBC access is an option, EclipseLink's NoSQL support is not required, as EclipseLink standard JPA support can be used.
Some NoSQL data-sources may support JCA. JCA is a Java Enterprise Edition API that allows connecting to more generic systems than JDBC. JCA is composed of two parts, a resource adapter layer, and the Common Client Interface (CCI). EclipseLink NoSQL and EIS support is based on the JCA CCI. For MongoDB, Oracle NoSQL, XML files, JMS, and Oracle AQ, EclipseLink provides the JCA adapter and EclipseLink EISPlatform and ConnectionSpec classes. Third party JCA adapters can also be used with EclipseLink as long as they support the CCI. There are third party JCA vendors, such as Attunity, that support various EIS data-sources such as IMS, VSAM and ADABASE.
NoSQL persistence units are configured the same as JPA persistence units. The persistence.xml file is used to define the persistence unit. NoSQL persistence units can be application managed, JTA managed, injected, or created through Persistence 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:
eclipselink.nosql.connection-spec
eclipselink.nosql.connection-factory
eclipselink.nosql.property
eclipselink.target-database—this is used to set the NoSQL platform class, or use org.eclipse.persistence.eis.EISPlatform for a generic platform.
For more information on these properties, see "Persistence Property Extensions Reference"in Oracle Fusion Middleware Java Persistence API (JPA) Extensions Reference for Oracle TopLink.
NoSQL persistence units have the following restrictions:
<jta-data-source>, <non-jta-data-source>—these elements are not supported, as they refer to JDBC DataSources.
JTA—JTA-managed persistence units are supported, but XA transactions may not be provided unless the NoSQL JCA resource adapter supports JTA.
javax.jdbc, eclipselink.jdbc—JDBC-specific properties are not supported as NoSQL does not use JDBC.
To use a NoSQL platform you must set both the eclipselink.nosql.connection-spec to the connection spec class name and the eclipselink.target-database to the platform class name. Each NoSQL platform also supports platform-specific properties that can be set using eclipselink.nosql.property. For more information on values for MongoDB, Oracle NoSQL, XML, JMS, and Oracle AQ, see "@NoSql" in Oracle Fusion Middleware Java Persistence API (JPA) Extensions Reference for Oracle TopLink. See also Section A.3, "Non-SQL Standard Database Support: 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 attribute. The dataType attribute is the name for the entity's 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 attribute specifies the type of structure the data is stored as. The dataFormat attribute is defined by the DataFormatType enum.
For examples of configuring an application with the @NoSql annotation, see "@NoSql" in Oracle Fusion Middleware Java Persistence API (JPA) Extensions Reference for Oracle TopLinkk
NoSQL supports most JPA annotations 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
@Convert, @Converter, @TypeConverter, @ObjectTypeConverter
@Access, @Transient, @Mutable
@Id, @EmbeddedId
@GeneratedValue, @UuidGenerator
@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
@Cacheable, @Cache, @ReadOnly, @Noncacheable
@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
@Customizer
Unsupported mapping annotations:
@Table, @SecondaryTable—are not supported, as objects are not mapped to tables, it is replaced by the dataType on the @NoSql annotation.
@Column—@Field should be used, as data is not stored in table columns, however @Column is still allowed, but just the name will be used.
@JoinColumn—is not supported; it is replaced by @JoinField.
@JoinTable—is not required or supported; OneToManys and ManyToManys are stored as collections of Ids embedded in the source object's data structure.
@CollectionTable—is not required or supported; 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 is 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 flattened as in the case of relational data.
@JoinFetch, @BatchFetch—are not supported.
NoSQL maps objects to structured data such as XML or JSON. NoSQL supports embedded data, embedded collections, and all of the existing JPA mapping annotations.
To map NoSQL objects, you must define IDs, mapping, embedded objects, relationships, and locking. For more information, see "Implementing the Solution" in Oracle Fusion Middleware Solutions Guide for Oracle TopLink.
Whether querying is supported in NoSQL depends on the NoSQL platform you are using. Some NoSQL data-sources may support dynamic querying through their own query language, others may not support querying at all. The following types of queries are supported by NoSQL.
JPQL Queries
Native Queries
Interaction Queries
For more information on support for these queries, see "Defining Queries" in Oracle Fusion Middleware Solutions Guide for Oracle TopLink.
The JPA transaction API is supported with NoSQL data-sources. Some NoSQL data-sources might not support transactions, so the level of transaction support is dependent on the NoSQL platform. JTA persistence units and transactions are also supported, but unless the NoSQL adapter is integrated with JTA, no XA or transaction support will be available.
If the NoSQL data-source does not support transactions, then any database change such as flush() will be committed directly to the database, and rollback() will not have any affect. A commit operation that fails will not roll back any successful changes written before the error. JPA normally does not write to the database until commit or flush() are called, so there will still be some level of transaction support offered by the persistence context.
JPA operations persist(), merge(), and remove() are supported.
MongoDB—Transactions are not supported.
Oracle NoSQL—Transactions are not supported.