onami-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sclas...@apache.org
Subject svn commit: r1592691 - in /onami/sandbox/persist/src/site/apt: ./ daoExample.apt.vm emProvider.apt.vm guicePersist.apt.vm index.apt.vm simpleWebApp.apt.vm standaloneApp.apt.vm
Date Tue, 06 May 2014 09:07:14 GMT
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



Mime
View raw message