Advanced Web Topics

1. Customizing the Web Service
2. Starting on Boot
3. Integrating with Apache
4. Themes and User Agent Specific Content
5. Bundled Web Content
6. Controlling Rendering with the Render Object
7. Web Configuration Pages

For Windows (XP, Vista, 7, etc)...

sudo cp etc/init.d/web/debian /etc/init.d/web
sudo chmod +x /etc/init.d/web
sudo update-rc.d add web defaults

As it is currently implemented, the web application requires binding to a specific host and port. If a dedicated port is not an issue (ie connecting to http://myhost:8080/ is not a problem), then running standalone is preferred. However, in vhost situations, where there are many hostnames referring to the same ip, standalone function may not be possible. By integrating the standalone applications with apache, it is possible for apache to serve many hosts on the same ip and to quietly pass requests to the standalone applications. In such a way, multiple applications can be served on the same host or multiple hosts on the same ip and port.

There are two main methods for apache integration, mod_proxy_ajp or mod_proxy_http with mod_rewrite. The mod_proxy_ajp method is preferred, as it is more transparent by not clobbering 5XX error codes. The jetty guide recommends mod_proxy_http over mod_proxy_ajp, but I have found mod_proxy_ajp to work better.

$ sudo a2enmod proxy_ajp

LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_ajp_module /usr/lib/apache2/modules/mod_proxy_ajp.so
<IfModule mod_proxy.c>
  #turning ProxyRequests on and allowing proxying from all may allow
  #spammers to use your proxy to send email.

  ProxyRequests On

  <Proxy Ajp://127.0.0.1>
      Options Indexes FollowSymLinks MultiViews
      AllowOverride None
      Order allow,deny
      allow from all
  </Proxy>

  # Enable/disable the handling of HTTP/1.1 "Via:" headers.
  # ("Full" adds the server version; "Block" removes all outgoing Via: headers)
  # Set to one of: Off | On | Full | Block

  ProxyVia On
</IfModule>

Now, setup your application to start at boot, as described in the last section. Ensure that the --ajp parameter is used for application startup. This will add the jetty ajp connector at port+4, ie if your app starts on port 8420, an ajp connector will be started and listen on port 8424. To manually specify the ajp port, provide a --ajp-port [port] parameter. If started manually with the ajp parameter(s), the ajp port will be displayed during startup (and in the log). You probably want to also specify the -b localhost parameter, which will bind the application to localhost, which will prevent external access. This reduces security concerns.

Once it's configured to run on boot, modify the apache vhost configuration to proxy via ajp:

ProxyPass / ajp://localhost:8424/
ProxyPassReverse / ajp://localhost:8424/

<VirtualHost *:80>
  ServerAdmin webmaster@localhost
  ServerName myhost.com

  DocumentRoot /path/to/application/html
  <Directory /path/to/application/html/>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride None
    Order allow,deny
    allow from all
  </Directory>

  ErrorLog /path/to/application/logs/error.log
  LogLevel warn
  CustomLog /path/to/application/logs/access.log combined

  ProxyPass / ajp://localhost:8424/
  ProxyPassReverse / ajp://localhost:8424/
</VirtualHost>

For more complex integrations, it is possible to exclude paths from proxy, which will then be served by apache. This is desirable for heavily hit paths, or to use apache functionality (dir listing, etc). An example including exclusion is:

<VirtualHost *:80>
  ServerAdmin webmaster@localhost
  ServerName myhost.com

  DocumentRoot /path/to/application/html
  <Directory /path/to/application/html/>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride None
    Order allow,deny
    allow from all
  </Directory>

  ErrorLog /path/to/application/logs/error.log
  LogLevel warn
  CustomLog /path/to/application/logs/access.log combined

  ProxyPassReverse / http://localhost:8127/
  
  # except the following (in order)
  ProxyPass /project !
  ProxyPass /misc !
  ProxyPass /webalizer !
  ProxyPass /docs !
  # proxy everything
  ProxyPass / ajp://localhost:8127/
</VirtualHost>

This same concept is used for delivering different web items according to requesting User-Agent. There are several stock user agent matchers defined, with the ability to define custom matchers. By default the user agent matchers match the User-Agent header passed in the request.

• UserAgent contains 'MSIE 5' : ie5
• UserAgent contains 'MSIE 6' : ie6
• UserAgent contains 'MSIE' : ie
• UserAgent contains 'Firefox' : firefox
• UserAgent contains 'iPhone' : ipod

UserAgent matchers can be added by implementing the UserAgentMatcher interface and using the org.benow.java.packager.Packager procedure before jar'ing. The Packager procedure is already defined in build.xml, so an ant jar is all that is required to register the custom UserAgentMatcher. The @Position annotation can be used to determine load order of the UserAgentMatcher. An example (as found in src/java/test/org/benow/web/SampleUserAgentMatcher.java is:

@Position(Position.FIRST)
public class SampleUserAgentMatcher implements UserAgentMatcher {

  @Override
  public String getTypeName() {
    return "sample";
  }

  @Override
  public boolean matches(String uaString) {
    return uaString.contains("Sample");
  }

}

Themes and UA matching can also be used in conjuction. A request for test/test.page by a user with the blue theme on a ipod touch would use test/test.blue.ipod.page if it existed.

An example of this functionality is the admin pages. If you have the web running on localhost:8080, hit http://localhost:8080/admin/dev/menu.page. You'll see the menu administration page be delivered. One would expect to find menu.page as html/admin/dev/menu.page within the project root, but it is not there. The page is being delivered from the benow-web.jar itself. To verify this, you can view the contents of benow-web.jar:

$ jar tvf benow-web.jar | grep admin
 50970 Mon Aug 31 17:53:02 PDT 2009 WEB-INF/html/admin/dev/index.page
 19590 Mon Aug 31 17:53:02 PDT 2009 WEB-INF/html/admin/dev/menu.page
   925 Mon Aug 31 17:53:02 PDT 2009 WEB-INF/html/admin/dev/resources.page
  5484 Mon Aug 31 17:53:02 PDT 2009 WEB-INF/html/admin/dev/service.page
  3712 Mon Aug 31 17:53:02 PDT 2009 WEB-INF/html/admin/index.page
  1337 Mon Aug 31 17:53:02 PDT 2009 WEB-INF/html/admin/log/index.page
 31069 Mon Aug 31 17:53:02 PDT 2009 WEB-INF/html/admin/security/index.page
 16708 Mon Aug 31 17:53:02 PDT 2009 WEB-INF/html/admin/security/login.page
 17236 Mon Aug 31 17:53:02 PDT 2009 WEB-INF/html/admin/security/role.page
 20623 Mon Aug 31 17:53:02 PDT 2009 WEB-INF/html/admin/test/index.page

<xsl:param name="render"/>

• Setting the page title
• Setting the help context
• Setting the content type
• Supressing the header
• Supressing all site template content

<xsl:template match="/">
  <xsl:value-of select="java:set($render,java:'pageTitle','Page Creation Examples')"/>
  <xsl:apply-templates/>
</xsl:template>

<xsl:template match="/">
  <xsl:value-of select="java:set($render,java:'helpContext','test')"/>
  <xsl:apply-templates/>
</xsl:template>

<xsl:template match="/">
  <xsl:value-of select="java:set($render,java:'contentType','text/xml')"/>
  <xsl:apply-templates/>
</xsl:template>

<xsl:template match="/">
  <xsl:value-of select="java:set($render,java:'supressHeader','true')"/>
  <xsl:apply-templates/>
</xsl:template>

<xsl:template match="/">
  <xsl:value-of select="java:set($render,java:'supressAll','true')"/>
  <xsl:apply-templates/>
</xsl:template>