Standalone Servers and Managed Domains

In JBoss Enterprise Application Platform 6, deployment configuration is done using one file. This file is used to configure all the services and subsystems used for the deployment.

• A standalone server is configured using the JBOSS_HOME/standalone/configuration/standalone.xml file.

• For servers running in a managed domain, the server is configured using the JBOSS_HOME/domain/configuration/domain.xml file.

Ordering of deployments

JBoss EAP 6 uses fast, concurrent initialization for deployment resulting in improved performance and efficiency. In most cases, the application server is able to automatically determine dependencies in advance and choose the most efficient deployment strategy. However, JBoss Enterprise Application Platform 5 applications that consist of multiple modules deployed as EARs and use legacy JNDI lookups instead of CDI injection or resource-ref entries may require configuration changes.

Archive Packaging and Assembly

The following are general rules for assembly of archives or directories that will be deployed to JBoss EAP 6:

• Archives may be nested within other archived deployments.

• Extracted directories may be nested in extracted deployments.

• Archives may be nested in extracted deployments.

• Extracted directories may NOT be nested in archived deployments. You must recreate archives for the nested artifacts.

• In WebSphere, an extracted WAR, EAR, or other archive can be deployed without the archive extension in the directory name. In JBoss, the extension must appear on the extracted directory name, for example myEnterpriseApp.ear or myWebApp.war.Extracted WAR, EAR, or other archive directories must contain archive extension on the folder name, for example myEnterpriseApp.ear or myWebApp.war.

• For web applications, it is generally better to avoid the use of a web.xml file if possible. If this file is required, it should be located under the root of the application WEB-INF/ directory.

• If your enterprise applications requires an application.xml file, it should be located under the META-INF/ directory in the root of the EAR.

Static Modules

Static Modules are predefined in the JBOSS_HOME/modules/ directory of the application server. Each sub-directory represents one module and contains one or more JAR files and a configuration file (module.xml). The name of the module is defined in the module.xml file. All the application server provided APIs are provided as static modules, including the Java EE APIs as well as other APIs such as JBoss Logging. The following is an example module.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-5.1.15.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

The module name, com.mysql, should match the directory structure for the module.

Creating custom static modules can be useful if many applications are deployed on the same server that use the same third party libraries. Instead of bundling those libraries with each application, a module containing these libraries can be created and installed by the JBoss administrator. The applications can then declare an explicit dependency on the custom static modules.

Dynamic Modules

Dynamic Modules are created and loaded by the application server for each JAR or WAR deployment, or subdeployment in an EAR. The name of a dynamic module is derived from the name of the deployed archive. Because deployments are loaded as modules, they can configure dependencies and be used as dependencies by other deployments.

Modules are only loaded when required. This usually only occurs when an application is deployed that has explicit or implicit dependencies.

For more information on modular class loading, see see Class Loading and Modules in the Development Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal.

autoresponseEncoding and autorequestEncoding

In WebSphere, the Web container does not automatically set request and response encodings and response content types. If a programmer needs to change the encoding value from the Servlet 2.3 default of "ISO-8859-1", the autoResponseEndcoding and autoRequestEncoding extensions are set to true to enable the server to set the encoding value and content type.

These values are specified in the ibm-web-ext.xmi file as:
autoResponseEncoding="true"
autoRequestEncoding="true"

In JBoss, you can you can override the character encoding used to decode the URI bytes in one of the following ways:

1. You can set the encoding at a server level by running the following in the Management CLI:

   /system-property=org.apache.catalina.connector.URI_ENCODING:add(value=UTF-8)
   /system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:add(value=true)

2. You can use the javax.servlet.Filter class to enforce character encoding for specific request and response content:

   public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
     response.setContentType("text/html; charset=UTF-8");
     request.setCharacterEncoding("UTF-8");
     response.setCharacterEncoding("UTF-8");
     chain.doFilter(request, response);
   }

reloadingEnabled and reloadInterval

WebSphere uses these properties to enable automatic reloading of web applications when application files have changed.

In JBoss EAP 6, automatic reloading is configured in the 'deployment-scanner' subsystem of the server configuration file. You can enable automatic deployment of exploded archives and set the timer interval to check for updated files. You can also configure the server to monitor deployments to external directories. For more information, see the section 'Deploy with the Deployment Scanner' in the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal.

You can use the JBoss Management CLI to modify the deployment-scanner configuration settings. The following examples show how modify and view the current deployment-scanner settings.

1. Enable the automatic deployment of an exploded archive and specify the scanner interval time in milliseconds to check for file updates

   1. Connect to JBoss server using the Management CLI
      Open a terminal and type the following to connect to the JBoss server.
      For Linux, enter the following at the command line:

      $ JBOSS_HOME/bin/jboss-cli.sh --connect

      For Windows, enter the following at a command line:

      C:\>JBOSS_HOME\bin\jboss-cli.bat --connect

      You should see the following response:

      Connected to standalone controller at localhost:9999

   2. Navigate to the default scanner in the 'deployment-scanner' subsystem:

      cd subsystem=deployment-scanner/scanner=default

   3. Type the following command to set the 'auto-deploy-exploded' attrbute to 'true'.

      :write-attribute(name=auto-deploy-exploded,value=true)

      You should see the following response:

      {
          "outcome" => "success",
      }

   4. Specify the scanner interval in milliseconds between checks for file updates.

      :write-attribute(name=scan-interval,value=10000)

      You should see the following response:

      {
          "outcome" => "success",
      }

2. To track a specific external folder for updates, issue the following command:

   :write-attribute(name=path,value=home/username/external-deployments)

   You should see the following response:

   {
       "outcome" => "success",
       "response-headers" => {
           "operation-requires-reload" => true,
           "process-state" => "reload-required"
       }
   }

3. To view the current setting in the Managment CLI, type:

   :read-resource

   You should see:

   {
       "outcome" => "success",
       "result" => {
           "auto-deploy-exploded" => true,
           "auto-deploy-xml" => true,
           "auto-deploy-zipped" => true,
           "deployment-timeout" => 60,
           "path" => "home/username/external-deployments",
           "relative-to" => "jboss.server.base.dir",
           "scan-enabled" => true,
           "scan-interval" => 10000
       }
   }

4. After you run the above commands, the 'deployment-scanner' subsystem in the server configuration file now contains the new attribute value.

   <subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
       <deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="10000" auto-deploy-exploded="true"/>
   </subsystem>

For information on how to configure the server to monitor updates to JSP files, see the section on jspAttributes below.

autoLoadFilters

This WebSphere setting specifies whether filters should be loaded on the startup of a web module. JBoss EAP 6 automatically loads filters on startup so there is no equivalent configuration.

mimeFilters

WebSphere provides MIME filters that can direct requests to URIs within the web application based on the content type of the request. To provide similar functionality in JBoss EAP 6, you write a custom servlet filter, then specify it in the standard web.xml file.

fileServingAttributes

The WebSphere file serving attribute properties define the behavior of how the web container serves files. These properties include the buffer size used by the web container for file serving. There are no equivalent settings for input and output buffer sizing in JBoss EAP 6.

directoryBrowsingEnabled

This WebSphere attribute allows directory browsing from within the application. For security reasons, this feature is disabled by default in JBoss EAP 6. It can be reenabled by adjusting the configuration of the web subsystem as follows.

To modify the setting for a Standalone server using the JBoss Management CLI, type the following:

/subsystem=web/configuration=static-resources/:write-attribute(name=listings,value=true)

To modify the setting for a managed domain using the JBoss Management CLI, type the following::
You should see the following response:

/profile=full/subsystem=web/configuration=static-resources/:write-attribute(name=listings,value=true)

serveServletsByClassnameEnabled

This WebSphere attribute allows servlets to be served by fully-qualified classname. There is no equivalent setting in JBoss EAP 6.

jspAttributes

Websphere uses this setting to configure JSP attributes.

In JBoss EAP 6, the following JSP attributes are configured in the <jsp-configuration> element of the 'web' subsystem in the server configuration file.

The following example shows how to use the JBoss Management CLI to set or change a JSP attribute.

1. Connect to JBoss server using the Management CLI
   Open a terminal and type the following to connect to the JBoss server.
   For Linux, enter the following at the command line:

   $ JBOSS_HOME/bin/jboss-cli.sh --connect

   For Windows, enter the following at a command line:

   C:\>JBOSS_HOME\bin\jboss-cli.bat --connect

   You should see the following response:

   Connected to standalone controller at localhost:9999

2. Enable development mode

   /subsystem=web/configuration=jsp-configuration:write-attribute(name=development,value=true)

   You should see the following response:

   {
       "outcome" => "success",
       "response-headers" => {
           "operation-requires-reload" => true,
           "process-state" => "reload-required"
       }
   }

3. Set the scan interval to detect JSP file changes:

   /subsystem=web/configuration=jsp-configuration/:write-attribute(name=check-interval,value=30)

   You should see the following response:

   {
       "outcome" => "success",
       "response-headers" => {
           "operation-requires-reload" => true,
           "process-state" => "reload-required"
       }
   }

4. Reload the server configuration

   :reload

   You should see the following response:

   {
       "outcome" => "success",
       "response-headers" => {"process-state" => "reload-required"}
   }

5. To view the current settings in the Management CLI, navigate to the 'web' subsystem 'jsp-configuration'

   cd subsystem=web/configuration=jsp-configuration

   Then type the following command:

   :read-resource

   You should see the following response:

   {
       "outcome" => "success",
       "result" => {
           "check-interval" => 30,
           "development" => true,
           "disabled" => false,
           "display-source-fragment" => true,
           "dump-smap" => false,
           "error-on-use-bean-invalid-class-attribute" => false,
           "generate-strings-as-char-arrays" => false,
           "java-encoding" => "UTF8",
           "keep-generated" => true,
           "mapped-file" => true,
           "modification-test-interval" => 4,
           "recompile-on-fail" => false,
           "scratch-dir" => undefined,
           "smap" => true,
           "source-vm" => "1.5",
           "tag-pooling" => true,
           "target-vm" => "1.5",
           "trim-spaces" => false,
           "x-powered-by" => true
       }
   }

6. The 'web' subsystem in the server configuration file now contains the new attribute value.

   <subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">
       <configuration>
           <jsp-configuration development="true" check-interval="30"/>
       </configuration>
       <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
       <virtual-server name="default-host" enable-welcome-root="true">
           <alias name="localhost"/>
           <alias name="example.com"/>
       </virtual-server>
   </subsystem>

defaultErrorPage

This WebSphere attribute specifies the URI of a page or servlet to use as the default error page for the web application.

JBoss EAP 6 supports the standard Java Servlet 3.0 specification, so you simply define the <error-page> in the web.xml file as follows:

<error-page>
   <location>/general-error.html</location>
</error-page>

servletCacheConfigs

WebSphere provides configuration for caching the output of servlets and JSP pages to its dynamic cache. To provide similar functionality in JBoss EAP 6 you use simple ServletFilter and caching provider, such as Infinispan.

additionalClasspath

This property allows users to specify an additional classpath to reference resources outside the WEB-INF/ directory.

JBoss EAP 6 uses a modular class loading system. You can use the jboss-deployment-structure.xml file or define a custom module to load class dependencies that are external to the deployment. For more information, see the section entitled Create or Modify Files That Control Class Loading in JBoss EAP in the Migration Guide for JBoss Enterprise Application Platform located on the Customer Portal.

web.xml

The web.xml file, located in the WEB-INF/ directory, is the standard Java EE deployment descriptor for a web application. This file is often no longer required since the Servlet 3.0 specification was released. If it is defined, it must not contain specific vendor information since it must be portable across different application servers.

References to JDBC, Mail and JMS resources can be defined in the web.xml file. However, the mapping of the resource name to the JNDI binding defined in JBoss is configured in the jboss-web.xml file. This is done using a <resource-ref> element in the jboss-web.xml deployment descriptor. For example, to reference the 'DefaultDS' datasource defined in the jboss-web.xml configuration, you use add the following code to the web.xml file:

<resource-ref>
    <description>The default DS</description>
    <res-ref-name>jdbc/DefaultDS</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
</resource-ref>

jboss-web.xml

The jboss-web.xml configuration file, located in the WEB-INF/ directory, contains JBoss specific JNDI mapping information. This configuration file can be used in conjunction with the web.xml file to map JBoss specific services to their JNDI names in the JBoss environment. The <resource-ref> element in the jboss-web.xml file maps to the <resource-ref> element defined in the web.xml file.

The following code in the jboss-web.xml file maps the JDBC datasource to the web.xml file example:

<resource-ref>
    <res-ref-name>jdbc/DefaultDS</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <jndi-name>java:global/DefaultDS</jndi-name>
</resource-ref>

jboss-deployment-structure.xml

This file is a JBoss specific deployment descriptor that can provide fine grained control over class loading in a deployment. This file can be used to add explicit dependencies, prevent automatic loading of implicit dependencies, define additional modules from the resources of that deployment, change the subdeployment isolated class loading behavior in an EAR's deployment, and add additional resource roots to a module in an EAR.

The following is an example of a jboss-deployment-structure.xml file that adds a dependency for JSF 1.2 module and prevents the automatic loading of the JSF 2.0 module.

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
    <deployment>
        <dependencies>
            <module name="javax.faces.api" slot="1.2" export="true"/>
                <module name="com.sun.jsf-impl" slot="1.2" export="true"/>
        </dependencies>
    </deployment>
    <sub-deployment name="jboss-seam-booking.war">
        <exclusions>
            <module name="javax.faces.api" slot="main"/>
                <module name="com.sun.jsf-impl" slot="main"/>
        </exclusions>
        <dependencies>
            <module name="javax.faces.api" slot="1.2"/>
            <module name="com.sun.jsf-impl" slot="1.2"/>
        </dependencies>
    </sub-deployment>
</jboss-deployment-structure>

server.xml

ToDo: this section needs content