[fleXive] installation guide for JBoss 4.2.2 GA

[fleXive] installation guide for JBoss 4.2.2 GA
Prev	Chapter 2. Installing [fleXive]	Next

Required libraries

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:

mysql-connector-java-*.jar (Alternatively you can download the latest stable MySQL JDBC driver)
or h2.jar if you are using the H2 database.

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. For the H2 database, we provide the flexive-h2-ds.xml configuration file as a template. In the flexive-[h2-]ds.xml configure your database connections as follows if using MySQL: 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</connection-url>
    <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 MySQL Datasource Configuration

 Please make sure mysql-connector-java-<version>-bin.jar is copied to the <JBoss>/server/<profile>/lib directory!

 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>

If you are using H2 please apply the following settings:

                                
<!--
 JBoss H2 Datasource Configuration

 Please make sure h2.jar is copied to the <JBoss>/server/<profile>/lib directory!

 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>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
        <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
        <xa-datasource-property name="URL">jdbc:h2:tcp://localhost:9092/~/flexive;SCHEMA=flexive;MVCC=TRUE;LOCK_TIMEOUT=10000</xa-datasource-property>
        <user-name>sa</user-name>
        <!--<password></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/>
    </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>org.h2.Driver</driver-class>
        <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
        <connection-url>jdbc:h2:tcp://localhost:9092/~/flexive;SCHEMA=flexive;MVCC=TRUE;LOCK_TIMEOUT=10000</connection-url>
        <user-name>sa</user-name>
        <!--<password></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/>
    </no-tx-datasource>

    <xa-datasource>
        <jndi-name>jdbc/flexiveConfiguration</jndi-name>
        <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
        <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
        <xa-datasource-property name="URL">jdbc:h2:tcp://localhost:9092/~/flexive;SCHEMA=flexiveConfiguration;MVCC=TRUE</xa-datasource-property>
        <user-name>sa</user-name>
        <!--<password></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/>
    </xa-datasource>

</datasources>

Database Setup

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.
# Please use the database.vendor property at the bottom of this file to select
# the database vendor to use.

# MySQL database settings

# The server host or IP
database.MySQL.host=localhost
# The server port
database.MySQL.port=3306
# The user name and password to be used for creating flexive database structures
database.MySQL.username=root
database.MySQL.password=a
# The root schema where the flexive schemas can be dropped and created
database.MySQL.schema.root=mysql
database.MySQL.schema.config=mysql
# JDBC Driver
database.MySQL.driver=com.mysql.jdbc.Driver
# JDBC base URL, will be appended by the database name and the url parameters
database.MySQL.url.base=jdbc:mysql://${database.MySQL.host}:${database.MySQL.port}/
# Optional URL parameters to append to the JDBC connect string
database.MySQL.url.parameters=?useUnicode=true&amp;characterEncoding=UTF-8

# H2 database settings

# The server host or IP
database.H2.host=localhost
# The server port
database.H2.port=9092
# The user name and password to be used for creating flexive database structures
database.H2.username=sa
database.H2.password=
database.H2.schema.root=flexive
database.H2.schema.config=flexiveConfiguration
database.H2.driver=org.h2.Driver
database.H2.url.base=jdbc:h2:tcp://${database.H2.host}:${database.H2.port}/~/
database.H2.url.parameters=;SCHEMA=@DATABASE@;MVCC=TRUE


#select the database vendor to use
#database.vendor=H2
database.vendor=MySQL

database.properties contains settings for all currently supported database vendors of [fleXive]. You can adapt the setting like choosing different ports or locations for the database. The probably most important setting are the lines at the end of the file:

#select the database vendor to use
#database.vendor=H2
database.vendor=MySQL

Here you can select the database vendor to use by commenting out the appropriate line. In this example MySQL is the database vendor to be used.

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.

Deployment

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.

Starting [fleXive]

Currently JBoss 4.2.x uses the Java's default maximum heap size, which means that [fleXive] will probably run out of memory during the first startup. You have to set the maximum heap size using -Xmx to a larger value, at least 256m.

On Linux execute

export JAVA_OPTS="-Xms128m -Xmx512m"

On Windows execute

SET JAVA_OPTS=-Xms128m -Xmx512m

Change to the ${jboss.home}/bin directory.

On Linux launch JBoss using

sh run.sh -c default -Djboss.bind.address=0.0.0.0

On Windows launch JBoss using

                            start run.bat -c default -Djboss.bind.address=0.0.0.0

To access the administration GUI point your browser to http://localhost:8080/flexive/adm/

Alternatively you can specify your server's IP address, which is supported by default, too.
The default superuser's username and password for the administration GUI are:

username: supervisor, password: supervisor

Refining your configuration

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).