Conversion from JBoss 4.0.x to JBoss 5.1.x

Version 1

    Eclipse Workspace Changes

    If you are using Eclipse, here are some JARs that you may want to include in a User Library:

    • jboss-5.1.0.GA/common/lib/commons-logging.jar
    • jboss-5.1.0.GA/common/lib/servlet-api.jar
    • jboss-5.1.0.GA/common/lib/ejb-persistence.jar
    • jboss-5.1.0.GA/common/lib/jboss-javaee.jar
    • jboss-5.1.0.GA/common/lib/jsp-api.jar
    • jboss-5.1.0.GA/common/lib/mail.jar
    • jboss-5.1.0.GA/common/lib/jboss-ha-server-cache-jbc.jar
    • jboss-5.1.0.GA/common/lib/jboss-ejb3-ext-api.jar
    • jboss-5.1.0.GA/server/default/lib/jbosscache-core.jar

    Package Changes

    1. javax.annotation.EJB moved to javax.ejb.EJB

    JBoss Cache

    First, the TreeCacheMBean is gone. To access the cache, you need to  use the org.jboss.cache.jmx.CacheJmxWrapperMBean class. This MBean is  just a wrapper, you still need to get the org.jboss.cache.Cache object.  To use an object level version of the Cache, get the instance with a  @PostConstruct method in the session bean. Here's an example:

     

    SomeBean.java
    @Stateless
    public class SomeBean implements Some
    {
        @Resource(mappedName=JNDI_SOME_CACHE) CacheJmxWrapperMBean cacheWrapper;
        private Cache cache = null;

        @PostConstruct
        public void init()
        {
            cache = cacheWrapper.getCache();
        }
    }

     

    The configuration of the MBean has changed slightly also.

    1. The TransactionManagerLookupClass attribute changed from  org.jboss.cache.JBossTransactionManagerLookup to  org.jboss.cache.transaction.GenericTransactionManagerLookup.
    2. The EvictionPolicyClass attribute has moved to within the EvictionPolicyConfig attribute and is now named policyClass.
      Here's an example of the new file:

     

    Some-service.xml
    <?xml version="1.0" encoding="UTF-8"?>
    <server>

      <!--  ====================================================================  -->
      <!--  Defines TreeCache configuration                                       -->
      <!--  ====================================================================  -->
      <mbean code="org.jboss.cache.jmx.CacheJmxWrapper" name="jboss.cache:service=SomeCache">
        <depends>jboss:service=Naming</depends>
        <depends>jboss:service=TransactionManager</depends>

        <!-- Configure the TransactionManager -->
        <attribute name="TransactionManagerLookupClass">org.jboss.cache.transaction.GenericTransactionManagerLookup</attribute>

        <!--
                Node locking level : SERIALIZABLE
                                     REPEATABLE_READ (default)
                                     READ_COMMITTED
                                     READ_UNCOMMITTED
                                     NONE
        -->
        <attribute name="IsolationLevel">READ_COMMITTED</attribute>

        <!--     Valid modes are LOCAL
                                 REPL_ASYNC
                                 REPL_SYNC
        -->
        <attribute name="CacheMode">REPL_SYNC</attribute>

        <!-- Name of cluster. Needs to be the same for all clusters, in order
                 to find each other -->
        <attribute name="ClusterName">some-cache</attribute>

        <attribute name="ClusterConfig">
          <config>
            <!-- UDP: if you have a multihomed machine,
                    set the bind_addr attribute to the appropriate NIC IP address
            -->
            <!-- UDP: On Windows machines, because of the media sense feature
                     being broken with multicast (even after disabling media sense)
                     set the loopback attribute to true
            -->
            <UDP mcast_addr="${jboss.partition.udpGroup:228.1.2.3}" mcast_port="43333" ip_ttl="2" ip_mcast="true"
               mcast_send_buf_size="150000" mcast_recv_buf_size="80000" ucast_send_buf_size="150000"
               ucast_recv_buf_size="80000" loopback="false" />
            <PING timeout="2000" num_initial_members="3" up_thread="false" down_thread="false" />
            <MERGE2 min_interval="10000" max_interval="20000" />
            <FD shun="true" up_thread="true" down_thread="true" />
            <VERIFY_SUSPECT timeout="1500" up_thread="false" down_thread="false" />
            <pbcast.NAKACK gc_lag="50" max_xmit_size="8192" retransmit_timeout="600,1200,2400,4800" up_thread="false"
               down_thread="false" />
            <UNICAST timeout="600,1200,2400" window_size="100" min_threshold="10" down_thread="false" />
            <pbcast.STABLE desired_avg_gossip="20000" up_thread="false" down_thread="false" />
            <FRAG frag_size="8192" down_thread="false" up_thread="false" />
            <pbcast.GMS join_timeout="5000" join_retry_timeout="2000" shun="true" print_local_addr="true" />
            <pbcast.STATE_TRANSFER up_thread="false" down_thread="false" />
          </config>
        </attribute>

        <!--    The max amount of time (in milliseconds) we wait until the
                initial state (ie. the contents of the cache) are retrieved from
                existing members in a clustered environment
        -->
        <attribute name="InitialStateRetrievalTimeout">5000</attribute>

        <!--    Number of milliseconds to wait until all responses for a
                synchronous call have been received.
        -->
        <attribute name="SyncReplTimeout">10000</attribute>

        <!--  Max number of milliseconds to wait for a lock acquisition -->
        <attribute name="LockAcquisitionTimeout">15000</attribute>

        <!--  Specific eviction policy configurations. This is LRU -->
        <attribute name="EvictionPolicyConfig">
          <config>
            <attribute name="wakeUpIntervalSeconds">5</attribute>
            <!--  Cache wide default -->

            <!--  Name of the eviction policy class. -->
            <attribute name="policyClass">org.jboss.cache.eviction.LRUPolicy</attribute>

            <region name="/_default_">
             <attribute name="maxNodes">5000</attribute>
             <attribute name="timeToLiveSeconds">1000</attribute>
           </region>

           <region name="/some/data/company">
             <attribute name="maxNodes">5000</attribute>
             <attribute name="timeToLiveSeconds">0</attribute>
             <attribute name="maxAgeSeconds">3600</attribute>
           </region>
           <region name="/some/data/customer">
             <attribute name="maxNodes">5000</attribute>
             <attribute name="timeToLiveSeconds">0</attribute>
             <attribute name="maxAgeSeconds">3600</attribute>
           </region>

          </config>
        </attribute>

      </mbean>

         <mbean
              code="org.jboss.invocation.jrmp.server.JRMPProxyFactory"
              name="pinksheets:service=proxyFactory,type=jrmp,target=factory,name=SomeCache">
                     <attribute name="InvokerName">jboss:service=invoker,type=jrmp</attribute>
              <attribute name="TargetName">jboss.cache:service=SomeCache</attribute>
              <attribute name="JndiName">cache/Some</attribute>
              <attribute name="InvokeTargetMethod">true</attribute>
              <attribute name="ExportedInterface">org.jboss.cache.jmx.CacheJmxWrapperMBean</attribute>
              <attribute name="ClientInterceptors">
                   <iterceptors>
                        <interceptor>org.jboss.proxy.ClientMethodInterceptor</interceptor>
                        <interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>
                        <interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>
                   </iterceptors>
              </attribute>
              <depends>jboss:service=invoker,type=jrmp</depends>
              <depends>jboss.cache:service=SomeCache</depends>
         </mbean>

    </server>

    Messaging

    The configuration file changed from this for queues and topics:

     

    Some-destination-service.xml Old
      <mbean code="org.jboss.mq.server.jmx.Queue"
             name="jboss.mq.destination:service=Queue,name=someChange">
        <depends optional-attribute-name="DestinationManager">jboss.mq:service=DestinationManager</depends>
        <attribute name="RedeliveryDelay">300000</attribute>
        <attribute name="RecoveryRetries">10</attribute>
      </mbean>

      <mbean code="org.jboss.mq.server.jmx.Topic"
                    name="jboss.mq.destination:service=Topic,name=anotherChange">
        <depends optional-attribute-name="DestinationManager">jboss.mq:service=DestinationManager</depends>
        <attribute name="RedeliveryDelay">300000</attribute>
        <attribute name="RecoveryRetries">10</attribute>
      </mbean>

     

    To this:

     

    Some-destination-service.xml New
      <mbean code="org.jboss.jms.server.destination.QueueService"
          name="jboss.messaging.destination:service=Queue,name=someChange"
          xmbean-dd="xmdesc/Queue-xmbean.xml">
        <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
        <depends>jboss.messaging:service=PostOffice</depends>
        <attribute name="RedeliveryDelay">300000</attribute>
        <attribute name="MaxDeliveryAttempts">10</attribute>
      </mbean>

      <mbean code="org.jboss.jms.server.destination.TopicService"
         name="jboss.messaging.destination:service=Topic,name=anotherChange"
          xmbean-dd="xmdesc/Queue-xmbean.xml">
        <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
        <depends>jboss.messaging:service=PostOffice</depends>
        <attribute name="RedeliveryDelay">300000</attribute>
        <attribute name="MaxDeliveryAttempts">10</attribute>
      </mbean>

     

    And within the MDB, the following changes are required:

    1. The ActivationConfigProperty, ConnectionFactoryName, is no longer needed and must be removed.
    2. The ActivationConfigProperty, durability, is now named subscriptionDurability with the same value of Durable.

    Data Source Configuration File

    In any configuration file suffixed with -ds.xml, the usage of system  property substitution for the max-pool-size field yields the following  error:

    javax.resource.ResourceException: No ManagedConnections available within configured blocking timeout ( 30000 [ms] )

    Thus, you must replace the following:

     

    Some-ds.xml Old
    <?xml version="1.0" encoding="UTF-8"?>

    <datasources>
         <local-tx-datasource>
              <jndi-name>jdbc/Some</jndi-name>
              <connection-url>${some.db.url:jdbc:mysql://mydb.3306/somedb}</connection-url>
              <driver-class>${some.db.driver:com.mysql.jdbc.Driver}</driver-class>
              <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
              <user-name>${some.db.username:dba}</user-name>
              <password>${some.db.password:123}</password>
              <max-pool-size>${some.db.max:100}</max-pool-size>
         
              <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->
              <metadata>
                 <type-mapping>${some.db.typemapping:mySQL}</type-mapping>
              </metadata>
         </local-tx-datasource>
    </datasources>

     

    with this:

     

    Some-ds.xml New
    <?xml version="1.0" encoding="UTF-8"?>

    <datasources>
         <local-tx-datasource>
              <jndi-name>jdbc/Some</jndi-name>
              <connection-url>${some.db.url:jdbc:mysql://mydb:3306/somedb}</connection-url>
              <driver-class>${some.db.driver:com.mysql.jdbc.Driver}</driver-class>
              <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
              <user-name>${some.db.username:dba}</user-name>
              <password>${some.db.password:123}</password>
              <max-pool-size>100</max-pool-size>

              <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->
              <metadata>
                 <type-mapping>${some.db.typemapping:mySQL}</type-mapping>
              </metadata>
         </local-tx-datasource>
    </datasources>

     

    All other attributes may continue to use the system property substitution.

     

    Deployment Descriptors

    The application.xml, jboss.xml, jboss-web.xml, persistence.xml, and  web.xml descriptors require changes to the schemas/doctypes specified.  Here are their new headers. Please note that the web.xml descriptor only  needs to be updated if you're using the JSP Standard Template Library  from Sun. The downside of the web.xml update is that the taglib element is no longer supported after Servlet Spec 2.3. Thus, all  shortened taglib references in the JSPs must be modified to specify the  full taglib URI.

     

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

    <application xmlns="http://java.sun.com/xml/ns/javaee" version="5"
      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/application_5.xsd">
    jboss.xml
    <?xml version="1.0" encoding="ISO-8859-1" ?>

    <!DOCTYPE jboss PUBLIC
      "-//JBoss//DTD JBOSS 5.0//EN"
      "http://www.jboss.org/j2ee/dtd/jboss_5_0.dtd">
    jboss-web.xml
    <?xml version="1.0" encoding="UTF-8"?>

    <!DOCTYPE jboss-web PUBLIC
      "-//JBoss//DTD Web Application 5.0//EN"
      "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
    persistence.xml
    web.xml
    <?xml version="1.0" encoding="ISO-8859-1"?>

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

     

    Due to cache changes, the hibernate.cache.provider_class, hibernate.treecache.mbean.object_name, and hibernate.transaction.manager_lookup_class properties in persistence.xml must be removed and replaced with the following entries:

     

    persistence.xml
                   <property name="hibernate.cache.use_second_level_cache" value="true" />
                   <property name="hibernate.cache.use_query_cache" value="true" />
                   <property name="hibernate.cache.region.factory_class"
                        value="org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory"/>
                   <!-- region factory specific properties -->
                   <property name="hibernate.cache.region.jbc2.cachefactory" value="java:CacheManager" />
                   <property name="hibernate.cache.region.jbc2.cfg.entity" value="mvcc-entity" />
                   <property name="hibernate.cache.region.jbc2.cfg.collection" value="mvcc-entity" />

     

    Asynchronous replication of the HTTP session state is now considered  interval replication. The replication-config sections of the old &  new jboss-web.xml files are included here:

     

    jboss-web.xml Old
            <replication-config>
                    <replication-trigger>SET</replication-trigger>
                    <replication-type>ASYNC</replication-type>
                    <replication-granularity>ATTRIBUTE</replication-granularity>
                    <replication-field-batch-mode>TRUE</replication-field-batch-mode>
            </replication-config>
    jboss-web.xml New
         <replication-config>
              <replication-trigger>SET</replication-trigger>
              <replication-granularity>ATTRIBUTE</replication-granularity>
              <replication-field-batch-mode>true</replication-field-batch-mode>
              <snapshot-mode>INTERVAL</snapshot-mode>
              <snapshot-interval>30000</snapshot-interval>
         </replication-config>

    Entity Beans

    If you use an entity bean to map fields from a native SQL query with a sql-result-set-mapping,  make sure the bean does not include any CMR (Container Managed  Relationship) fields. JBoss 5.1 processes CMR fields used in a native  result set mapping like Container Managed Fields trying to load it from  the query results. Since the field does not exist in the results, the  database throws an error that the field does not exist.

    Queries

    A query that tries to reference the many side of a CMR directly within the WHERE clause will fail. Here's the old query.

    SELECT COUNT(DISTINCT o.id) FROM Some o WHERE  o.parentId = ?1 AND o.others.typeId = ?2

    And here's the error message:

    org.hibernate.QueryException: illegal attempt to  dereference collection [some0_.id.others] with element  property reference [typeId]

    Finally, here's the new query:

    SELECT COUNT(DISTINCT o.id) FROM Some o INNER JOIN o.others oth WHERE  o.parentId = ?1 AND oth.typeId = ?2

    Timer Service

    If regular interval jobs are setup at application startup with the  TimerService, make sure to cancel all previous timers. JBoss 4  automatically canceled all timers when the server shutdown. JBoss 5  retains and starts up prior timers, so timers setup during startup  become cumulative. Here's a simple method to cancel all timers for an  EJB.

     

    Cancel Timers
         TimerService service = context.getTimerService();
         Collection<Timer> timers = service.getTimers();

         // DO NOT need to filter timers. getTimers only returns timers for this EJB/service.
         for (Timer timer : timers)
         {
              log.info(timer.getInfo().toString() + " - found timer and stopping.");
              timer.cancel();
         }