Java Data Objects (JDO)

The Apache JDO Team

+ @import url("./style/maven-theme.css");

The Apache JDO Team

The people listed below have made significant contributions to JDO by working long and hard to make quality software for the rest of the world to use. Modified: db/jdo/site/docs/transactions.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/transactions.html?rev=772590&r1=772589&r2=772590&view=diff ============================================================================== --- db/jdo/site/docs/transactions.html (original) +++ db/jdo/site/docs/transactions.html Thu May 7 10:25:02 2009 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - Transactions

Transactions

+ @import url("./style/maven-theme.css");

Transactions

When managing the persistence of objects using a PersistenceManager it is normal to handle all datastore operations in a transaction. For this reason each PersistenceManager has its own transaction. Consequently a typical JDO persistence method Modified: db/jdo/site/docs/why_jdo.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/why_jdo.html?rev=772590&r1=772589&r2=772590&view=diff ============================================================================== --- db/jdo/site/docs/why_jdo.html (original) +++ db/jdo/site/docs/why_jdo.html Thu May 7 10:25:02 2009 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - Why JDO ?

Why JDO ?

+ @import url("./style/maven-theme.css");

Why JDO ?

The majority of applications need to persist (or store) data during their lifecycle. There are many ways of doing this with an application written in Java.

JDO 2.0 : JPOX 1.1
JDO 2.1 : JPOX 1.2
JDO 2.2 : DataNucleus AccessPlatform 1.0.1
JDO 2.3 : DataNucleus AccessPlatform 1.1

@@ -60,7 +61,7 @@ DataNucleus Access Platform NonCommercial - 1.0, 2.0, 2.1, 2.2 + 1.0, 2.0, 2.1, 2.2, 2.3 RDBMS, db4o, LDAP, Excel, XML, NeoDatis, JSON, OpenDocumentFormat (ODF), Google BigTable Modified: db/jdo/site/xdocs/jdo_v_jpa_api.xml URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/jdo_v_jpa_api.xml?rev=772590&r1=772589&r2=772590&view=diff ============================================================================== --- db/jdo/site/xdocs/jdo_v_jpa_api.xml (original) +++ db/jdo/site/xdocs/jdo_v_jpa_api.xml Thu May 7 10:25:02 2009 @@ -47,6 +47,11 @@ em.refresh() + Detach single Object + pm.detachCopy() + em.detach() (JPA2) + + Flush changes pm.flush() em.flush() @@ -66,6 +71,11 @@ pm.newNamedQuery() em.createNamedQuery() + + New SQL Query + pm.newQuery() + em.createNativeQuery() + Added: db/jdo/site/xdocs/jdoql.xml URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/jdoql.xml?rev=772590&view=auto ============================================================================== --- db/jdo/site/xdocs/jdoql.xml (added) +++ db/jdo/site/xdocs/jdoql.xml Thu May 7 10:25:02 2009 @@ -0,0 +1,245 @@ + + + + JDO Object Retrieval + + + +

+ JDO defines ways of querying objects persisted into the datastore. It provides + its own object-based query language (JDOQL). JDOQL is designed as the Java + developers way of having the power of SQL queries, yet retaining the Java + object relationship that exist in their application model. + A typical JDOQL query may be set up in one of 2 ways. Here's an example +

+ +Declarative JDOQL : +Query q = pm.newQuery(mydomain.Person.class, "lastName == \"Jones\" && age < age_limit"); +q.declareParameters("double age_limit"); +List results = (List)q.execute(20.0); + +Single-String JDOQL : +Query q = pm.newQuery("SELECT FROM mydomain.Person WHERE lastName == \"Jones\"" + + " && age < :age_limit PARAMETERS double age_limit"); +List results = (List)q.execute(20.0); +

+ So here in our example we select all "Person" objects with surname of "Jones" + and where the persons age is below 20. The language is intuitive for Java + developers, and is intended as their interface to accessing the persisted + data model. As can be seen above, the query is made up of distinct parts. + The class being selected (the SELECT clause in SQL), the filter (which equates + to the WHERE clause in SQL), together with any sorting (the ORDER BY clause + in SQL), etc. +

+
+ + + +

