The Persistence Manager API

- When you have created a new - Persistence Manager in your application, you can use this +

+ +

+ When you have created a new + Object Content Manager in your application, you can use this component to insert, update, delete and retrieve objects. The class 'Folder' used in the following sections should be - associated to a class-descriptor defined in the mapping descriptor. + associated to a class-descriptor defined in the mapping descriptor.

- This page describes only the main Persistence Manager methods. + This page describes only the main Object Content Manager methods. You can see the javadoc to get more information on the API.

- + Folder folder = new Folder(); folder.setPath("/myfolder"); folder.set...(); // call the setter methods -persistenceManager.insert(myFolder); +ocm.insert(myFolder); -Folder folder = (Folder) persistenceManager.getObject(Folder.class, "/myfolder"); +Folder folder = (Folder) ocm.getObject("/myfolder"); folder.set...(); // call the setter methods -persistenceManager.update(myFolder); +ocm.update(myFolder); -persistenceManager.remove("/test"); +ocm.remove("/test"); - +

After some inserts, deletes and/or updates, you can call - the method persistenceManager.save() to apply your + the method ocm.save() to apply your changes into the JCR repository.

+ With Jackrabbit, it is also possible to run the modifications inside a transaction. + See the class org.apache.jackrabbit.ocm.transaction.jackrabbit.UserTransactionImpl defined in the unit tests. + +import javax.transaction.UserTransaction; +import org.apache.jackrabbit.ocm.transaction.jackrabbit.UserTransactionImpl; + +UserTransaction utx = new UserTransactionImpl(session); + +// start transaction +utx.begin(); + +ocm.remove("/test"); +ocm.remove("/test2"); + +utx.commit(); + +

Modified: jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/locking.xml URL: http://svn.apache.org/viewvc/jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/locking.xml?rev=616072&r1=616071&r2=616072&view=diff ============================================================================== --- jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/locking.xml (original) +++ jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/locking.xml Mon Jan 28 13:57:02 2008 @@ -20,11 +20,11 @@ Christophe Lombart - The Persistence Manager API + The Object Content Manager API -

- +

Following the Jcr specification, it is possible to lock nodes and their children (see section 8.4). You can see on this page the @@ -67,14 +67,14 @@ a.setCollection(collection); -persistenceManager.insert(a); -persistenceManager.save(); +ocm.insert(a); +ocm.save(); // -------------------------------------------------------------------------------- // Check if the object is not locked // -------------------------------------------------------------------------------- -if (persistenceManager.isLocked("/test")) +if (ocm.isLocked("/test")) { System.out.println("Error : The object is locked- humm ??"); } @@ -82,12 +82,12 @@ // -------------------------------------------------------------------------------- // Lock the object // -------------------------------------------------------------------------------- -String lockToken = persistenceManager.lock("/test", true, false); +String lockToken = ocm.lock("/test", true, false); // -------------------------------------------------------------------------------- // Check if the object is not locked // -------------------------------------------------------------------------------- -if (! persistenceManager.isLocked("/test")) +if (! ocm.isLocked("/test")) { System.out.println("Error : The object is not locked- humm ??"); } @@ -95,7 +95,7 @@ // -------------------------------------------------------------------------------- // Unlock the object // -------------------------------------------------------------------------------- -persistenceManager.unlock("/test", lockToken); +ocm.unlock("/test", lockToken);

Modified: jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/search.xml URL: http://svn.apache.org/viewvc/jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/search.xml?rev=616072&r1=616071&r2=616072&view=diff ============================================================================== --- jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/search.xml (original) +++ jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/search.xml Mon Jan 28 13:57:02 2008 @@ -18,10 +18,10 @@ Christophe Lombart - The Persistence Manager API + The Object Content Manager API -

