Author: sclassen
Date: Tue May 6 09:07:14 2014
New Revision: 1592691
URL: http://svn.apache.org/r1592691
Log:
onami-persist: added site pages
Added:
onami/sandbox/persist/src/site/apt/
onami/sandbox/persist/src/site/apt/daoExample.apt.vm (with props)
onami/sandbox/persist/src/site/apt/emProvider.apt.vm (with props)
onami/sandbox/persist/src/site/apt/guicePersist.apt.vm (with props)
onami/sandbox/persist/src/site/apt/index.apt.vm (with props)
onami/sandbox/persist/src/site/apt/simpleWebApp.apt.vm (with props)
onami/sandbox/persist/src/site/apt/standaloneApp.apt.vm (with props)
Added: onami/sandbox/persist/src/site/apt/daoExample.apt.vm
URL:
http://svn.apache.org/viewvc/onami/sandbox/persist/src/site/apt/daoExample.apt.vm?rev=1592691&view=auto
==============================================================================
--- onami/sandbox/persist/src/site/apt/daoExample.apt.vm (added)
+++ onami/sandbox/persist/src/site/apt/daoExample.apt.vm Tue May 6 09:07:14
2014
@@ -0,0 +1,51 @@
+ ------
+ DAO Example
+ ------
+ The Apache Onami developers team
+ ------
+ 2014
+
+~~
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+~~
+
+DAO Example
+
+ The following code snippet is a little example on how to use Onami-Persist
to access a persistence unit.
+
++--------------------------------------+
+public class FooDao {
+
+ private final EntityManagerProvider emProvider;
+
+ @Inject
+ public FooDao(EntityManagerProvider emProvider) {
+ this.emProvider = emProvider;
+ }
+
+ @Transactional
+ public Foo getFooByName(String name) {
+ final EntityManager em = emProvider.get();
+ return getFooByName(name, em);
+ }
+
+ private Foo getFooByName(String name, EntityManager em) {
+ // retrieve foo from the DB using the entity manager...
+ }
+}
++--------------------------------------+
Propchange: onami/sandbox/persist/src/site/apt/daoExample.apt.vm
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: onami/sandbox/persist/src/site/apt/daoExample.apt.vm
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: onami/sandbox/persist/src/site/apt/daoExample.apt.vm
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: onami/sandbox/persist/src/site/apt/emProvider.apt.vm
URL:
http://svn.apache.org/viewvc/onami/sandbox/persist/src/site/apt/emProvider.apt.vm?rev=1592691&view=auto
==============================================================================
--- onami/sandbox/persist/src/site/apt/emProvider.apt.vm (added)
+++ onami/sandbox/persist/src/site/apt/emProvider.apt.vm Tue May 6 09:07:14
2014
@@ -0,0 +1,86 @@
+ ------
+ EntityManagerProvider vs. Provider of
EntityManager
+ ------
+ The Apache Onami developers team
+ ------
+ 2014
+
+~~
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+~~
+
+EntityManagerProvider vs. Provider of EntityManager
+
+ In guice-persist the EntityManager is bound in the injector allowing to
directly inject an EntityManager into your
+ classes. This causes for a lot of problems since the EntityManager has a
life cycle. When a unit of work is started
+ a new EntityManager instance is created. The thread which started the unit
of work must use this instance and this
+ instance alone to interact with the persistence unit. When the unit of work
is ended the EntityManager is closed.
+ This ends the life cycle of the EntityManager. All calls to the closed
instance will result in an Exception
+ (except isClosed() ).
+
+ People not familiar with the life cycle of the EntityManager tend to build a
DAO or service like this:
+
++--------------------------------------+
+public class ExampleService {
+
+ private final EntityManager em;
+
+ @Inject
+ public ExamleService(EntityManager em) {
+ this.em = em;
+ }
+
+ @Transactional
+ public Foo getFooByName(String name) {
+ // retrieve foo from the DB using the EntityManager.
+ }
+}
++--------------------------------------+
+
+ The above implementation will always use the very same EntityManager for all
threads and all calls to its methods.
+ This won't work. To make it more obvious that the EntityManager should not
be injected into a class guice-jpa does
+ not bind the EntityManager. Instead it binds an EntityManagerProvider. The
EntityManagerProvider has only one method
+ get() which returns the EntityManager. This EntityManager should be used by
the calling thread to access the
+ persistence unit.
+
+ If you need the EntityManager to be bound in the injector you can do this as
follows:
+
++--------------------------------------+
+public class MyPersistenceModule extends PersistenceModule {
+
+ @Override
+ protected void configurePersistence() {
+
addApplicationManagedPersistenceUnit("main").annotatedWith(MainPU.class);
+
+
bind(EntityManager.class).annotatedWith(MainPU.class).toProvider(MainEntityManagerExposingProvider.class);
+ }
+}
+
+public class MainEntityManagerExposingProvider implements
Provider<EntityManager> {
+ private final EntityManagerProvider emProvider;
+
+ @Inject
+ public MainEntityManagerExposingProvider(@MainPU EntityManagerProvider
emProvider) {
+ this.emProvider = emProvider;
+ }
+
+ public EntityManager get() {
+ ret emProvider.get();
+ }
+}
++--------------------------------------+
Propchange: onami/sandbox/persist/src/site/apt/emProvider.apt.vm
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: onami/sandbox/persist/src/site/apt/emProvider.apt.vm
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: onami/sandbox/persist/src/site/apt/emProvider.apt.vm
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: onami/sandbox/persist/src/site/apt/guicePersist.apt.vm
URL:
http://svn.apache.org/viewvc/onami/sandbox/persist/src/site/apt/guicePersist.apt.vm?rev=1592691&view=auto
==============================================================================
--- onami/sandbox/persist/src/site/apt/guicePersist.apt.vm (added)
+++ onami/sandbox/persist/src/site/apt/guicePersist.apt.vm Tue May 6 09:07:14
2014
@@ -0,0 +1,54 @@
+ ------
+ Onami-Persist vs. Guice-Persist
+ ------
+ The Apache Onami developers team
+ ------
+ 2014
+
+~~
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+~~
+
+Onami-Persist vs. Guice-Persist
+
+ Onami-Persist is inspired and based upon Guice-Persist. Most of the concepts
and ideas have been adapted and/or reused.
+
+ * UnitOfWork as the life cycle manager for EntityManagers.
+
+ * PersistFilter for spanning a UnitOfWork around a request.
+
+ * PersistenceService for starting and stopping the entire persistence
engine.
+
+ * @Transactional annotation on methods to span a transaction around the
method.
+
+ []
+
+ The most notable changes to guice-persist:
+
+ * EntityManager cannot be injected. Instead an EntityManagerProvider has to
be injected. ({{{./emProvider.html}details}}).
+
+ * @Transactional annotation allows to specify which persistence units are
involved in the transaction.
+
+ * UnitOfWork has a new method isActive()
+
+ * Retrieving an EntityManager does not start a UnitOfWork. Instead it will
throw an Exception if the UnitOfWork is not active.
+
+ * PersistenceService can be restarted after it has been stopped.
+
+ * @Finder annotation is not yet supported
+
Propchange: onami/sandbox/persist/src/site/apt/guicePersist.apt.vm
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: onami/sandbox/persist/src/site/apt/guicePersist.apt.vm
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: onami/sandbox/persist/src/site/apt/guicePersist.apt.vm
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: onami/sandbox/persist/src/site/apt/index.apt.vm
URL:
http://svn.apache.org/viewvc/onami/sandbox/persist/src/site/apt/index.apt.vm?rev=1592691&view=auto
==============================================================================
--- onami/sandbox/persist/src/site/apt/index.apt.vm (added)
+++ onami/sandbox/persist/src/site/apt/index.apt.vm Tue May 6 09:07:14 2014
@@ -0,0 +1,62 @@
+ ------
+ Home
+ ------
+ The Apache Onami developers team
+ ------
+ 2014
+
+~~
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+~~
+
+Welcome to Onami-Persist!
+
+ ${project.description}.
+
+Before starting
+
+ Onami-Persist is available on the Maven Central repo,
+ you just need to add the dependency below in your <<<pom.xml>>> file:
+
++--------------------------------------+
+<dependencies>
+ ...
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ ...
+</dependencies>
++--------------------------------------+
+
+Why Onami-Persist
+
+ The official guice extension guice-persist allows to configure and inject a
persistence unit into your classes.
+ Guice-persist assumes that only one persistence unit is used in an
application and that this persistence unit is
+ application managed. Onami-Persist overcomes this shortcoming.
+
+ It supports:
+
+ * multiple persistence units
+
+ * application manged and container managed persistence units
+
+ * resource local and JTA transactions.
+
+
Propchange: onami/sandbox/persist/src/site/apt/index.apt.vm
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: onami/sandbox/persist/src/site/apt/index.apt.vm
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: onami/sandbox/persist/src/site/apt/index.apt.vm
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: onami/sandbox/persist/src/site/apt/simpleWebApp.apt.vm
URL:
http://svn.apache.org/viewvc/onami/sandbox/persist/src/site/apt/simpleWebApp.apt.vm?rev=1592691&view=auto
==============================================================================
--- onami/sandbox/persist/src/site/apt/simpleWebApp.apt.vm (added)
+++ onami/sandbox/persist/src/site/apt/simpleWebApp.apt.vm Tue May 6 09:07:14
2014
@@ -0,0 +1,130 @@
+ ------
+ Simple Web Application
+ ------
+ The Apache Onami developers team
+ ------
+ 2014
+
+~~
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+~~
+
+Simple Web Application
+
+* java code
+
++--------------------------------------+
+public class BootstrapServletListener extends GuiceServletContextListener {
+ protected Injector getInjector() {
+ final PersistenceModule persistenceModule = new PersistenceModule() {
+ @Override
+ protected void configurePersistence() {
+
addContainerManagedPersistenceUnitWithJndiName("java:comp/env/foobar/puJndiName");
+ }
+ };
+
+ final ServletModule servletModule = new ServletModule() {
+ filter("/*").through(PersistenceFilter.class);
+ };
+
+ return Guice.createInjector(servletModule, persistenceModule,
getApplicationSpecificModules());
+ }
++--------------------------------------+
+
+* web.xml
+
++--------------------------------------+
+<?xml version="1.0" encoding="UTF-8"?>
+<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee";
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd";>
+ <display-name>FooBar App</display-name>
+ <filter>
+ <filter-name>guiceFilter</filter-name>
+ <filter-class>com.google.inject.servlet.GuiceFilter</filter-class>
+ </filter>
+ <filter-mapping>
+ <filter-name>guiceFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ <listener>
+ <listener-class>foo.bar.BootstrapServletListener</listener-class>
+ </listener>
+ <!-- More config. -->
+</web-app>
++--------------------------------------+
+
+* persistence.xml
+
++--------------------------------------+
+<persistence xmlns="http://java.sun.com/xml/ns/persistence";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"; version="2.0">
+ <persistence-unit name="puName" transaction-type="RESOURCE_LOCAL">
+ <!-- your configuration -->
+ </peristence-unit>
+</peristence>
++--------------------------------------+
+
+* JNDI Binding
+
+ In order to allow container managed persistence units the persistence unit
must be bound in the JNDI framework.
+
+ If your container follows the J2EE Standard 5.0 add the following to your
web.xml
+
++--------------------------------------+
+<peristence-unit-ref>
+ <peristence-unit-ref-name>foobar/puJndiName</peristence-unit-ref-name>
+ <peristence-unit-name>puName</peristence-unit-name>
+</peristence-unit-ref>
++--------------------------------------+
+
+ Important: JBoss AS7.x do not support placing the JNDI binding in the
web.xml.
+ Instead add the following to your persistence.xml
+
++--------------------------------------+
+<property name="jboss.entity.manager.factory.jndi.name"
value="java:comp/env/foobar/puJndiName" />
+<property name="jboss.as.jpa.managed" value="true" />
++--------------------------------------+
+
+ Important: JBoss AS 7.x makes all datasources defined in the standalone.xml
JTA managed. If you want one or more of
+ the datasources to be resource local you must add the attribute "jta" to the
datasource element.
+
++--------------------------------------+
+<datasource jndi-name="java:jboss/datasources/systemDS" pool-name="systemDS"
enabled="true" use-java-context="true" jta="false">
+ ...
+</datasource>
++--------------------------------------+
+
+* Structure of the .war
+
++--------------------------------------+
++ app.war
+| + META-INF
+| | + MANIFEST.MF
+| | + persistence.xml
+| + WEB-INF
+| | + classes
+| | | + META-INF
+| | | | + MANIFEST.MF
+| | | + foo
+| | | | + bar
+| | | | | + BootstrapServletListener.class
+| | + lib
+| | | + guice.jar
+| | | + onami-persist.jar
++--------------------------------------+
+
Propchange: onami/sandbox/persist/src/site/apt/simpleWebApp.apt.vm
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: onami/sandbox/persist/src/site/apt/simpleWebApp.apt.vm
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: onami/sandbox/persist/src/site/apt/simpleWebApp.apt.vm
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: onami/sandbox/persist/src/site/apt/standaloneApp.apt.vm
URL:
http://svn.apache.org/viewvc/onami/sandbox/persist/src/site/apt/standaloneApp.apt.vm?rev=1592691&view=auto
==============================================================================
--- onami/sandbox/persist/src/site/apt/standaloneApp.apt.vm (added)
+++ onami/sandbox/persist/src/site/apt/standaloneApp.apt.vm Tue May 6 09:07:14
2014
@@ -0,0 +1,85 @@
+ ------
+ Standalone Application
+ ------
+ The Apache Onami developers team
+ ------
+ 2014
+
+~~
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+~~
+
+Standalone Application
+
+* java code
+
++--------------------------------------+
+public static void main(String[] args) {
+ final PersistenceModule persistenceModule = new PersistenceModule() {
+ @Override
+ protected void configurePersistence() {
+ addApplicationManagedPersistenceUnit( "puName" );
+ }
+ };
+ final Injector injector = Guice.createInjector(persistenceModule,
getApplicationSpecificModules());
+
+ final PersistenceService persistenceService =
injector.getInstance(PersistenceService.class);
+
+ try {
+ persistenceService.start();
+
+ while(notTerminated()) {
+ // run application
+ }
+ }
+ finally {
+ persistenceService.stop();
+ }
+}
++--------------------------------------+
+
+* persistence.xml
+
++--------------------------------------+
+<persistence
+ xmlns="http://java.sun.com/xml/ns/persistence";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
+
http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd";
+ version="2.0">
+
+ <persistence-unit name="puName" transaction-type="RESOURCE_LOCAL">
+ <!-- your configuration -->
+ </peristence-unit>
+
+</peristence>
++--------------------------------------+
+
+* Structure of the .jar
+
++--------------------------------------+
++ app.jar
+| + META-INF
+| | + MANIFEST.MF
+| | + persistence.xml
+| + foo
+| | + bar
+| | | + Main.class
+| | | + App.class
++--------------------------------------+
+
Propchange: onami/sandbox/persist/src/site/apt/standaloneApp.apt.vm
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: onami/sandbox/persist/src/site/apt/standaloneApp.apt.vm
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: onami/sandbox/persist/src/site/apt/standaloneApp.apt.vm
------------------------------------------------------------------------------
svn:mime-type = text/plain
