You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@aries.apache.org by bu...@apache.org on 2011/03/07 18:51:09 UTC
svn commit: r786620 -
/websites/staging/aries/trunk/content/modules/jpaproject.html
Author: buildbot
Date: Mon Mar 7 17:51:09 2011
New Revision: 786620
Log:
Staging update by buildbot
Modified:
websites/staging/aries/trunk/content/modules/jpaproject.html
Modified: websites/staging/aries/trunk/content/modules/jpaproject.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/jpaproject.html (original)
+++ websites/staging/aries/trunk/content/modules/jpaproject.html Mon Mar 7 17:51:09 2011
@@ -242,7 +242,125 @@ persistence for the Blueprint container.
<p>For more information, check out section "127 JPA Service Specification
Version 1.0" in the "OSGi Service Platform Enterprise Specification,
Release 4, Version 4.2" available for public download from the <a href="http://www.osgi.org/Download/Release4V42">OSGi Alliance</a>
-.</p></div>
+.</p>
+<p>Developing an Aries JPA project is very easy and can be achieved with simple steps described hereafter.</p>
+<h1 id="maven_project_creation">Maven Project Creation</h1>
+<p>The first step consist in to create a maven module and make the following modifications to allow to deploy
+ it as OSGI bundle on the platform and reference where the persistence XML file must loaded by the classpath to
+ allow to the JPA container to configure the project accordingly.</p>
+<p>Step 1 : Module</p>
+<p>Every jar deployed on an OSGI platform must be adapted to be conform to OSGI standard. That means that the maven
+packaging which is defined as the default value must be defined to bundle</p>
+<p>{code}
+ <groupId>org.apache.aries.samples.blog</groupId>
+ <artifactId>org.apache.aries.samples.blog.persistence.jpa</artifactId>
+ <name>Apache Aries blog sample persistence</name>
+ <packaging>bundle</packaging>
+{code} </p>
+<p>and that you must configure the maven-bundle-plugin (http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html)
+to generate the MANIFEST.MF file required by OSGI platform.</p>
+<p>Remark : the modification to be made (packages to be imported or exported depends on your project setting)</p>
+<p>{code}
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <configuration>
+ <instructions>
+ <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
+ <Private-Package>org.apache.aries.samples.blog.persistence.jpa.<em></Private-Package>
+ <Export-Package>!org.apache.aries.samples.blog.persistence.jpa.</em></Export-Package>
+ </instructions>
+ </configuration>
+ </plugin>
+{code}</p>
+<p>To allow the Aries JPA Container to setup your persistence layer (akka : instantiate the entityFactory with the information
+provided into the persistence.xml file), an additional modification must be made in your pom.xml file to package this file
+into the META-INF directory</p>
+<p>{code}
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <configuration>
+ <instructions>
+ <Meta-Persistence>META-INF/persistence.xml</Meta-Persistence>
+ ...
+ </instructions>
+ </configuration>
+ </plugin>
+{code}</p>
+<p>When this step is done, your pom.xml file is ready to be used to package and install your bundle into the maven repository
+and next into a OSGI container (Apache Felix, Apache Karaf, Eclipse Equinox)</p>
+<p>Step 2 : Adapt the persistence file</p>
+<p>We will not cover how to define the different parameters of the persistence file but present you what you should modify to
+deploy it on non J2EE platform, which is the case by definition for OSGI kernel. Curiously, there is only one think
+to modify and it concerns the access to the datasource. In J2EE world, we use JNDI as registry mecahnism to registry
+the datasource with a key used to find it from applications. JNDI is not supported like that in OSGI world but OSGI EE
+specification has made a proposition to provide a similar mechanism that Aries JNDI project covers (http://aries.apache.org/modules/jndiproject.html).</p>
+<p>To access to the datasource, you must provide within the <jta-data-source> or <non-jta-data-source> depending if you use a JTA
+transaction manager or not.</p>
+<p>{code}
+ <persistence-unit name="ReportIncident" transaction-type="JTA">
+ <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider></p>
+<div class="codehilite"><pre> <span class="nt"><jta-data-source></span>osgi:service/javax.sql.DataSource/(osgi.jndi.service.name=jdbc/reportincidentdb)<span class="nt"></jta-data-source></span>
+</pre></div>
+
+
+<p>{code}</p>
+<p>With J2EE applications, you simply use the jdbc key with the name of the datasource associated (jdbc/reportincidentdb). As OSGI uses a
+ different mechanism, we must define two parameters, the "osgi:service" wich will allow to find from the OSGI Service registry (aka proxy)
+ the interface "javax.sql.DataSource" and the name of the service "osgi.jndi.service.name", which is a filter property, with its jndi name associated.</p>
+<p>The other tags of the xml file are defined according to JPA specification</p>
+<p>Step 3 : Define the services and expose them</p>
+<p>The last step consist in to use Annotations and Injection mechanism to let the Aries JPA container to create the entity Manager
+with the classes of your DAO layer and add Transactional aspect into the methods. This way of work allows to complety
+embed existing projects into ARIES sphere without modifications</p>
+<p>Here are the modifications to do in the blueprint xml file located under OSGI-INF/blueprint</p>
+<p>{code}
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0"
+ xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0"
+ default-activation="lazy"></p>
+<div class="codehilite"><pre><span class="nt"><bean</span> <span class="na">id=</span><span class="s">"incidentDAO"</span>
+ <span class="na">class=</span><span class="s">"org.apache.camel.example.reportincident.dao.impl.IncidentDAOImpl"</span><span class="nt">></span>
+ <span class="nt"><tx:transaction</span> <span class="na">method=</span><span class="s">"*"</span> <span class="na">value=</span><span class="s">"Required"</span> <span class="nt">/></span> (1)
+ <span class="nt"><jpa:context</span> <span class="na">property=</span><span class="s">"entityManager"</span> <span class="na">unitname=</span><span class="s">"ReportIncident"</span> <span class="nt">/></span> (2)
+<span class="nt"></bean></span>
+
+<span class="nt"><service</span> <span class="na">ref=</span><span class="s">"incidentDAO"</span>
+ <span class="na">interface=</span><span class="s">"org.apache.camel.example.reportincident.dao.IncidentDAO"</span><span class="nt">></span>
+<span class="nt"></service></span>
+
+<span class="c"><!-- DataSource Derby --></span>
+<span class="nt"><bean</span> <span class="na">id=</span><span class="s">"dataSourceDerby"</span> <span class="na">class=</span><span class="s">"org.apache.commons.dbcp.BasicDataSource"</span> <span class="na">destroy-method=</span><span class="s">"close"</span><span class="nt">></span>
+ <span class="nt"><property</span> <span class="na">name=</span><span class="s">"driverClassName"</span> <span class="na">value=</span><span class="s">"org.apache.derby.jdbc.EmbeddedDriver"</span> <span class="nt">/></span>
+ <span class="nt"><property</span> <span class="na">name=</span><span class="s">"url"</span> <span class="na">value=</span><span class="s">"jdbc:derby:/temp/reportincident;create=true"</span> <span class="nt">/></span>
+ <span class="nt"><property</span> <span class="na">name=</span><span class="s">"username"</span> <span class="na">value=</span><span class="s">""</span> <span class="nt">/></span>
+ <span class="nt"><property</span> <span class="na">name=</span><span class="s">"password"</span> <span class="na">value=</span><span class="s">""</span> <span class="nt">/></span>
+<span class="nt"></bean></span>
+
+<span class="c"><!-- Expose DataSource as JNDI reference --></span>
+<span class="nt"><service</span> <span class="na">ref=</span><span class="s">"dataSourceDerby"</span> <span class="na">interface=</span><span class="s">"javax.sql.DataSource"</span><span class="nt">></span>
+ <span class="nt"><service-properties></span>
+ <span class="nt"><entry</span> <span class="na">key=</span><span class="s">"osgi.jndi.service.name"</span> <span class="na">value=</span><span class="s">"jdbc/reportincidentdb"</span><span class="nt">/></span> (3)
+ <span class="nt"></service-properties></span>
+<span class="nt"></service></span>
+</pre></div>
+
+
+<p></blueprint>
+{code}</p>
+<p>(1) The <tx:transaction> tag allows to inject in your DAO layer the transactional aspect and using the following symbol
+"*", Aries Transaction manager will create for each method a session to begin / commit or rollback a transaction in your class
+The scope of the transaction can be defined using the attribute value.
+(2) The JPA context is created using <jpa:context>. The entityManager (which corresponds to the property of your DAO class) will be
+injected using the property="entityManager". The reference to your unit name (defined in the persistence.xml file) is passed with the
+ attribute unitname.
+file.
+(3) The <service> allows to expose an interface on the OSGI Registry Service using as key the name of the interface ("javax,sql.Datasource").
+The <service-properties> will let to define a property that we will use to retrieve the datasource from the registry</p>
+<p>Step 4 : Package the solution</p>
+<p>To package and deploy the solution, execute a "maven clean install" instruction and deploy your project on you OSGI platform</p></div>
<!-- Content -->
</td>
</tr>