QueryManager queryManager = persistenceManager.getQueryManager(); @@ -32,7 +32,7 @@ // Build the query Query query = queryManager.createQuery(filter); -Paragraph paragraph = (Paragraph) persistenceManager.getObject(query); +Paragraph paragraph = (Paragraph) ocm.getObject(query); @@ -42,8 +42,8 @@ Filter filter = queryManager.createFilter(Paragraph.class); filter.setScope("/test/node1//"); Query query = queryManager.createQuery(filter); -persistenceManager = this.getPersistenceManager(); -Collection result = persistenceManager.getObjects(query); + +Collection result = ocm.getObjects(query); @@ -53,8 +53,8 @@ Filter filter = queryManager.createFilter(Paragraph.class); filter.setScope("/test/node1//"); Query query = queryManager.createQuery(filter); -persistenceManager = this.getPersistenceManager(); -Iterator ierator = persistenceManager.getObjectIterator(query); + +Iterator ierator = ocm.getObjectIterator(query); @@ -64,8 +64,8 @@ Filter filter = queryManager.createFilter(Paragraph.class); filter.setScope("/test/node1//"); Query query = queryManager.createQuery(filter); -persistenceManager = this.getPersistenceManager(); -persistenceManager.remove(query); + +ocm.remove(query);

Modified: jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/versionning.xml URL: http://svn.apache.org/viewvc/jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/versionning.xml?rev=616072&r1=616071&r2=616072&view=diff ============================================================================== --- jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/versionning.xml (original) +++ jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/api/versionning.xml Mon Jan 28 13:57:02 2008 @@ -20,11 +20,11 @@ Christophe Lombart - The Persistence Manager API + The Object Content Manager API -

- +

Right now, the OCM tools provides basic versioning features:

@@ -52,28 +52,28 @@ page.setTitle("Page Title"); page.addParagraph(new Paragraph("para1")); page.addParagraph(new Paragraph("para2")); -persistenceManager.insert(page); -persistenceManager.save(); +ocm.insert(page); +ocm.save(); // Update the page object and create a new version page.addParagraph(new Paragraph("para3")); -persistenceManager.checkout("/page"); -persistenceManager.update(page); -persistenceManager.save(); -persistenceManager.checkin("/page"); +ocm.checkout("/page"); +ocm.update(page); +ocm.save(); +ocm.checkin("/page"); // Update the page object and create a new version page.addParagraph(new Paragraph("para4")); -persistenceManager.checkout("/page"); -persistenceManager.update(page); -persistenceManager.save(); -persistenceManager.checkin("/page"); +ocm.checkout("/page"); +ocm.update(page); +ocm.save(); +ocm.checkin("/page"); -VersionIterator versionIterator = persistenceManager.getAllVersions("/page"); +VersionIterator versionIterator = ocm.getAllVersions("/page"); while (versionIterator.hasNext()) { Version version = (Version) versionIterator.next(); @@ -86,11 +86,11 @@ // Retrieve the first version description -Version baseVersion = persistenceManager.getBaseVersion("/page"); +Version baseVersion = ocm.getBaseVersion("/page"); System.out.println("Base version : " + baseVersion.getName()); // Retrieve the latest version description -Version rootVersion = persistenceManager.getRootVersion("/page"); +Version rootVersion = ocm.getRootVersion("/page"); System.out.println("Root version : " + rootVersion.getName()); @@ -98,7 +98,7 @@ //Get the object matching to the first version -Page page = (Page) persistenceManager.getObject( "/page", "1.0"); +Page page = (Page) ocm.getObject( "/page", "1.0"); @@ -109,29 +109,29 @@ page.setTitle("Page Title"); page.addParagraph(new Paragraph("para1")); page.addParagraph(new Paragraph("para2")); -persistenceManager.insert(page); -persistenceManager.save(); +ocm.insert(page); +ocm.save(); // Checkin with some labels page.addParagraph(new Paragraph("para3")); -persistenceManager.checkout("/page"); -persistenceManager.update(page); -persistenceManager.save(); -persistenceManager.checkin("/page", new String[] {"A", "B"}); +ocm.checkout("/page"); +ocm.update(page); +ocm.save(); +ocm.checkin("/page", new String[] {"A", "B"}); // Checkin with some labels page.addParagraph(new Paragraph("para4")); -persistenceManager.checkout("/page"); -persistenceManager.update(page); -persistenceManager.save(); -persistenceManager.checkin("/page", new String[] {"C", "D"}); +ocm.checkout("/page"); +ocm.update(page); +ocm.save(); +ocm.checkin("/page", new String[] {"C", "D"}); // Retrieve all labels -String[] allLabels = persistenceManager.getAllVersionLabels("/page"); +String[] allLabels = ocm.getAllVersionLabels("/page"); assertTrue("Incorrect number of labels", allLabels.length == 4); // Retrieve labels assigned to the version 1.1 -String[] versionLabels = persistenceManager.getVersionLabels("/page", "1.1"); +String[] versionLabels = ocm.getVersionLabels("/page", "1.1"); assertTrue("Incorrect number of labels", versionLabels.length == 2); assertTrue("Incorrect label", versionLabels[0].equals("C") || versionLabels[0].equals("D")); assertTrue("Incorrect label", versionLabels[1].equals("C") || versionLabels[0].equals("D")); Modified: jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/engine-introduction.xml URL: http://svn.apache.org/viewvc/jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/engine-introduction.xml?rev=616072&r1=616071&r2=616072&view=diff ============================================================================== --- jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/engine-introduction.xml (original) +++ jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/engine-introduction.xml Mon Jan 28 13:57:02 2008 @@ -18,39 +18,43 @@ Christophe Lombart - OCM: Object Manager + Jackrabbit OCM : the Object Content Manager -

