JBoss

Setting up JBoss Enterprise Application Platform 7.0.0 with LSPS Application

Important: It is strongly discouraged to run other applications on JBoss Enterprise Application Platform (EAP) with LSPS since LSPS is using a customized Hibernate.

To set up JBoss EAP 7.0.0 with LSPS, do the following:

1. Install JBoss EAP.
2. Create JBoss module with the LSPS login module:
   1. Copy lsps-security-jboss-${lsps.version}.jar to $EAP_HOME/modules/com/whitestein/lsps/security/main.
   2. Create the file $EAP_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 JBoss 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>-.jar to $EAP_HOME/modules/com/mysql/main. Then create $EAP_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-8.0.15.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 $EAP_HOME/modules/com/microsoft/sqlserver/mainr. Additional steps may be required to enable the XA transaction support on Microsoft SQL server. Refer to the relevant Microsoft documentation for information on your version of Microsoft SQL server and JDBC driver; for example, for Windows Server 2003 and sqljdbc4.jar, refer to http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=11774 and http://msdn.microsoft.com/en-US/library/aa342335(v=sql.90). You may also need to install MSDTC in Windows (Add/remove Windows components -> Application Server -> Details -> Enable network DTC access).

     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 $EAP_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, $EAP_HOME/standalone/configuration/standalone-full.xml):
   1. Set JMS to persist messages: <server name="default" persistence-enabled="true">
   2. Add queue and topic under messaging-activemq -> server:

      <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, $EAP_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</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 for Oracle 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> referred to from the data source definition:
   • 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>
     

   • Delete driver with name="h2".
7. Consider adding logging.properties for better log legibility:

   # Specify the handlers to create in the root logger
   # (all loggers are children of the root logger)
   # The following creates two handlers
   handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler
   
   # Set the default logging level for the root logger
   .level = WARN
   
   # Set the default logging level for new ConsoleHandler instances
   java.util.logging.ConsoleHandler.level = ALL
   
   # Set the default logging level for new FileHandler instances
   java.util.logging.FileHandler.level = ALL
   
   # Set the default formatter for new ConsoleHandler instances
   java.util.logging.ConsoleHandler.formatter = com.whitestein.lsps.log.LSPSFormatter
   
   # Set the default formatter for new FileHandler instances
   java.util.logging.FileHandler.formatter = com.whitestein.lsps.log.LSPSFormatter
   
   # Set the logging level for the LSPS
   com.whitestein.lsps.level = FINER

8. Set up the login module for the LSPS realm: add the following to the "security-domains" of the security subsystem tag in $EAP_HOME/standalone/configuration/standalone-full.xml or the respective JBoss 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.

9. Configure bean pools.

   The application requires configuration of bean and data source connection pools. The configuration depends on the expected load as well as other performance parameters. You can change the configuration in the $EAP_HOME/standalone/configuration/standalone-full.xml or the respective JBoss config.

   • Limit the MDB pool and the default pool used for timers, async, and remoting.
   • Extend the SLSB pool to 10 * (MDB pool size + default pool size) at least .
   • Adapt the acquisition timeouts to reasonable values to prevent long waiting deadlocks in case of lack of resources. Set data-source connection pool the maximum to MDB pool size + the default pool size at least. For example:

     <bean-instance-pools>
       <!-- A sample strict max pool configuration -->
       <strict-max-pool name="slsb-strict-max-pool" max-pool-size="200" instance-acquisition-timeout="5" instance-acquisition-timeout-unit="MINUTES"/>
       <strict-max-pool name="mdb-strict-max-pool" max-pool-size="20" instance-acquisition-timeout="5" instance-acquisition-timeout-unit="MINUTES"/>
      
       <thread-pools>
         <thread-pool name="default">
           <max-threads count="10"/>
     

