Prerequisites

• Apache MyFaces Orchestra core

• Apache MyFaces Orchestra core15 (optional; requires java1.5 or later)

• Spring 2.x

• a JSF implementation (e.g. JSF-RI, MyFaces)

• a JPA implementation (e.g. OpenJPA, toplink.essentials (formerly Oracle Toplink)

• and all their dependencies
  This might sound somehow vague; however, the exact names of the necessary libraries depends on the JSF and JPA implementation. If you have to setup an application architecture like this from scratch it might be best to take a look at our examples package, and there in the file "pom.xml" which includes a section on the necessary dependencies.

Spring Configuration

Apache MyFaces Orchestra uses the powerful Spring framework to provide its conversation scope. Spring is a dependency injection framework - just like the JSF managed-bean facility which is configured in the faces-config files of traditional JSF applications. However Spring offers many very nice additional features, including some that are essential for Apache Orchestra. In particular it allows us to create a new scope-type.

Lets start with the Spring configuration for the conversation scope and the JPA entity-manager factory. This configuration file has to be placed into the WEB-INF directory of your web application using the name applicationContext.xml. This can be configured with a context-parameter in your web.xml; for more information, take a look at the Spring documentation.

  <?xml version="1.0" encoding="UTF-8"?>

  <beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:tx="http://www.springframework.org/schema/tx"
    xmlns:aop="http://www.springframework.org/schema/aop"
    xsi:schemaLocation="
    http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
    http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.0.xsd
    http://www.springframework.org/schema/aop
    http://www.springframework.org/schema/aop/spring-aop-2.0.xsd">

    <!-- 1. initialization of all orchestra modules (required for core15 module) -->
    <import resource="classpath*:/META-INF/spring-orchestra-init.xml" />

    <!-- 2. the conversation scopes -->
    <bean class="org.springframework.beans.factory.config.CustomScopeConfigurer">
      <property name="scopes">
        <map>
          <entry key="conversation.manual">
            <bean class="org.apache.myfaces.orchestra.conversation.spring.SpringConversationScope">
              <property name="timeout" value="30" />
              <property name="advices">
                <list>
                  <ref bean="persistentContextConversationInterceptor"/>
                </list>
              </property>
            </bean>
          </entry>

          <entry key="conversation.access">
            <bean class="org.apache.myfaces.orchestra.conversation.spring.SpringConversationScope">
              <property name="timeout" value="30" />
              <property name="advices">
                <list>
                  <ref bean="persistentContextConversationInterceptor"/>
                </list>
              </property>
              <property name="lifetime" value="access"/>
            </bean>
          </entry>
        </map>
      </property>
    </bean>

    <!-- 3. the "entity manager" manager -->
    <bean id="persistentContextConversationInterceptor"
        class="org.apache.myfaces.orchestra.conversation.spring.PersistenceContextConversationInterceptor">
      <property name="persistenceContextFactory" ref="persistentContextFactory"/>
    </bean>

    <!-- 4. conversation - persistence adapter -->
    <bean id="persistentContextFactory"
        class="org.apache.myfaces.orchestra.conversation.spring.JpaPersistenceContextFactory">
      <property name="entityManagerFactory" ref="entityManagerFactory"/>
    </bean>

    <!-- 5. persistence -->
    <bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/>

    <tx:annotation-driven />

    <bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager">
      <property name="entityManagerFactory" ref="entityManagerFactory"/>
    </bean>

    <bean id="entityManagerFactory"
        class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean">
      <property name="jpaProperties">
        <props>
          <prop key="toplink.logging.level">FINE</prop>
          <prop key="toplink.jdbc.driver">org.apache.derby.jdbc.EmbeddedDriver</prop>
          <prop key="toplink.jdbc.url">jdbc:derby:myfacesOrchestraDB;create=true</prop>
          <prop key="toplink.jdbc.user">sa</prop>
          <prop key="toplink.jdbc.password">foobar</prop>
          <prop key="toplink.target-database">oracle.toplink.essentials.platform.database.DerbyPlatform</prop>
          <prop key="toplink.ddl-generation">create-tables</prop>
        </props>
      </property>
      <property name="persistenceUnitName" value="default"/>
    </bean>
  </beans>
  

Basically, all you need to do is copy this configuration segment and paste it into your Spring configuration file. Then you'll need to adapt the settings in the element entityManagerFactory - namely the jpaProperties. For a more detailed explanation, we have included the following instructions - it is not necessary to read through them.

• 1. initialization of orchestra modules
  The Spring import statement will ensure that all spring-orchestra-init.xml files are processed. Orchestra sets up some defaults in these init files that are necessary for the correct functioning of Orchestra.
• 2. the conversation scopes
  Here we configure both "conversation.access" and "conversation.manual" as new Spring custom scopes. This configuration allows us to use scope="conversation.access" or scope="conversation.manual" within our bean declarations. The scope definition also allows a number of advices (interceptors) to be configured; advices intercept each method call to a bean in that scope. We add an interceptor here to ensure that on any call to a bean in that scope the entity manager (aka persistence context) is set to be the appropriate one for that conversation.
  If your application does not have to deal with persistence, and you would still like to use the conversation scopes you can delete the advices from this configuration.
  Optionally you can configure the timeout used to automatically end a conversation. The timeout property accepts a numeric value which means a timespan in minutes.
  Notice: Without this timeout configuration, a manual conversation won't die if you do not explicitly end it using the conversation API.
• 3. the "persistence context conversation interceptor"
  This tells spring what class to use for the interceptor specified in the scope definitions. This orchestra class does the hard work of keeping the right persistence context set up at all times.
• 4. conversation - persistence adapter
  Depending on the ORM tool you want to use you will have to configure an appropriate persistenceContextFactory. Apache MyFaces Orchestra provides a JPA implementation in its current release; other adapters may be added in the future.
• 5.persistence
  This enables the standard Spring support for persistence annotations such as @PersistenceContext; any bean instantiated by spring will be scanned for annotations and the appropriate dependencies injected.
  This section also sets up database transaction support.
  As this is all standard Spring functionality, have a look at the Spring documentation for further details and options. For our example, we use .
  If you are using Java 1.4 you can choose a non-annotation-based approach.

Notice : You will be able to configure multiple conversation scopes (each one of them will need to have a distinct name) using different persistence strategies or without persistence at all.

That's all for Spring now - according to the JPA specification and your JPA implementation, you will also have to provide a META-INF/persistence.xml too. Please check your JPA provider documentation on how to do this.

JSF configuration

Next you have to add some listeners to your web.xml configuration.

<listener>
  <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<listener>
  <listener-class>org.springframework.web.context.request.RequestContextListener</listener-class>
</listener>
<listener>
  <listener-class>org.apache.myfaces.orchestra.conversation.servlet.ConversationManagerSessionListener</listener-class>
</listener>

        

Mixed environment installation

If your application has only JSF pages then no further configuration is required.

However if your application includes jsp, plain servlets, or anything else that does not pass through the FacesServlet then two filters must be defined:

  <filter>
    <filter-name>frameworkAdapterFilter</filter-name>
    <filter-class>org.apache.myfaces.orchestra.frameworkAdapter.basic.BasicFrameworkAdapterFilter</filter-class>
  </filter>

  <filter>
    <filter-name>requestParameterFilter</filter-name>
    <filter-class>org.apache.myfaces.orchestra.requestParameterProvider.RequestParameterServletFilter</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>frameworkAdapterFilter</filter-name>
    <url-pattern>*.jsp</url-pattern>
  </filter-mapping>

  <filter-mapping>
    <filter-name>requestParameterFilter</filter-name>
    <url-pattern>*.jsp</url-pattern>
  </filter-mapping>

Conclusion