[fleXive] installation guide for JBoss 4.2.2 GA

The following required libraries have to be deployed:

Copy the following file from the extlib directory of your [fleXive] binary distribution to ${jboss.home}/server/default/lib:

  • Create and copy the datasource config file flexive-ds.xml to ${jboss.home}/server/default/deploy/ and adapt to your datasource(s) or simply copy it from the [fleXive] source tree, if available. In the flexive-ds.xml configure your database connections as follows: For the flexive database

    <!-- transactional datasource -->
    <xa-datasource>
        <jndi-name>jdbc/flexiveDivision1</jndi-name>
        <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
        <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
        <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/flexive?useUnicode=true&characterEncoding=utf8&characterResultSets=utf8</xa-datasource-property>
        <user-name>root</user-name>
        <password>a</password>
    </xa-datasource>
    
    <!-- non-transactional datasource for database structure patches, Quartz, etc. -->
    <no-tx-datasource>
        <jndi-name>jdbc/flexiveDivision1NoTX</jndi-name>
        <driver-class>com.mysql.jdbc.Driver</driver-class>
        <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
        <connection-url>jdbc:mysql://localhost:3306/flexive?useUnicode=true&characterEncoding=utf8&characterResultSets=utf8</xa-datasource-property>
        <user-name>root</user-name>
        <password>a</password>
    </no-tx-datasource>
    
    

    For the flexiveConfiguration database

    <xa-datasource>
        <jndi-name>jdbc/flexiveConfiguration</jndi-name>
        <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
        <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
        <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/flexiveConfiguration?useUnicode=true&characterEncoding=utf8&characterResultSets=utf8</xa-datasource-property>
        <user-name>root</user-name>
        <password>a</password>
    </xa-datasource>
    

    flexive-ds.xml

                                    
    <!--
     JBoss Datasource Configuration
    
     See http://www.redhat.com/docs/manuals/jboss/jboss-eap-4.3/doc/Server_Configuration_Guide/html/Connectors_on_JBoss-Configuring_JDBC_DataSources.html
     for detailed configuration infos
    -->
    <datasources>
    
        <!--
            transactional datasource, as configured in the global configuration
        -->
        <xa-datasource>
            <jndi-name>jdbc/flexiveDivision1</jndi-name>
            <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
            <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
            <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/flexive?useUnicode=true&amp;characterEncoding=utf8&amp;characterResultSets=utf8</xa-datasource-property>
            <user-name>root</user-name>
            <password>a</password>
    
            <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
            <no-tx-separate-pools/>
            <!-- This disables transaction interleaving (which BTW, most DB vendors don't support) -->
            <track-connection-by-tx/>
            <isSameRM-override-value>false</isSameRM-override-value>
    
            <!--pooling parameters-->
            <min-pool-size>5</min-pool-size>
            <max-pool-size>20</max-pool-size>
            <blocking-timeout-millis>5000</blocking-timeout-millis>
            <idle-timeout-minutes>15</idle-timeout-minutes>
    
            <!-- If you supply the usr/pw from a JAAS login module -->
            <security-domain/>
    
            <exception-sorter-class-name>
                com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
            </exception-sorter-class-name>
            <valid-connection-checker-class-name>
                com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
            </valid-connection-checker-class-name>
            <metadata>
                <type-mapping>mySQL</type-mapping>
            </metadata>
        </xa-datasource>
    
        <!--
            non-transactional datasource for database structure patches, Quartz, etc.
            As per convention, non-transactional datasources have the same name like
            transactional but use the suffix "NoTX"
        -->
        <no-tx-datasource>
            <jndi-name>jdbc/flexiveDivision1NoTX</jndi-name>
            <driver-class>com.mysql.jdbc.Driver</driver-class>
            <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
            <connection-url>jdbc:mysql://localhost:3306/flexive?useUnicode=true&amp;characterEncoding=utf8&amp;characterResultSets=utf8</connection-url>
            <user-name>root</user-name>
            <password>a</password>
    
            <!--pooling parameters-->
            <min-pool-size>5</min-pool-size>
            <max-pool-size>20</max-pool-size>
            <blocking-timeout-millis>5000</blocking-timeout-millis>
            <idle-timeout-minutes>15</idle-timeout-minutes>
    
            <!-- If you supply the usr/pw from a JAAS login module -->
            <security-domain/>
    
            <exception-sorter-class-name>
                com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
            </exception-sorter-class-name>
            <valid-connection-checker-class-name>
                com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
            </valid-connection-checker-class-name>
            <metadata>
                <type-mapping>mySQL</type-mapping>
            </metadata>
        </no-tx-datasource>
    
        <xa-datasource>
            <jndi-name>jdbc/flexiveConfiguration</jndi-name>
            <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
            <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
            <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/flexiveConfiguration?useUnicode=true&amp;characterEncoding=utf8&amp;characterResultSets=utf8</xa-datasource-property>
            <user-name>root</user-name>
            <password>a</password>
    
            <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
            <no-tx-separate-pools/>
            <!-- This disables transaction interleaving (which BTW, most DB vendors don't support) -->
            <track-connection-by-tx/>
            <isSameRM-override-value>false</isSameRM-override-value>
    
            <!--pooling parameters-->
            <min-pool-size>5</min-pool-size>
            <max-pool-size>20</max-pool-size>
            <blocking-timeout-millis>5000</blocking-timeout-millis>
            <idle-timeout-minutes>15</idle-timeout-minutes>
    
            <!-- If you supply the usr/pw from a JAAS login module -->
            <security-domain/>
    
            <exception-sorter-class-name>
                com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
            </exception-sorter-class-name>
            <valid-connection-checker-class-name>
                com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
            </valid-connection-checker-class-name>
            <metadata>
                <type-mapping>mySQL</type-mapping>
            </metadata>
        </xa-datasource>
    
    </datasources> 
    
                                

To set up the databases do the following

  • Adapt the database.properties file located in your flexive-dist directory of your [fleXive] distribution to your needs:

    # This is the database configuration file used by the flexive setup tasks.
    #
    # Enter the settings for your database server connection to be used for development.
    
    # The server host or IP
    database.host=localhost
    # The server port
    database.port=3306
    # The user name and password to be used for creating flexive database structures
    database.username=root
    database.password=a

  • Change to the flexive-dist directory of your [fleXive] distribution and run ant db.create db.config.create

    You will be prompted to enter a name for your division database (simply hit enter to keep flexive).

    Warning: Existing databases will be deleted.

Change to the flexive-dist directory of your [fleXive] distribution and run ant ear. This will create the flexive.ear file inside the flexive-dist directory. Copy flexive.ear to ${jboss.home}/server/default/deploy.

  • Extend ${jboss.home}/server/default/conf/jboss-log4j.xml to configure logging:

        
    <!-- Limit flexive -->
    <category name="com.flexive">
        <priority value="INFO"/>
    </category>
    
    <!-- Limit ajax4jsf -->
    <category name="org.ajax4jsf">
        <priority value="WARN"/>
    </category>
    

  • Optional if you need JAAS support: Extend ${jboss.home}/server/default/conf/login-config.xml with the following entry:

        
    <application-policy name = "FxLogin">
         <authentication>
           <login-module code="com.flexive.core.security.FxDefaultLogin" flag="required"></login-module>
         </authentication>
    </application-policy>
    

  • Optional step: To use an external service deployer for JBoss Cache, create the cache service file 99_JBossCacheJNDI42-service.xml in ${jboss.home}/server/default/deploy/ or simply copy it from the [fleXive] source tree, if available:

                                <?xml version="1.0" encoding="UTF-8"?>
    <server>
    
       <loader-repository>com.flexive:archive=flexive.ear
       </loader-repository>
    
       <!-- ========================================================== -->
       <!-- Clustered SFSB cache config for use with JBoss Cache 1.4.x --> 
       <!-- ========================================================== -->
       <mbean code="org.jboss.cache.jmx.CacheJmxWrapper"
              name="jboss.cache:service=JNDITreeCache">
          <!--<depends>jboss:service=Naming</depends>-->
          <!--<depends>jboss:service=TransactionManager</depends>-->
    
          <attribute name="TransactionManagerLookupClass">org.jboss.cache.transaction.GenericTransactionManagerLookup</attribute>
            
           <!--
                   Node locking scheme :
                                       PESSIMISTIC (default)
                                       OPTIMISTIC
           -->
          <attribute name="NodeLockingScheme">PESSIMISTIC</attribute>
           
          <attribute name="ClusterName">[fleXive]-Cache-JNDI</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_ASYNC</attribute>
    
    	  <!-- We want to activate/inactivate regions as beans are deployed -->
          <attribute name="UseRegionBasedMarshalling">true</attribute>
          <!-- Must match the value of "useRegionBasedMarshalling" -->
          <attribute name="InactiveOnStartup">true</attribute>
    
    	  <!-- 
    	       JGroups protocol stack config in XML format.
    		   If your CacheMode is set to REPL_SYNC we recommend you comment
               out the FC (flow control) protocol
    			 
               On Windows machines, because of the media sense feature
               being broken with multicast (even after disabling media sense)
               set the UDP.loopback attribute to true
    	  -->     
          <attribute name="ClusterConfig">
             <config>
                <UDP mcast_addr="${flexive.cluster.udpGroup:229.1.2.5}"
                 mcast_port="${jboss.ejb3sfsbpartition.mcast_port:45557}"
                 tos="8"
                 ucast_recv_buf_size="20000000"
                 ucast_send_buf_size="640000"
                 mcast_recv_buf_size="25000000"
                 mcast_send_buf_size="640000"
                 loopback="false"
                 discard_incompatible_packets="true"
                 enable_bundling="false"
                 max_bundle_size="64000"
                 max_bundle_timeout="30"
                 use_incoming_packet_handler="true"
                 use_outgoing_packet_handler="false"
                 ip_ttl="${jgroups.udp.ip_ttl:2}"
                 down_thread="false" up_thread="false"/>
              <PING timeout="2000"
                 down_thread="false" up_thread="false" num_initial_members="3"/>
              <MERGE2 max_interval="100000"
                 down_thread="false" up_thread="false" min_interval="20000"/>
              <FD_SOCK down_thread="false" up_thread="false"/>
              <FD timeout="10000" max_tries="5" down_thread="false" up_thread="false" shun="true"/>
              <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
              <pbcast.NAKACK max_xmit_size="60000"
                       use_mcast_xmit="false" gc_lag="0"
                       retransmit_timeout="300,600,1200,2400,4800"
                       down_thread="false" up_thread="false"
                       discard_delivered_msgs="true"/>
              <UNICAST timeout="300,600,1200,2400,3600"
                 down_thread="false" up_thread="false"/>
              <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
                       down_thread="false" up_thread="false"
                       max_bytes="400000"/>
              <pbcast.GMS print_local_addr="true" join_timeout="3000"
                       down_thread="false" up_thread="false"
                       join_retry_timeout="2000" shun="true"
                       view_bundling="true"
                       view_ack_collection_timeout="5000"/>
              <FC max_credits="2000000" down_thread="false" up_thread="false"
                  min_threshold="0.10"/>
              <FRAG2 frag_size="60000" down_thread="false" up_thread="false"/>
              <pbcast.STATE_TRANSFER down_thread="false" up_thread="false" use_flush="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.
          -->
          <attribute name="InitialStateRetrievalTimeout">17500</attribute>
    
          <!--    Number of milliseconds to wait until all responses for a
                  synchronous call have been received.
          -->
          <attribute name="SyncReplTimeout">17500</attribute>
    
          <!--  Max number of milliseconds to wait for a lock acquisition -->
          <attribute name="LockAcquisitionTimeout">15000</attribute>
    
          <!--  Specific eviction policy configurations. -->
          <attribute name="EvictionPolicyConfig">
             <config>
                <attribute name="policyClass">org.jboss.cache.eviction.LRUPolicy</attribute>
                <attribute name="wakeUpIntervalSeconds">5</attribute>
                <name>flexiveMain</name>
                <!-- So default region would never timeout -->
                <region name="/_default_">
                   <attribute name="maxNodes">0</attribute>
                   <attribute name="timeToLiveSeconds">0</attribute>
                </region>
                <!-- cache region for contents -->
                <region name="/Division1/FxContent">
                    <attribute name="maxNodes">1000</attribute>
                    <attribute name="timeToLiveSeconds">1000</attribute>
                </region>
                 <!-- cache region for user configuration -->
                 <region name="/Division1/userConfig">
                     <attribute name="maxNodes">10000</attribute>
                     <attribute name="timeToLiveSeconds">1000</attribute>
                 </region>
             </config>
          </attribute>
       </mbean>
    </server>
    
                            

    If you want to use the external cache deplyoment you have to apply another modification: Due to classloading issues ([fleXive] uses JBoss Cache 2.x, while JBoss 4.2 uses JBoss Cache 1.x) you need to modify the deployment scanner in ${jboss.home}/server/default/conf/jboss-service.xml: replace the entry

                                <attribute name="URLComparator">org.jboss.deployment.DeploymentSorter</attribute>

    with

                                <attribute name="URLComparator">org.jboss.deployment.scanner.AlphaNumericDeploymentSorter</attribute>

    This ensures that the cache service is started after flexive.ear is deployed and thus can use its cache implementation classes (this deployment scanner allows to influence the deployment order with a numeric prefix, otherwise it's the same as the default one).