- The main component in the OCM framework is the Object Manager. - It converts an object graph into JCR nodes and properties and - vice versa. The object manager is always associated with a - JCR Session. Usually there is one object manager per user session, - but depending on your needs you can use any number of object managers - in your application. + The main component in the OCM framework is the ObjectContentManager. It converts an object graph into JCR nodes and properties and vice versa. The ObjectContentManager is always associated with a JCR Session. It is used to retrieve, create, update and delete objects from a JCR content repository. Usually there is one ObjectContentManager per user session.

- This page describes the how object managers work and how you can - configure and use them in your applications. + This page describes how an ObjectManager is working and how it can be initialised in your applications.

- - -

- Thanks to a Mapping Descriptor file described below, - the Object Manager is able to use the more appropriate mapping - strategy for each object. The Mapping Descriptor file contains - one class descriptor per persistent class. Each class descriptor - contains mapping information for the corresponding class attributes. -

- In all cases, the desired persistent class is mapped to a JCR node - and its fields are mapped to subnodes or properties depending on - their type (see below). -

+ +

- There are 4 "field types": + Thanks to a Mapping Descriptor, the ObjectContentManager is able to use the appropriate mapping strategy for each persistent object (pojo). The Mapping Descriptor contains one Class Descriptor per persistent class. Each Class Descriptor contains mapping information for the corresponding class attributes.

+ In point of view implementation, the Mappring Descriptor is an java object injected into the ObjectContentManager (see the interface org.apache.jackrabbit.ocm.mapper.Mapper). Right now,there are 2 different Mapping Descriptor implementations: +

+ Annotation : each persistent object is annoted in order to provide to the ObjectContentManager all the required information on its mapping strategy (see the class org.apache.jackrabbit.ocm.mapper.impl.annotation.AnnotationMapperImpl). +
+ XML configuration file : the mapping class descriptors are defined in one or more XML config files used by the ObjectContentManager when it is instantiated (see the class org.apache.jackrabbit.ocm.mapper.impl.digester.DigesterMapperImpl). This XML file contains the different class descriptors. +

For a business developer, it is not necessary to know how the ObjectContent Manager is using the Class Descriptors. He has to make only a choice between annoted classes or one or more XML files.

+ + +

+ In all cases, a persistent object (a pojo) is mapped into a JCR node and its fields are mapped into subnodes or properties depending on their types. +

+ There are 4 "field types": +

Atomic fields: @@ -60,65 +64,58 @@
Bean fields: One class can contain an 1..1 association to another bean. - In this case, the attribute is a custom object. Those fields - are mapped into JCR subnodes. + In this case, the field is a custom object. Those fields + are mapped into JCR subnodes or a referenced node.
Collection fields: One class can contain an 1..n association to a collection of beans (or Map). Those fields are mapped into a collection of - JCR subnodes. -
Reference fields: - One good example to understand the "reference" type is the - Folder concept. A folder "B" can have an attribute called - "parentFolder" which is a simple field pointing to the parent - folder "A". Of course, in a JCR repository, it is a nonsense - for persist this "parentFolder" attribute into a "B" subnode. - Another interesting example are references between cms objects - (folders, documents, ...). This type is not yet implemented. + JCR subnodes or a collection of referenced nodes. It is also possible to map a java collection into a multivalue property.