10. Configure networking (optional).

    By default JBoss binds to the local host. You can change the configuration in $EAP_HOME/standalone/configuration/standalone-full.xml (or the JBoss config you use). For example, to bind JBoss 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 JBoss option in $EAP_HOME/bin/standalone.conf (or the JBoss config you use).

    1. Set up Java memory options:

       • minimum setting: JAVA_OPTS="-Xms128m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m * recommended setting: JAVA_OPTS="-Xms256m -Xmx1024m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=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:
       1. Configure EMF framework to work properly on JBoss:

          JAVA_OPTS="$JAVA_OPTS -Dorg.eclipse.emf.ecore.EPackage.Registry.INSTANCE=org.eclipse.emf.ecore.impl.EPackageRegistryImpl"
          

       2. 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.
12. Deploy the LSPS Application EAR to the server.
    • To deploy the default LSPS Application, deploy lsps-application-<VERSION>.ear located in the lsps-runtime directory.
    • To create and deploy a customized LSPS Application, install PDS with SDK and proceed as instructed here.
13. Create a mail session with the JNDI name mail/LSPS_MAIL defined in $EAP_HOME/standalone/configuration/standalone-full.xml or the respective JBoss 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>
    

14. Run JBoss.

    $EAP_HOME/bin/standalone.sh

15. Open your browser and go to url http://localhost:8080/lsps-application
16. Authenticate with the credentials:
    • user: admin
    • password: admin
17. To shut down JBoss, use the command-line administration client:

    $EAP_HOME/bin/jboss-cli.sh --connect :shutdown

18. Optional: Hide useless vaadin warning from the log:

    <logger category="com.vaadin.ui.ConnectorTracker" use-parent-handlers="true">
       <level name="ERROR"/>
    </logger>
    

Setting up JBoss Enterprise Application Platform 6.4.0 with LSPS Application

Important: It is strongly discouraged to run other applications on JBoss Enterprise Application Platform (EAP) with LSPS since LSPS is using a customized Hibernate.

To set up JBoss EAP 6.4.0 with LSPS, do the following:

1. Install JBoss EAP.
2. Create JBoss module with the LSPS login module:
   1. Copy lsps-security-jboss-${lsps.version}.jar to $EAP_HOME/modules/com/whitestein/lsps/security/main.
   2. Create the file $EAP_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 JBoss 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>.jar to $EAP_HOME/modules/com/mysql/main. Then create $EAP_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-8.0.15.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 $EAP_HOME/modules/com/microsoft/sqlserver/mainr. Additional steps may be required to enable the XA transaction support on Microsoft SQL server. Refer to the relevant Microsoft documentation for information on your version of Microsoft SQL server and JDBC driver; for example, for Windows Server 2003 and sqljdbc4.jar, refer to http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=11774 and http://msdn.microsoft.com/en-US/library/aa342335(v=sql.90). You may also need to install MSDTC in Windows (Add/remove Windows components -> Application Server -> Details -> Enable network DTC access).

     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 $EAP_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, $EAP_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, $EAP_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</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 for Oracle 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> referred to from the datasource definition:
   • 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>
     

   • Delete driver with name="h2".
7. Consider adding logging.properties for better log legibility:

   # Specify the handlers to create in the root logger
   # (all loggers are children of the root logger)
   # The following creates two handlers
   handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler
   
   # Set the default logging level for the root logger
   .level = WARN
   
   # Set the default logging level for new ConsoleHandler instances
   java.util.logging.ConsoleHandler.level = ALL
   
   # Set the default logging level for new FileHandler instances
   java.util.logging.FileHandler.level = ALL
   
   # Set the default formatter for new ConsoleHandler instances
   java.util.logging.ConsoleHandler.formatter = com.whitestein.lsps.log.LSPSFormatter
   
   # Set the default formatter for new FileHandler instances
   java.util.logging.FileHandler.formatter = com.whitestein.lsps.log.LSPSFormatter
   
   # Set the logging level for the LSPS
   com.whitestein.lsps.level = FINER