+ In traditional (declarative) JDOQL (JDO 1.0) it was necessary to specify + the component parts (filter, candidate class, ordering, etc) of the query + using the mutator methods on the Query. In JDO 2 you can now specify it + all in a single string. This string has to follow a particular pattern, + but provides the convenience that many people have been asking for. + The pattern to use is as follows +

+ +SELECT [UNIQUE] [<result>] [INTO <result-class>] + [FROM <candidate-class> [EXCLUDE SUBCLASSES]] + [WHERE <filter>] + [VARIABLES <variable declarations>] + [PARAMETERS <parameter declarations>] + [<import declarations>] + [GROUP BY <grouping>] + [ORDER BY <ordering>] + [RANGE <start>, <end>] +

+ The "keywords" in the query are shown in UPPER CASE but can be in + UPPER or lower case. +

+ Lets give an example of a query using this syntax +

+SELECT UNIQUE FROM org.datanucleus.samples.Employee ORDER BY departmentNumber +

+ so we form the parts of the query as before, yet here we just specify it + all in a single call. +

+ + + +

+ In JDOQL you access fields in the query by referring to the field name. + For example, if you are querying a class called Product and it has + a field "price", then you access it like this +

+ +Query query = pm.newQuery(mydomain.Product.class, "price < 150.0"); +

+ In addition to the persistent fields, you can also access + "public static final" fields of any class. You can do this as follows +

+ +Query query = pm.newQuery(mydomain.Product.class, + "taxPercent < mydomain.Product.TAX_BAND_A"); +

+ So this will find all products that include a tax percentage less than + some "BAND A" level. Where you are using "public static final" fields you + can either fully-qualify the class name or you can include it in the + "imports" section of the query (see later). +

+ + + +

+ JDOQL supports the following literals: IntegerLiteral, + FloatingPointLiteral, BooleanLiteral, CharacterLiteral, StringLiteral, + and NullLiteral. +

+ + + +

+ The following list describes the operator precedence in JDOQL. +

Cast
Unary ("~") ("!")
Unary ("+") ("-")
Multiplicative ("*") ("/") ("%")
Additive ("+") ("-")
Relational (">=") (">") ("<=") ("<") ("instanceof")
Equality ("==") ("=!")
Boolean logical AND ("&")
Boolean logical OR ("|")
Conditional AND ("&&")
Conditional OR ("||")

+ + + +

+ The concatenation operator(+) concatenates a String to either another + String or Number. Concatenations of String or Numbers to null results in + null. +

+ + + +

+ Here's a simple example for finding the elements of a class with a field + below a particular threshold level. Here we pass in the threshold value + (limit), and sort the output in order of ascending price. +

+ +Declarative JDOQL : +Query query = pm.newQuery(mydomain.Product.class,"price < limit"); +query.declareParameters("double limit"); +query.setOrdering("price ascending"); +List results = (List)query.execute(150.00); + +Single-String JDOQL : +Query query = pm.newQuery("SELECT FROM mydomain.Product WHERE " + + "price < limit PARAMETERS double limit ORDER BY price ASCENDING"); +List results = (List)query.execute(150.00); +

+ For completeness, the class is shown here +

+ + + + + + + + + + + + + +]]> +
+ + + +

+ Let's repeat the previous query but this time using implicit + parameters. +

+ +Declarative JDOQL : +Query query = pm.newQuery(mydomain.Product.class,"price < :limit"); +query.setOrdering("price ascending"); +List results = (List)query.execute(150.00); + +Single-String JDOQL : +Query query = pm.newQuery("SELECT FROM mydomain.Product WHERE " + + "price < :limit ORDER BY price ASCENDING"); +List results = (List)query.execute(150.00); +

+ So we omitted the declaration of the parameter and just prefixed it with + a colon (:) +

+
+ + + +

+ Here's another example using the same Product class as above, but this + time comparing to a Date field. Because we are using a type in our query, + we need to import it ... + just like you would in a Java class if you were using it there. +

+ +Declarative JDOQL : +Query query = pm.newQuery(domain.Product.class, + "endDate > best_before_limit"); +query.declareImports("import java.util.Date"); +query.declareParameters("Date best_before_limit"); +query.setOrdering("endDate descending"); +Collection results = (Collection)query.execute(my_date_limit); + +Single-String JDOQL : +Query query = pm.newQuery("SELECT FROM mydomain.Product " + + "WHERE endDate > best_before_limit " + + "PARAMETERS Date best_before_limit " + + "import java.util.Date ORDER BY endDate DESC"); +List results = (List)query.execute(my_date_limit); +
+ + + +

