## Installation

In the following, we will assume that you know how to setup

- a servlet container (Tomcat, Jetty, etc)
- your ORM tool (OpenJPA, Toplink.essentials, Hibernate, etc)
- your JSF implementation (MyFaces, JSF-RI, etc)

For a beginner these are big assumptions; none of these technologies are simple. However we simply cannot conver these topics in a brief guide. In addition, these subjects are covered well elsewhere.

For an absolute beginner in using these technologies, we recommend taking a look at the Faces-Goodies project - a perfect way of kickstarting you in the world of JSF, Spring and JPA and then return back to include Apache Orchestra.

The installation guide will show you how to setup a JPA entity manager for Orchestra (so you are working with the new JavaPersistence API standard). Later we hope to add chapters on integrating directly with Hibernate and Toplink.

### 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

That's all for the basic configuration of Apache MyFaces Orchestra; now you should have working conversation scopes and correctly configured persistence. In fact there is nothing special in creating the database access objects (DAO) or your business objects (BO). Your JSF page backing beans will also look the same - however, you configure them in Spring and put them into the conversation scope now, rather than session scope.

## User provided configurations

- A spring configuration using toplink and load time weaving with tomcat