- Of course, all those "field types" imply different mapping - algorithms. -

- The descriptor file contains also information on - inheritance/interface mapping strategy, lazy loading, + The Mapping descriptor contains also information on inheritances, interface mapping strategy, lazy loading, custom converter, cache strategy, etc.

- -

- The mapping descriptor is an xml file with the following structure: -

- - - ... - - ... - -]]> -

- The root element is "jackrabbit-ocm" and it contains one or more - "class-descriptor". As you can see in the - Mapping Strategies - section, each class-descriptor contains the mapping information - used for each class attribute. -

- It is possible to have several mapping descriptor files. -

+ + +

+ When you start your application, you need the following code + to initialize correctly the Object Content Manager. +

+ +import javax.jcr.Session; +import javax.jcr.Repository; + +import org.apache.jackrabbit.ocm.manager.impl.ObjectContentManagerImpl; +import org.apache.jackrabbit.ocm.mapper.Mapper; +import org.apache.jackrabbit.ocm.mapper.impl.annotation.AnnotationMapperImpl; + + +// 1. Instantiate a JCR session +Repository repository = ...; +Session session = repository.login(...); + +// 2. Register the different persistent classes +List classes = new ArrayList(); +classes.add(MyContent.class); // Call this method for each persistent class + + +// 3. Instantiate the object manager +Mapper mapper = new AnnotationMapperImpl(classes); +ocm = new ObjectContentManagerImpl(session, mapper); + + + - +

When you start your application, you need the following code - to initialize correctly the Object Manager. + to initialize correctly the Object Content Manager.

import javax.jcr.Session; @@ -146,18 +143,9 @@ "./src/test-config/jcrmapping-beandescriptor.xml" }; -// 3. Initialize the PersistenceManager dependencies -Mapper mapper = new DigesterMapperImpl(files).buildMapper(); -AtomicTypeConverterProvider converterProvider = - new DefaultAtomicTypeConverterProvider(); -Map atomicTypeConverters = converterProvider.getAtomicTypeConverters(); -QueryManager queryManager = new QueryManagerImpl(mapper, atomicTypeConverters); -ObjectConverter objectConverter = - new ObjectConverterImpl(mapper, converterProvider); - -// 4. Instantiate the object manager -ObjectContentManager manager = - new ObjectContentManagerImpl(mapper, objectConverter, queryManager, session); +// 3. Instantiate the object manager +ObjectContentManager ocm = new ObjectContentManagerImpl(session, files); + Modified: jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/index.xml URL: http://svn.apache.org/viewvc/jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/index.xml?rev=616072&r1=616071&r2=616072&view=diff ============================================================================== --- jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/index.xml (original) +++ jackrabbit/trunk/jackrabbit-site/src/site/xdoc/ocm/index.xml Mon Jan 28 13:57:02 2008 @@ -19,34 +19,23 @@ Christophe Lombart - Jackrabbit Object/Content Mapping (OCM) + Jackrabbit OCM : oveview -

- -

- This subproject is an object/JCR persistence and query service. - This tools lets you to persist Java objects into a JCR compliant - repository - including association, inheritance, polymorphism, - composition, and the Java collections framework. Furthermore, - this OCM component allows you to express queries in Java-based - criteria, as well as in JCR query language. It offers also - features like version support and object locking. +

+ +

+ Jackrabbit OCM is a framework used to persist java objects (pojos) in a JCR repository including association, inheritance, polymorphism, composition, and the Java collections framework. It offers also features like version support, object locking and express queries with Java-based criteria, as well as with JCR query languages.

+ In order to easily support the JCR specification, any content application managing an high level object model can use this framework. For example, a classic Forum application contains objects like "Forum", "Topic" and "Post". Now, Jackrabbit OCM can manage these pojos and persist them into a JCR compliant repository.

- In order to easily support the JCR specification, any content - application managing an high level object model can use this - framework. For example, a classic Forum application contains - objects like "Forum", "Topic" and "Post". Now, the data objects - (pojo) can be managed by our JCR mapping tools in order to persist - them into a JCR compliant repository. +

- The object content mapping framework was created for the following - different reasons: + The object content mapping framework was created for the following reasons: