LSPS documentation logo
LSPS Documentation
Setting up WildFly 11.0.0 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 11.0.0 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. Then create $WF_HOME/modules/com/microsoft/sqlserver/main/module.xml with following content:
        <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>
      Also consider adding the sendStringParametersAsUnicode=false property.
    • 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>
    • For DB2, copy jcc-11.5.0.0.jar to $WF_HOME/modules/com/ibm/db2/main
        <module xmlns="urn:jboss:module:1.0" name="com.ibm.db2">
          <resources>
            <resource-root path="jcc-11.5.0.0.jar"/>
          </resources>
          <dependencies>
            <module name="javax.api"/>
            <module name="javax.transaction.api"/>
          </dependencies>
        </module>
  4. Configure JMS in the server profile file (typically, $WF_HOME/standalone/configuration/standalone-full.xml):

    1. Set JMS to be persistent: <server name="default" persistence-enabled="true">.
    2. Add queue and topic under messaging-activemq -> server:
      <jms-queue name="LSPS_QUEUE" entries="java:jboss/jms/LSPS_QUEUE"/>
      <jms-topic name="LSPS_TOPIC" entries="java:jboss/jms/LSPS_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&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 DB2, 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>db2xa</driver>
          <xa-datasource-property name="User">lsps</xa-datasource-property>
          <xa-datasource-property name="Password">lsps</xa-datasource-property>
          <xa-datasource-property name="DatabaseName">lsps</xa-datasource-property>
          <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
          <xa-datasource-property name="PortNumber">5000</xa-datasource-property>
          <xa-datasource-property name="progressiveStreaming">2</xa-datasource-property>
          <xa-datasource-property name="progressiveLocators">2</xa-datasource-property>
          <xa-datasource-property name="fullyMaterializedLobData">true</xa-datasource-property>
          <xa-datasource-property name="fullyMaterializedInputStreams">true</xa-datasource-property>
          <xa-datasource-property name="downgradeHoldCursorsUnderXa">true</xa-datasource-property>
          <xa-datasource-property name="resultSetHoldabilityForCatalogQueries">1</xa-datasource-property>
          <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
          <security>
            <user-name>lsps</user-name>
            <password>lsps</password>
          </security>
          <xa-pool>
            <min-pool-size>10</min-pool-size>
            <max-pool-size>20</max-pool-size>
            <prefill>true</prefill>
          </xa-pool>
        </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:
        <driver name="mysqlxa" module="com.mysql">
          <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>
    • for DB2:
        <driver name="db2xa" module="com.ibm.db2">
          <xa-datasource-class>com.ibm.db2.jcc.DB2XADataSource</xa-datasource-class>
        </driver>
    • Delete the h2 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>
  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. 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-address/>
      </interface>
      <interface name="public">
        <any-address/>
      </interface>
      <interface name="unsecure">
        <any-address/>
      </interface>
  11. Set up the WildFly option in $WF_HOME/bin/standalone.conf (or the WildFly config you use).
    1. Set up Java memory options:

      • minimum setting: JAVA_OPTS="-Xms128m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=512m"
      • recommended setting: JAVA_OPTS="-Xms256m -Xmx1024m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=512m"

      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"
        Without this configuration property, the LSPS application will fail to run properly.
      • Configure 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.
  12. Copy the LSPS Application EAR to $WF_HOME/standalone/deployments.
  13. Run WildFly.