Seam 2.1 Migration Guide ======================== Before you get started with Seam 2.

1, there are a few things you should be aware of. This process should not be too painful - if you get stuck, just refer back to the updated Seam examples. This migration guide assumes you are using Seam 2.0, if you are migrating from Seam 1.2, see the seam2migration guide as well. Testing ------SeamTest now boots Seam at the start of each suite, rather than the start of each class. This is much faster. See the reference manual for how to alter the default. DTDs and Schemas ---------------The DTDs for Seam XML files are no longer supported. Please use the XML schemas for validation. Files that use the Seam 2.0 XSDs should be updated to refer to the 2.1 XSDs Exception Handling -----------------The caught exception is now available in EL as #{org.jboss.seam.caughtException} rather than #{org.jboss.seam.exception} EntityConverter configuration ----------------------------If you need to configure which entity manager to use, this is now done on the entity-loader component. See the documentation for details. Assumed name for managed Hibernate session -----------------------------------------Several areas of Seam, including the Seam Application Framework, rely on a naming convention for the Seam-managed persistence context (JPA) and Hibernate session. Prior to Seam 2.1, the assumed name of the managed Hibernate session was "session". However, session is a very overloaded name in Seam and the Java Servlet API. To make it less ambigous, the default was changed to "hibernateSession". The benefit now is that when you inject or resolve the Hibernate session, you know that is the refernece you are getting (rather than the HTTP session, mail session, or some other "session"). You would inject it as follows: @In private Session hibernateSession; or @In(name = "hibernateSession") private Session session; If the name of your Seam-managed Hibernate session is "session", you can still inject this reference explictly using the session property:

<framework:hibernate-entity-home session="#{session}".../> <transaction:entity-transaction session="#{session}".../> The alternative is to override the getPersistenceContextName() method on any persistence controller in the Seam Application Framework: public String getPersistenceContextName() { "session"; } Security -------If you are using rule-based security in your project, the configuration for the security rules in components.xml has changed. Previously, the rules were configu red as a property of the identity component as such: <security:identity security-rules="#{securityRules}" authenticate-method="#{au thenticator.authenticate}"/> In Seam 2.1, rule-based permission checks are now carried out by the ruleBasedPe rmissionResolver component. You must activate this component and register the security rules with it instead of the identity component: <security:rule-based-permission-resolver security-rules="#{securityRules}"/> IMPORTANT! The definition of a permission has also changed. Prior to Seam 2.1, a permission consisted of three elements: * name * action * contextual object (optional) The name would typically be the Seam component name, entity class, or view ID. T he action would be the method name, the JSF phase (restore or render), or an assigned term represen ting the intent of the activity. Finally, one or more contextual objects could be inserted directly into the working memory to help make the decision, typically the target of the activity. For example: s:hasPermission('userManager', 'edit', user) In Seam 2.1, a permission has been simplified to just two elements: * target * action In place of the nebulous name element, the target becomes the focus of the permi ssion. The action continues to communicate the intent of the activity being secured. Inside the ru les file, most of the checking now revolves around the target object. For example: s:hasPermission(user, 'edit')

This change makes the rules more generally applicable. It also allows Seam to co nsult a persistent permission resolver (ACL) in addition to the rule-based resolver. Be aware that existing rules may behave oddly. That's because given the followin g permission check: s:hasPermission('userManager', 'edit', user) Seam will transpose as follows to bring it inline with the new design. s:hasPemrission(user, 'edit') Please read the new chapter on security for all the details about this new desig n. Identity.isLoggedIn() --------------------This method has been modified so that it doesn't attempt to perform an authentic ation if credentials have been set. Instead, it will simply return true if the user is currently aut henticated. If you require the previous behaviour, then please use Identity.tryLogin() instead. If you are using the token-based "Remember Me" feature of Seam Security, you wil l need to add the following section to components.xml to ensure that the user is automatically logged in whe n first accessing the application: <event type="org.jboss.seam.security.notLoggedIn"> <action execute="#{redirect.captureCurrentView}"/> <action execute="#{identity.tryLogin}"/> </event> <event type="org.jboss.seam.security.loginSuccessful"> <action execute="#{redirect.returnToCapturedView}"/> </event> PDF (iText) -------The documentStore component has been moved from the pdf/itext module into Seam p roper. Any references to pdf:document-store in components.xml should be replaced with docum ent:document-store. Similary, if you are currently referencing org.jboss.seam.pdf.DocumentStoreServl et in your web.xml, you should now use org.jboss.seam.document.DocumentStoreServlet. Clustering ---------Seam's ManagedEntityInterceptor (formally ManagedEntityIdentityInterceptor) is n ow disabled by default. If you need the ManagedEntityInterceptor for clustered failover of conv ersations, you can enable it components.xml:

<core:init> <core:interceptors> <value>org.jboss.seam.core.SynchronizationInterceptor</value> <value>org.jboss.seam.async.AsynchronousInterceptor</value> <value>org.jboss.seam.ejb.RemoveInterceptor</value> <value>org.jboss.seam.persistence.HibernateSessionProxyInterceptor</value> <value>org.jboss.seam.persistence.EntityManagerProxyInterceptor</value> <value>org.jboss.seam.core.MethodContextInterceptor</value> <value>org.jboss.seam.core.EventInterceptor</value> <value>org.jboss.seam.core.ConversationalInterceptor</value> <value>org.jboss.seam.bpm.BusinessProcessInterceptor</value> <value>org.jboss.seam.core.ConversationInterceptor</value> <value>org.jboss.seam.core.BijectionInterceptor</value> <value>org.jboss.seam.transaction.RollbackInterceptor</value> <value>org.jboss.seam.transaction.TransactionInterceptor</value> <value>org.jboss.seam.webservice.WSSecurityInterceptor</value> <value>org.jboss.seam.security.SecurityInterceptor</value> <value>org.jboss.seam.persistence.ManagedEntityInterceptor</value> </core:interceptors> </core:init> Asynchronous Exception Handling ---------------------All asynchronous invocations are now wrapped in exception handling. By default, any exceptions which propagate out of the asynchronous call are caught and logged at error level. The reference manual describes how to customize this behaviour. Redeploy -------The org.jboss.seam.postInitialization event is no longer called on redeploy, instead org.jboss.seam.postReInitialization is called. Cache Support ------------Cache support has be rewritten to support JBoss Cache, JBoss POJO Cache, JBoss Cache 2 and EHCache. If you are running on JBoss AS 4.2.x JBoss Cache 1.x will be used or on JBoss 5.x JBoss Cache 2 will be installed. You can find more about how to configure the cache provider in the reference manual. The use <s:cache /> is unchanged, but you can no longer inject the pojoCache component. Instead you should configure JBoss POJO cache as your cache provider in components.xml: <cache:jboss-pojo-cache-provider /> and inject it using @In CacheProvider<PojoCache> cacheProvider; The CacheProvider provides a Map like interface, and the getDelegate() method can be used to retrieve the underling cache.

Dependency changes (Maven) -------------------------The "provided" platform is now JBoss AS 4.2.3, therefore javasisst:javassist and dom4j:dom4j are now marked as provided. Seam Application Framework Changes ---------------------------------Seam now expects value expressions for a number of properties (entityHome.createdMessage, entityHome.updatedMessage, entityHome.deletedMessage and entityQuery.restrictions); if you are using components.xml to configure your objects, you don't need to make any changes. If you are extending the objects in Java, you just need to create a value expression; for example: public ValueExpression getCreatedMessage() { return createValueExpression("New person #{person.firstName} #{person.lastNam e} created"); }