There are two approaches to migrating your Seam 1.2 application to Seam 2. The recommended approach, described in Section 4.1, “Creating a new project skeleton using seam-gen” is to create a new project using seam-gen in Seam 2, and migrate your code across. We recognize that many projects may have extensive customizations to their project, so we also provide instructions for how to upgrade your project in-situ in Section 4.2, “In place migration” Due to the number of changes introduced between Seam 1.2 and Seam 2, this may not always be a straightforward process!
However you decide to migrate your application, you'll need to alter your code, as many components have moved. Section 4.3, “Updating your code” details those changes.
Start by creating a new skeleton seam project. In your Seam 2 directory run:
~/seam_2_0$ ./seam setup
Customize the defaults as needed. You'll want to set the location of JBoss EAP, name your project and select an EAR or WAR as needed; you can accept the defaults for Java package names (as we aren't going to use the reverse engineering features of seam-gen); you'll want to set your JDBC driver, URL, username and password correctly, and configure Hibernate to drop and recreate tables if so desired.
Now, we are ready to import your existing code and views into the new structure. The simplest way to do this is to import both projects into your favorite IDE, and copy your code and views across.
Continue on to Section 4.3, “Updating your code” for details regarding the changes needed to your code, and configuration files.
This requires more work, but is suitable for more complex projects. The steps below may not be an exhaustive list, so if you have to any extra steps please report them through the Customer Support Portal.
You only need to do this if you are migrating from the community edition of Seam, JBoss EAP 4.2 and 4.3 shipped a version of Seam 1.2 which used JSF 1.2.
Seam 2.0 requires JSF 1.2, and JBoss EAP supports Sun's JSF RI. To switch to JSF 1.2, you need to remove the MyFaces listener:
<!--Remove for Seam 2-->
<!--<listener>
<listener-class>org.apache.myfaces.webapp.StartupServletContextListener</listener-class>
</listener>-->
from your web.xml
.
The JSF RI doesn't require you to specify a listener.
Due to an incompatibility between Seam and MyFaces, you had to use client side state saving in Seam 1.2. Switching to the JSF RI 1.2 lifts this restriction.
In your Seam 1.2 app you may have specified some Seam specific
configuration in web.xml
. First, we'll discuss
all the Seam related elements you need in
web.xml
, not just those that have changed, noting
any changes.
In Seam 2, you need specify a listener (just as you did in Seam 1.2):
<listener>
<listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
</listener>
Modify the Seam master filter (note the package of the class changed):
<filter>
<filter-name>Seam Filter</filter-name>
<filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Seam Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
If any other Seam Filters (for example the
SeamExceptionFilter
) are enumerated, they should
be removed.
Finally, you should have the Seam resouce servlet (just as you did in Seam 1.2):
<servlet>
<servlet-name>Seam Resource Servlet</servlet-name>
<servlet-class>org.jboss.seam.servlet.SeamResourceServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Seam Resource Servlet</servlet-name>
<url-pattern>/seam/resource/*</url-pattern>
</servlet-mapping>
Seam 2 will automatically install RichFaces' Ajax4JSF if it present in your project so you should make sure the Ajax4JSF filter isn't declared:
<!--Remove for Seam 2-->
<!--<filter>
<display-name>Ajax4jsf Filter</display-name>
<filter-name>ajax4jsf</filter-name>
<filter-class>org.ajax4jsf.Filter</filter-class>
</filter>-->
<!--Remove for Seam 2-->
<!--<filter-mapping>
<filter-name>ajax4jsf</filter-name>
<url-pattern>*.seam</url-pattern>
</filter-mapping>-->
Next, we'll describe the changes you need to make to your JSF
ViewHandler
configuration. Previously the
configuration you used depended on whether you were using Seam's EL
enhancements or Ajax4JSF or both. In Seam 2 you should use the
default FaceletViewHandler
.
Seam 1.2 required you to use a special JSF
ViewHandler
to install it's EL enhancement
(whilst in Seam 2 the EL enhancement is built in). The version of
Ajax4JSF distributed with Seam 1.2 required you to specify which
ViewHandler
to use when it was in use. Make sure
that the Ajax4JSF configuration is removed from your
web.xml:
:
<!--Remove for Seam 2-->
<!--<context-param>
<param-name>org.ajax4jsf.VIEW_HANDLERS</param-name>
<param-value>org.jboss.seam.ui.facelet.SeamFaceletViewHandler</param-value>
</context-param>-->
And that FaceletViewHandler
is set in
faces-config.xml
:
<application>
<view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
</application>
Seam 1.2 required you to specify either the
SeamPhaseListener
(Seam Managed Transaction were
are disabled) or SeamTransactionalPhaseListener
(Seam Managed Transactions are enabled) in
faces-config.xml
. Seam 2 lets you enable or
disable Seam Managed Transactions in
components.xml
, and installs the phase listener
for you. Therefore, you should remove any reference to
SeamPhaseListener
or
SeamTransactionalPhaseListener
from
faces-config.xml
.
Seam Managed Transaction are enabled by default, to disable Seam
Managed Transactions, set
transaction-management-enabled
to false:
<core:init transaction-management-enabled="false"/>
To workaround a bug, you may have specified
SeamELResolver
in
faces-config.xml
. This is no longer required.
If you have an EAR application there are some deployment structure
changes needed. You should move all the dependencies which you
previously declared as modules in application.xml
in the lib/
directory of your EAR
except jboss-seam.jar
which
should be declared as an ejb module in
application.xml
. Remove the unneeded module
declarations from application.xml
.
Support for deployment to JBoss Embeddable EJB3 and JBoss Microcontainer has been removed. Instead, the new JBoss Embedded distribution gives you a full set of EE-compatible APIs with simplified deployment.
For testing, you need the jars in Seam's lib/test
,
the jars in Seam's lib/
directory, your test
classes and application classes together with the
bootstrap/
directory in your classpath.
SeamTest
will automatically start the container.
You must order the classpath correctly when using Embedded with
SeamTest
. Make sure the jars in
lib/test
come first in any classpath order.
For example, when using Ant, they should be declared above any
other libraries in the test classpath.
If you want to run tests using the Eclipse TestNG plugin, you'll
need to add these jars to the top of your TestNG classpath. Using
the Run Dialog, select the xml suite to run, and add
/lib/test/jboss-embedded-all.jar
,
/lib/test/hibernate-all.jar
,
/lib/test/thirdparty-all.jar
,
/lib/jboss-embedded-api.jar
,
/lib/jboss-deployers-client-spi.jar
,
/lib/jboss-deployers-core-spi.jar
, and
/bootstrap
as the first entries in the
User classpath.
Note that JBoss Embedded is able to bootstrap a datasource from a
-ds.xml
file, so there is no longer a need for
jboss-beans.xml
.
Don't forget to update the XSD's in pages.xml
and
components.xml
to point at the ones for Seam 2.
Just change the suffix from -1.2.xml
to
-2.0.xml
.
Seam's built-in components have undergone a major reorganization designed to organize them for easier learning, and to isolate dependencies upon particular technologies like JSF into specific packages.
You'll need to update both your components.xml
and any references in Java code.
In general:
Persistence-related components are located in
org.jboss.seam.persistence
jBPM related components are located in
org.jboss.seam.bpm
JSF-related components are located in
org.jboss.seam.faces
Servlet-related components are located in
org.jboss.seam.web
Components related to asynchronicity are located in
org.jboss.seam.async
i18n-related components are located in
org.jboss.seam.international
The Pageflow component are located in
org.jboss.seam.pageflow
The Pages component are located in
org.jboss.seam.navigation
The following table presents a non-exhaustive list of changed components:
Table 4.1. Component's in Seam 2
Component name |
Seam 1.2 Old class |
Seam 2 class |
XML Element |
XML namespace |
XSD |
---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
N/A |
N/A |
N/A |
|
|
|
|
|
|
Specified by user |
|
|
|
|
|
|
|
|
N/A |
N/A |
N/A |
|
|
|
N/A |
N/A |
N/A |
|
|
|
N/A |
N/A |
N/A |
Specified by user |
|
|
|
|
|
Specified by user |
|
|
|
|
|
|
|
|
N/A |
N/A |
N/A |
|
|
removed |
N/A |
N/A |
N/A |
|
|
|
N/A |
N/A |
N/A |
|
|
|
|
|
|
N/A |
|
|
N/A |
N/A |
N/A |
|
|
|
|
|
|
N/A |
|
removed |
N/A |
N/A |
N/A |
Specified by user |
|
|
|
|
|
|
|
|
N/A |
N/A |
N/A |
Specified by user |
|
|
|
|
|
|
|
removed |
N/A |
N/A |
N/A |
|
|
|
N/A |
N/A |
N/A |
|
|
|
|
|
|
|
|
|
N/A |
N/A |
N/A |
|
|
|
N/A |
N/A |
N/A |
|
|
|
N/A |
N/A |
N/A |
|
|
|
N/A |
N/A |
N/A |
|
|
|
N/A |
N/A |
N/A |
|
|
|
|
|
|
|
|
|
N/A |
N/A |
N/A |
Annotations have also moved to reflect their purpose. In
BPM-related annotations are located in
org.jboss.seam.annotations.bpm
@BeginTask
@CreateProcess
@EndTask
@ResumeProcess
@StartTask
@Transition
JSF-related annotations are located in
org.jboss.seam.annotations.faces
@Converter
@Validator
Interceptor annotations are located in
org.jboss.seam.annotations.intercept
@AroundInvoke
@BypassIntercetors
@Interceptor
@Interceptors
Annotations related to asynchronicity are located in
org.jboss.seam.annotations.async
@Asynchronous
@Duration
@Expiration
@FinalExpiration
@IntervalCron
@IntervalDuration
The annotation to inject a request parameter is located in
org.jboss.seam.annotations.web
@RequestParameter
The annotation required to make a method accessible via
remoting is located in
org.jboss.seam.annotations.remoting
The annotation to apply a security restriction to the
component is located in
org.jboss.seam.annotations.security
@Restrict
Exception handling annotations moved to
org.jboss.seam.annotations.exception
@HttpError
@Redirect
You also need to replace @Intercept(NEVER)
with @BypassInterceptors
.
The conversation-is-long-running-parameter
attribute has been removed from Seam (and doesn't have a
replacement), remove it from <core:init />
.
As described in Section 4.2.4, “Migration to JBoss Embedded”, Embeddable EJB3
and Microcontainer support has been removed, so you need to remove
<core:ejb/>
and
<core:microcontainer/>
from
components.xml
.
The EE transaction integration has been redesigned, so the
transaction listener component name has changed. Replace
<core:transaction-listener/>
with
<transaction:ejb-transaction/>
.
The resource bundle loader has been split out of the resource bundle,
so you should replace
<core:resource-bundle/>
with
<core:resource-loader/>
.
Finally, you should change any expression
attributes to execute
:
<event type="org.jboss.seam.notLoggedIn">
<action execute="#{redirect.captureCurrentView}"/>
</event>
If you are using jBPM for business processes,
you need to add the tx service to jbpm.cfg.xml
:
<service name="tx" factory="org.jbpm.tx.TxServiceFactory" />
You don't need to do this if you are just using jBPM for pageflows.
If you are using RichFaces or Ajax4jsf, a major reorganization of
the project has occurred. ajax4jsf.jar
and
richfaces.jar
have been replaced by
richfaces-api.jar
(which should go in your ear
lib/
directory),
richfaces-impl.jar
and
richfaces-ui.jar
(both of which go in
WEB-INF/lib
).
You should check the RichFaces documentation for more information on parameter name changes and namespace changes.
As most JSF component sets provide a date selector, the Seam date
selector (s:selectDate
has been deprecated. You
should replace it with the date selector from the component set you
use.
<s:decorate/>
has become a naming container.
Therefore client ids have changed from
fooForm:fooInput
to
fooForm:foo:fooInput
(assuming your
<s:decorate>
has foo as an id).