LSPS documentation logo
LSPS Documentation
Setting up WildFly 9.0.2 with LSPS Application

Important: It is strongly discouraged to run other applications on WildFly (WF) with LSPS since LSPS is using a customized Hibernate.

To set up WildFly 9.0.2 with LSPS, do the following:

  1. Install WildFly.
  2. Create WildFly module with the LSPS login module:
    1. Copy lsps-security-jboss-${lsps.version}.jar to $WF_HOME/modules/com/whitestein/lsps/security/main.
    2. Create the file $WF_HOME/modules/com/whitestein/lsps/security/main/module.xml with the following content:
      <module xmlns="urn:jboss:module:1.0" name="com.whitestein.lsps.security">
        <resources>
          <resource-root path="lsps-security-jboss-${lsps.version}.jar"/>
        </resources>
        <dependencies>
          <module name="javax.api"/>
          <module name="javax.transaction.api"/>
          <module name="org.picketbox" />
        </dependencies>
      </module>
      
      Take a note of the module name since it is used later for security realm configuration.
  3. Create a WildFly module with your JDBC driver. Type IV JDBC drivers are recommended.

    • For MySQL you need to copy MySQL Connector/J, that is, mysql-connector-java-<VERSION>-bin.jar to $WF_HOME/modules/com/mysql/main. Then create $WF_HOME/modules/com/mysql/main/module.xml with following content:
      <module xmlns="urn:jboss:module:1.0" name="com.mysql">
        <resources>
          <resource-root path="mysql-connector-java-<VERSION>-bin.jar"/>
        </resources>
        <dependencies>
          <module name="javax.api"/>
          <module name="javax.transaction.api"/>
        </dependencies>
      </module>
      
    • For Microsoft SQL server, get the Microsoft SQL driver sqljdbc4.jar and copy it to $WF_HOME/modules/com/microsoft/sqlserver/main.

      Also consider adding the sendStringParametersAsUnicode=false property.

      <module xmlns="urn:jboss:module:1.0" name="com.microsoft.sqlserver">
        <resources>
          <resource-root path="sqljdbc4.jar"/>
        </resources>
        <dependencies>
          <module name="javax.api"/>
          <module name="javax.transaction.api"/>
        </dependencies>
      </module>
      
    • For Oracle 11g, copy ojdbc6.jar to $WF_HOME/modules/com/oracle/jdbc/main
      <module xmlns="urn:jboss:module:1.0" name="com.oracle.jdbc">
        <resources>
          <resource-root path="ojdbc6.jar"/>
        </resources>
        <dependencies>
          <module name="javax.api"/>
          <module name="javax.transaction.api"/>
        </dependencies>
      </module>
      

    The module name will be used later for creating data source.

  4. Configure JMS in the server profile file (typically, $WF_HOME/standalone/configuration/standalone-full.xml):

    1. Set JMS to be persistent with <persistence-enabled>true</persistence-enabled>.
      <subsystem xmlns="urn:jboss:domain:messaging:3.0">
         <hornetq-server>
            <persistence-enabled>true</persistence-enabled>
            <journal-file-size>102400</journal-file-size>
       
            <connectors>
              <http-connector name="http-connector" socket-binding="http">
                 <param key="http-upgrade-endpoint" value="http-acceptor"/>
             </http-connector>
      
    2. Add queue and topic under jms-destinations:
      <jms-queue name="LSPS_QUEUE">
        <entry name="java:jboss/jms/LSPS_QUEUE"/>
      </jms-queue>
      <jms-topic name="LSPS_TOPIC">
        <entry name="java:jboss/jms/LSPS_TOPIC"/>
      </jms-topic>
      

    LSPS will use the default JMS connection factory.

  5. Configure your data source in the server profile file (typically, $WF_HOME/standalone/configuration/standalone-full.xml).

    The data source must be an XA-datasource with the transaction isolation TRANSACTION_READ_COMMITTED and the JNDI name must be jdbc/LSPS_DS.

    • For MySql, add the following under the data sources subsystem:
      <xa-datasource jndi-name="java:/jdbc/LSPS_DS" pool-name="LSPS_DS" enabled="true" use-java-context="false">
        <driver>mysqlxa</driver>
        <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/lsps?useUnicode=true&amp;characterEncoding=utf-8</xa-datasource-property>
        <security>
          <user-name>lsps</user-name>
          <password>lsps</password>
        </security>
        <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
        <xa-pool>
          <min-pool-size>10</min-pool-size>
          <max-pool-size>20</max-pool-size>
          <prefill>true</prefill>
        </xa-pool>
      </xa-datasource>
      
    • For Microsoft SQL server, add the following under the data sources subsystem:
        <xa-datasource jndi-name="java:/jdbc/LSPS_DS" pool-name="LSPS_DS" enabled="true" use-java-context="true">
          <driver>mssqlxa</driver>
          <xa-datasource-property name="URL">jdbc:sqlserver://localhost;databaseName=lsps</xa-datasource-property>
          <security>
            <user-name>lsps</user-name>
            <password>lsps</password>
          </security>
          <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
          <xa-pool>
            <min-pool-size>10</min-pool-size>
            <max-pool-size>20</max-pool-size>
            <prefill>true</prefill>
          </xa-pool>
          <new-connection-sql>select 1</new-connection-sql>
          <validation>
            <check-valid-connection-sql>select 1</check-valid-connection-sql>
          </validation>
        </xa-datasource>
      
    • For forOracle 11g XE server, add the following under data sources subsystem:
        <xa-datasource jndi-name="java:/jdbc/LSPS_DS" pool-name="LSPS_DS" enabled="true" use-java-context="true">
          <driver>oraclexa</driver>
          <xa-datasource-property name="URL">jdbc:oracle:thin:@localhost:1521:XE</xa-datasource-property>
          <security>
            <user-name>lsps</user-name>
            <password>lsps</password>
          </security>
          <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
          <xa-pool>
            <min-pool-size>10</min-pool-size>
            <max-pool-size>20</max-pool-size>
            <prefill>true</prefill>
          </xa-pool>
          <validation>
            <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/>
            <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker"/>
            <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/>
          </validation>
        </xa-datasource>
      
  6. In the <drivers> element, make sure to delete the h2 driver (driver with the name="h2" attribute) and add <driver> for your data source:
    • for MySql (make sure the driver is 5.5 compatible):
        <driver name="mysqlxa" module="com.mysql">
          <!-- for version 8: -->
          <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class>
        </driver>
      
    • for MSSql:
        <driver name="mssqlxa" module="com.microsoft.sqlserver">
          <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
        </driver>
      
    • for Oracle:
        <driver name="oraclexa" module="com.oracle.jdbc">
          <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
        </driver>
      
  7. Set Infinispan acquire-timeout setting to at least 5 minutes in your profile XML, such as standalone-full.xml. For details refer to the respective faq entry
       <local-cache name="passivation">
            <locking isolation="REPEATABLE_READ" acquire-timeout="600000"/>
            <transaction mode="BATCH"/>
            <file-store passivation="true" purge="false"/>
       </local-cache>
    </cache-container>
    
  8. Create a mail session with the JNDI name mail/LSPS_MAIL defined in $WF_HOME/standalone/configuration/standalone-full.xml or the respective WildFly config under the mail subsystem tag.
      <mail-session name="lspsmail" jndi-name="java:jboss/mail/LSPS_MAIL">
        <smtp-server outbound-socket-binding-ref="mail-smtp"/>
      </mail-session>
    

    Important: If you are using Microsoft Exchange Server as your mail server, make sure you have enabled the smtp feature.

  9. Set up the login module for the LSPS realm: add the following to the "security-domains" of the security subsystem tag in $WF_HOME/standalone/configuration/standalone-full.xml or the respective WildFly config referencing the security module from step 2:

    <security-domain name="lspsRealm" cache-type="default">
      <authentication>
        <login-module code="com.whitestein.lsps.security.jboss.LSPSRealm" flag="required" module="com.whitestein.lsps.security">
           <module-option name="dsJndiName" value="/jdbc/LSPS_DS"/>
        </login-module>
      </authentication>
    </security-domain>
    

    The attribute cache-type of the security-domain element turns on caching of user login data. As a side effect, changes to user credentials will not be used until after the cache is flushed; for example, if a user changes user's password through the web console but the user is already using PDS, they will be able to connect PDS to the server with the old credentials. You can turn the cache off by omitting the cache-type attribute of the security-domain element. The security domain definition will look as follows:

    <security-domain name="lspsRealm">
      <authentication>
        <login-module code="com.whitestein.lsps.security.jboss.LSPSRealm" flag="required" module="com.whitestein.lsps.security">
        <module-option name="dsJndiName" value="/jdbc/LSPS_DS"/>
        </login-module>
      </authentication>
    </security-domain>
    

    For additional module options, refer to the JavaDoc of the implementing class and super classes. You can also plug in your own authentication module.

  10. On Wildfly 8 and 9, enable stateless session beans pooling: on WF 10, the feature is enabled by default, see https://developer.jboss.org/message/881747)
    <session-bean>
      <stateless>
        <bean-instance-pool-ref pool-name="slsb-strict-max-pool"/>
      </stateless>
  11. Configure networking (optional).

    By default WildFly binds to the local host. You can change the configuration in $WF_HOME/standalone/configuration/standalone-full.xml (or the WildFly config you use). For example, to bind WildFly to any IPv4 address use the following setting:

      <interface name="management">
        <any-ipv4-address/>
      </interface>
      <interface name="public">
        <any-ipv4-address/>
      </interface>
      <interface name="unsecure">
        <any-ipv4-address/>
      </interface>
    
  12. Set up the WildFly option file in $WF_HOME/bin/standalone.conf (or the WildFly config you use; on Windows, standalone.conf.bat).
    1. Set up Java memory options:

      • minimum setting: JAVA_OPTS="-Xms128m -Xmx512m -XX:MaxPermSize=128m"
      • recommended setting: JAVA_OPTS="-Xms256m -Xmx1024m -XX:MaxPermSize=256m"

      JVM might require larger amount of memory depending on the uploaded and used LSPS modules.

    2. Set up the server startup configuration file to use (pointing to the configuration file you modified), e.g. for standalone-full.xml:
      JAVA_OPTS="$JAVA_OPTS -Djboss.server.default.config=standalone-full.xml"
    3. Add the following Java system properties to the config file, so it is added to the Java options passed to the JVM:
      • Configure EMF framework to work properly on WildFly.
        JAVA_OPTS="$JAVA_OPTS -Dorg.eclipse.emf.ecore.EPackage.Registry.INSTANCE=org.eclipse.emf.ecore.impl.EPackageRegistryImpl"
        
      • Configure the conversion of empty numeric inputs.
        JAVA_OPTS="-Dorg.apache.el.parser.COERCE_TO_ZERO=false $JAVA_OPTS"
        
        LSPS needs the system property org.apache.el.parser.COERCE_TO_ZERO to be set to "false" (see https://jsp-spec-public.dev.java.net/issues/show_bug.cgi?id=183). Without the property, empty input in numeric fields in the web application is interpreted as 0. This interpretation causes some functionalities not to work.
  13. Copy the LSPS Application EAR to $WF_HOME/standalone/deployments.
  14. Run WildFly.