8. Create a mail session with the JNDI name mail/LSPS_MAIL defined in $EAP_HOME/standalone/configuration/standalone-full.xml or the respective JBoss 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 $EAP_HOME/standalone/configuration/standalone-full.xml or the respective JBoss 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 bean pools.

    The application requires configuration of bean and data source connection pools. The configuration depends on the expected load as well as other performance parameters. You can change the configuration in the $EAP_HOME/standalone/configuration/standalone-full.xml or the respective JBoss config.

    • Limit the MDB pool and the default pool used for timers, async, and remoting.
    • Extend the SLSB pool to 10 * (MDB pool size + default pool size) at least .
    • Adapt the acquisition timeouts to reasonable values to prevent long waiting deadlocks in case of lack of resources. Set the data-source connection pool maximum to MDB pool size + the default pool size at least, for example:

      <bean-instance-pools>
        <!-- A sample strict max pool configuration -->
        <strict-max-pool name="slsb-strict-max-pool" max-pool-size="200" instance-acquisition-timeout="5" instance-acquisition-timeout-unit="MINUTES"/>
        <strict-max-pool name="mdb-strict-max-pool" max-pool-size="20" instance-acquisition-timeout="5" instance-acquisition-timeout-unit="MINUTES"/>
       
        <thread-pools>
          <thread-pool name="default">
            <max-threads count="10"/>
      

11. Configure networking (optional).

    By default JBoss binds to the local host. You can change the configuration in $EAP_HOME/standalone/configuration/standalone-full.xml (or the JBoss config you use). For example, to bind JBoss 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>
    

12. Set up the JBoss option in $EAP_HOME/bin/standalone.conf (or the JBoss config you use).

    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:
       1. Configure EMF framework to work properly on JBoss:

          JAVA_OPTS="$JAVA_OPTS -Dorg.eclipse.emf.ecore.EPackage.Registry.INSTANCE=org.eclipse.emf.ecore.impl.EPackageRegistryImpl"
          

       2. 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. Deploy the LSPS Application to $EAP_HOME/standalone/deployments:
    • To deploy the default LSPS Application, deploy lsps-application-<VERSION>.ear located in the lsps-runtime directory.
    • To create and deploy a customized LSPS Application, install PDS with SDK and proceed as instructed here.
14. Run JBoss.

    $EAP_HOME/bin/standalone.sh

15. Open your browser and go to url http://localhost:8080/lsps-application
16. Authenticate with the credentials:
    • user: admin
    • password: admin
17. To shut down JBoss, use the command-line administration client:

    $EAP_HOME/bin/jboss-cli.sh --connect :shutdown

18. Optionally, exclude the useless vaadin warning from the log:

    <logger category="com.vaadin.ui.ConnectorTracker" use-parent-handlers="true">
       <level name="ERROR" />
    </logger>
    

Troubleshooting Data Source

XAException on Oracle 10g R2 or 11g

The server returns the following XA exception:

WARN  [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery got XA exception javax.transaction.xa.XAException, XAException.XAER_RMERR

To remedy the situation, do the following:

• For Oracle, make sure the Oracle user has access to the appropriate tables so they can accomplish the recovery:

  GRANT SELECT ON sys.dba_pending_transactions TO user;
  GRANT SELECT ON sys.pending_trans$ TO user;
  GRANT SELECT ON sys.dba_2pc_pending TO user;
  GRANT EXECUTE ON sys.dbms_xa TO user;

The above assumes that the user is the user defined to connect from JBoss to Oracle. It also assumes that either Oracle 10g R2 (patched for bug 5945463) or 11g is used. If an unpatched version, that is, a version older that 11g, is used, change the last GRANT EXECUTE to the following:

GRANT EXECUTE ON sys.dbms_system TO user;

InvalidConnectionAttributeException with MySQL

If on MySQL with the JDBC driver, you might get the following exception:

Caused by: com.mysql.cj.exceptions.InvalidConnectionAttributeException:
The server time zone value 'CEST' is unrecognized or represents more than one time zone.
You must configure either the server or JDBC driver (via the serverTimezone configuration property)
to use a more specific time zone value if you want to utilize time zone support.

To remedy the situation, set the time zone:

• in the database if one timezone is required, for example, `SET GLOBAL time_zone = '+3:00';`
• in the data source URL if multiple zones are required, for example,

  <xa-datasource-property
     name="URL">jdbc:mysql://localhost:3306/lsps?
                 useUnicode=true&
                 characterEncoding=utf-8
                 &useJDBCCompliantTimezoneShift=true
                 &useLegacyDatetimeCode=false
                 &serverTimezone=UTC
  </xa-datasource-property>