Deployment

The build and deploy process for WComponents applications depends on the target container.

Running in a Servlet container

The easiest way to deploying a WComponents application as a Java web application is to create a WAR file containing the following:

• an extension of the WServlet class, to serve up the UI;
• the WComponents jar and its dependencies;
• a web.xml file which registers your application's WServlet extension and the auxilliary WComponents servlets; and
• the theme resources (JavaScript, CSS, etc.) and a configuration file to set the theme to be used.

The WAR file is essentially a Zip file containing all the application resources. This can be built manually using any zip tool but it is recommended that you use a build tool such as Maven. Automated builds are easier to run and are much less error-prone.

The suggested layout for simple the "MyApp" application from the last section is shown below:

MyApplication.war
|
|__ theme
|    |__ wcomponents-theme
|    |     |__  ...
|    |__ custom-theme
|          |__  ...
|
|__ WEB-INF
|__ classes
|     |__ wcomponents_app.properties
|     |__ com
|          |__ example
|               |__ myapp
|                    |__ MyApp$1.class
|                    |__ MyApp.class
|                    |__ MyAppServlet.class
|__ lib
|     |__ commons-beanutils.jar
|     |__ commons-collections-3.2.jar
|     |__ commons-configuration-1.6.jar
|     |__ commons-fileupload-1.2.jar
|     |__ commons-io-1.3.1.jar
|     |__ commons-lang-2.3.jar
|     |__ commons-logging.jar
|     |__ velocity-dep-1.4.jar
|     |__ wcomponents.jar
|
|__ web.xml

The classes directory contains your application classes. Note that a WComponents application requires both a top-level component (MyApp) an extension of WServlet (MyAppServlet) to serve it.

The lib directory contains all the WComponents dependencies if they are not already present elsewhere in the container's classpath.

The web.xml file in the WebContent/WEB-INF directory is the web application descriptor and contains all the information required for the Servlet container to run your application. Your main application's servlet is registered in it. An example web.xml file is shown below.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
  "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app id="MyWebApp_ID">
  <display-name>My WebApp</display-name>

  <!-- Your extension of WServlet -->
  <servlet>
    <servlet-name>myAppServlet</servlet-name>
    <servlet-class>com.example.myapp.MyAppServlet</servlet-class>
  </servlet>

  <!-- Your servlet's mapping -->
  <servlet-mapping>
    <servlet-name>myAppServlet</servlet-name>
    <url-pattern>/app</url-pattern>
  </servlet-mapping>
</web-app>

The "theme" directory contains the resources required for the client-side theme. The resources for all themes can be found the WComponents distribution package. In the WAR file example above two themes have been included: "wcomponents-theme" and "custom-theme".

Note that by default WServlet expects the theme files to be located at the absolute path "/theme" rather than in the application you are deploying. You will need to override this and explicitly set which theme to use by including a properties file "wcomponents_app.properties" in the classes directory. With the WAR file layout given above the parameter would be set as follows for the "wcomponents-theme" theme:

bordertech.wcomponents.theme.content.path=theme/wcomponents-theme

This will configure the WServlet to point at the default theme, relative to the application which was deployed. To use a different theme, e.g. the "custom-theme", the parameter would be changed to:

bordertech.wcomponents.theme.content.path=theme/custom-theme

If you have multiple WComponents applications and wish to enforce a common theme for them all you may wish to deploy the theme as a separate WAR instead. Use an absolute path to use a theme deployed to another application context:

bordertech.wcomponents.theme.content.path=/anotherContext/theme-name

Using the default theme

If you are using the default WComponents theme you do not need to extract the static theme resources and place them in your WAR file. The WComponents library includes a "ThemeServlet" which can be used to serve up the static resources from within the WComponents jar file.

All that needs to be done to use the internal theme is to declare the ThemeServlet servlet declaration and mapping in your XML file then set the theme path parameter to point to the servlet relative to your application.

Servlet declaration:

<servlet>
  <servlet-name>themeServlet</servlet-name>
  <servlet-class>com.github.bordertech.wcomponents.servlet.ThemeServlet</servlet-class>
</servlet>

<servlet-mapping>
  <servlet-name>themeServlet</servlet-name>
  <url-pattern>/theme/*</url-pattern>
</servlet-mapping>

Configuration parameter:

bordertech.wcomponents.theme.content.path=theme