kundera-gae-datastore: A Java repository from arci

#kundera-gae-datastore

Kundera client module to support Google App Engine Datastore.

Kundera is a JPA 2.0 compliant Object-Datastore Mapping Library for NoSQL Datastores and is available here.

For complete documentation see Kundera Wiki.

##Supported Features The following feature are supported by this extension:

JPA relationships are supported as Kundera supports them
@GeneratedValue only with strategy GenerationType.AUTO.
@ElementCollection java Collection or Map are supported as types and are serialized when persisted into datastore.
@Embedded embedded entities are natively supported by datastore so are stored using datastore EmbeddedEntity.
@Enumerated java Enum types are supported and stored as strings.

For each feature see the relative JUnit test for usage examples.

Note: java List are natively supported by datastore but only for primitive types, for uniformity each map or collection is serialized.

##ID and Consistency In GAE Datastore, consistency (strong vs eventual) is managed through ancestor paths.

Was not possible for this release to automatically guess the ancestor path through JPA relationships so is not possible for the user to manage entity consistency, each entity is stored in a separated entity group identified by its Kind (the name of the JPA table associated to the entity).

IDs can be specified by the user or automatically generated, there are three possibilities:

@Id annotation on a String type field
@Id annotation on a Long type field
@Id annotation on a long type field

For each case the ID can be user specified before the persist operation but in case of ID auto-generated the field must be of type String and the generated ID will be a string representation of a random java UUID.

##Query support JPQL queries are supported as Kundera supports them, the operator supported is resumed in the following table:

JPA-QL Clause	Azure Table
SELECT	✔
UPDATE	✔
DELETE	✔
ORDER BY	✔
AND	✔
OR	✔
BETWEEN	✔
LIKE	X
IN	✔
=	✔
>	✔
<	✔
>=	✔
<=	✔

Examples in use of queries can be found in the JUnit test.

More details on the operator supported by Datastore can be found in the official documentation.

##Configuration

####persistence.xml The configuration is done in the persistence.xml file, two configuration are possible:

use the datastore instance within the appengine application
use a remote datastore instance through remote API

the properties to be specified inside the<properties> tag for the first case are:

kundera.client.lookup.class required, it.polimi.kundera.client.datastore.DatastoreClientFactory
kundera.ddl.auto.prepare optional, possible values are:
- create which creates the schema (if not already exists)
- create-drop which drop the schema (if exists) and creates it
kundera.client.property optional, the name of the xml file containing the datastore specific properties.

in addition to the previous properties and in case of remote API, those properties are also necessary:

kundera.nodes required, url of the appengine application on which the datastore is located
kundera.port optional default: 443, port used to connect to datastore
kundera.username required, username of an admin on the remote server
kundera.password required, password of an admin on the remote server

To test against local appengine runtime emulator the configuration is as follow:

<property name="kundera.nodes" value="localhost"/>
<property name="kundera.port" value="8888"/>
<property name="kundera.username" value="username"/>
<property name="kundera.password""/>

the value for kundera.password does not matter.

####Datastore specific properties A file with client specific properties can be created and placed inside the classpath, you need to specify its name in the persistence.xml file.

the skeleton of the file is the following:

<?xml version="1.0" encoding="UTF-8"?>
<clientProperties>
    <datastores>
        <dataStore>
            <name>datastore</name>
            <connection>
                <properties>
                    <!-- list of properties -->
                    <property name="" value=""></property>
                </properties>
            </connection>
        </dataStore>
    </datastores>
</clientProperties>

for more information see kundera datastore specific properties.

The available properties are:

datastore.policy.read [eventual|strong] default: strong, set the read policy.
datastore.deadline optional, RPCs deadline in seconds.
datastore.policy.transaction [auto|none] default: none, define if use implicit transaction.

arci/kundera-gae-datastore