Weblets Setup Guide

One goal which Weblets tries to achieve is to support as many web frameworks as possible to achieve this, currently in Weblets 1.0 two configuration options are supported.

Manual Configuration via web.xml configured servlets

To achieve the maximum compatibility with all existing frameworks an optional weblets servlet configuration is supported. Following code showcases such a servlet configuration

Code 0: Weblets servlet web.xml

    <?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>
      <description>Weblets Demo</description>


      <servlet>
        <servlet-name>Weblets Servlet</servlet-name>
        <servlet-class>net.java.dev.weblets.WebletsServlet</servlet-class>
      </servlet>


      <!-- The  Weblets servlet mapping must be path based otherwise  Weblets will fail! -->
      <servlet-mapping>
        <servlet-name>Weblets Servlet</servlet-name>
        <url-pattern>/weblets/*</url-pattern>
      </servlet-mapping>


    </web-app>

This is probably the most basic generic configuration which is possible. Note this configuration has one limitation

Code 2: Configuration limitation

  <!-- The  Weblets servlet mapping must be path based otherwise Weblets will fail! -->
  <servlet-mapping>
    <servlet-name>Weblets Servlet</servlet-name>
    <url-pattern>/weblets/*</url-pattern>
  </servlet-mapping>

Path based url pattern must be provided, otherwise Weblets will fail.

`Weblets` Basic configuration and the context path

Now we have a second limitation, Weblets internally tries to discover the webapps context path. This works properly in JSF and in JEE5 , in JEE4 and earlier there is no clean way to determine it.

Weblets has two optional configuration entries to overcome this Problem

Configuration Option 1, a Filter

The first method to enable a clear webapp context path resolution is to add a filter which Weblets optionally provides.

Code 3: Weblets Filter

 <filter>
      <filter-name>WebletsContextFilter</filter-name>
      <filter-class>net.java.dev.weblets.WebletsContextFilter</filter-class>
  </filter>
  <filter-mapping>
      <filter-name>WebletsContextFilter</filter-name>
      <url-pattern>*.jsp</url-pattern>
  </filter-mapping>
  <filter-mapping>
      <filter-name>WebletsContextFilter</filter-name>
      <url-pattern>*.jspx</url-pattern>
  </filter-mapping>

Note this filter is fully triggered only once, it tries to discover the context path and stores it in the Weblets container, so that it later can be used internally, after that it deactivates itself. Hence the performance impact is neglectable.

Though it is important that the filter is triggered before the first weblet:url resolution command is issued. Therefore it makes sense to put the filter over every active dynamic type which also triggers a servlet. (The provided default mapping above should take care of most use cases)

Configuration Option 1, a Context Parameter
The sheer number of web frameworks in the java realm simply makes it impossible to exactly determine every way the context path can be resolved. Standard methods might not work in portlet environments for instance or other frameworks enforce different mapping schemes. To cover such instances, weblet provides a second generic configuration option.

Code 4: Weblets Filter
```
 <context-param>
      <param-name>net.java.dev.weblets.contextpath</param-name>
      <param-value>/weblets-demo/</param-value>
  </context-param>
```
This optional context parameter overrides any locally determined webapp context value. It simply is an override for all cases in existence.
Every weblet url request will default to
```
    /weblets-demo/<path to the weblet resource/
```
in this case. So, if all other methods of context discovering fail, this one will work!

Manual Configuration in a `JSF` System

Weblets tries to cover the automatisms provided by JSF. Hence the configuration is easier in such systems.

Code 5: <<<JSF >> Specific web.xml >

<?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>
  <description>Weblets Demo</description>

  <servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>


  <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
  </servlet-mapping>


  <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>*.jsf</url-pattern>
  </servlet-mapping>

</web-app>

As you can see there is no Weblets specific part, there is no need to add additional context discovering tools to the web.xml. All is done automatically. However also in JSF one limitation still exists.

Limitations of the `JSF` configuration

Just as in the generic configuration, Weblets only allows path patterns. Hence

Code 6: <<<JSF >> Specific mapping patterns >

  <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
  </servlet-mapping>


  <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>*.jsf</url-pattern>
  </servlet-mapping>

The /faces/* pattern has to be set, Weblets automatically will use this one for its internal url mapping. The *.jsf pattern can be set and used also, Weblets simply will ignore it, JSF wont!

I have setup everything but Weblets still fails with internal errors

Some environments do not trigger the internal context listener automatically. Weblets uses an internal context listener for preinitialisation, if the weblet startup fails you might get some internal weblet errors during runtime. If it fails you should try to add

  <listener>
        <listener-class>net.java.dev.weblets.WebletsContextListener</listener-class>
  </listener>

To your local web.xml, this will ensure that the context listener is called, in any condition. This problem could be confirmed in certain portlet environments, so if you use weblets in a portlet environment it should work but you might have to add the context listener!

Special configurations

Weblets in a portlet environment

As of 1.0 Weblets 1.0 can be embedded in Portlet Specification 1.0 enabled portlet containers.

You do not have to take too many considerations to embed it both methods the Weblet Servlet and the Faces Servlet based environments should work.

Internally portlet triggers both servlets outside of the portlet scope and lets the servlets deliver the webapp just like they would be from a standalone application if your firewall or container tries to prevent this, you have to enable it!

Weblets in a BEA Server

Weblets has not been explicitely tested against BEA app servers, (every servlet spec 2.4 enabled app server should do however one user has reported a successful configuration. However as it seems the server itself does not come configured with the basic mime types you have to define them yourself.

This is a working example configuration reported by one of the mailing list users.

   <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>/faces/*</url-pattern>
    </servlet-mapping>

    <!--
    or the weblets servlet depending on your needs
    -->
    
    <listener>
        <listener-class>net.java.dev.weblets.WebletsContextListener</listener-class>
    </listener>

    <mime-mapping>
        <extension>css</extension>
        <mime-type>text/css</mime-type>
    </mime-mapping>
    <mime-mapping>
        <extension>js</extension>
        <mime-type>application/x-javascript</mime-type>
    </mime-mapping>
    <mime-mapping>
        <extension>gif</extension>
        <mime-type>image/gif</mime-type>
    </mime-mapping>

    <mime-mapping>
        <extension>png</extension>
        <mime-type>image/png</mime-type>
    </mime-mapping>

    <mime-mapping>
        <extension>jpg</extension>
        <mime-type>image/jpg</mime-type>
    </mime-mapping>

As it seems, Weblogic does not have auto mimetype mapping, and does not load the context listener automatically. By Providing both, Weblets should run. Alternatively the new Weblets mime type handling facilities also might work. Providing mime type mappings on bundle level!

Thank you Wim Bervoets for providing this configuration in [http://javablog.be/java/setup-weblets-10-for-jsf-on-weblogic-81/].

Summary

Weblets is configured over the web.xml configuration file.
If you are in a JSF environment, everything is done automatically once JSF is configured properly. In every other environment a small number of entries have to be added to the web.xml

Check out the weblets-demo example provided to see the configuration in action.

Weblets

weblets full project mirror