+ This example demonstrates use of the "instanceof" operator. We have a + class A that has a field "b" of type B and B has subclasses B1, B2, B3. + Clearly the field "b" of A can be of type B, B1, B2, B3 etc, and we want + to find all objects of type A that have the field "b" that is of type B2. + We do it like this +

+ +Declarative JDOQL : +Query query = pm.newQuery(mydomain.A.class); +query.setFilter("b instanceof mydomain.B2"); +List results = (List)query.execute(); + +Single-String JDOQL : +Query query = pm.newQuery("SELECT FROM mydomain.A WHERE b instanceof mydomain.B2"); +List results = (List)query.execute(); + +

+ + + Modified: db/jdo/site/xdocs/navigation.xml URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/navigation.xml?rev=772590&r1=772589&r2=772590&view=diff ============================================================================== --- db/jdo/site/xdocs/navigation.xml (original) +++ db/jdo/site/xdocs/navigation.xml Thu May 7 10:25:02 2009 @@ -35,6 +35,7 @@ + Modified: db/jdo/site/xdocs/object_retrieval.xml URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/object_retrieval.xml?rev=772590&r1=772589&r2=772590&view=diff ============================================================================== --- db/jdo/site/xdocs/object_retrieval.xml (original) +++ db/jdo/site/xdocs/object_retrieval.xml Thu May 7 10:25:02 2009 @@ -7,26 +7,30 @@

- JDO provides persistence of objects. The logical next step after persisting objects is to retrieve them - for use in your application. There are several ways to do this + JDO provides persistence of objects. The logical next step after persisting + objects is to retrieve them for use in your application. + There are several ways to do this

- The simplest form of object retrieval is where we have the identity. This is simply + The simplest form of object retrieval is where we have the identity. + This is simply

Object obj = pm.getObjectById(identity);

- If the object is in the JDO cache then it is retrieved from there, otherwise the JDO implementation - goes to the datastore. When the object is retrieved its fields are populated according to its Fetch Group. + If the object is in the JDO cache then it is retrieved from there, + otherwise the JDO implementation goes to the datastore. When the object + is retrieved its fields are populated according to its Fetch Group.

- A persistable class can be persisted with an Extent of all instances of that type. + A persistable class can be persisted with an Extent of all + instances of that type. You can use this to retrieve objects of the required type, like this

@@ -38,21 +42,23 @@ ... }

- The second argument in the getExtent call is whether to include instances of subclasses. + The second argument in the getExtent call is whether to include + instances of subclasses.

- Where we want to retrieve all objects based on some criteria (e.g all objects of class A where - field 'x' of A is a certain value) we need to use a query language. JDO2 provides 2 options here. - JDOQL is object-based and allows you to express your query in terms of the classes and fields - you are using. SQL is datastore-based and allows you to express your query in terms of the - datastore tables and columns. + Where we want to retrieve all objects based on some criteria (e.g all + objects of class A where field 'x' of A is a certain value) we need to + use a query language. JDO2 provides 2 options here. JDOQL is object-based + and allows you to express your query in terms of the classes and fields + you are using. SQL is datastore-based and allows you to express your query + in terms of the datastore tables and columns.

- To give an exmaple of a JDOQL query + To give an example of a JDOQL query

- If the objects found by the query are in the JDO cache then they are retrieved from there, otherwise the - JDO implementation goes to the datastore. When the objects are retrieved their fields are populated according to the Fetch Group. + If the objects found by the query are in the JDO cache then they are + retrieved from there, otherwise the JDO implementation goes to the + datastore. When the objects are retrieved their fields are populated + according to the Fetch Group.

General

JDO Implementation

JDO Usage

Community

Development

The Apache JDO Team

General

JDO Implementation

JDO Usage

Community

Development

The Apache JDO Team

General

JDO Implementation

JDO Usage

Community

Development

Transactions

General

JDO Implementation

JDO Usage

Community

Development

Transactions

General

JDO Implementation

JDO Usage

Community

Development

Why JDO ?

General

JDO Implementation

JDO Usage

Community

Development

Why JDO ?