Configuring VRD for Scripting Languages

In traditional java web applications, you can only use java language to write server side code. Using VRD-SLE (Scripting Language Extension), you can easily configure your java web applications to write server side code using Jython, JRuby, Groovy and JavaScript. Not only this, you can also get benefit of the powerful libraries of Jython and JRuby.

The first thing you need to do is to configure your web application to work with Vroom Request Dispatcher. For that please read the Blog Entry What is Vroom Request Dispatcher?

Once the above step is complete, you need to add following entries in /WEB-INF/vrd-config.xml file: (You may only include the entries that are needed)

<vrd-config>
<request pattern="/path/to/scripts/.*.py">
 <invocation method-name="net.openkoncept.vroom.vrd.jython.JythonRequestDispatcher.dispatch"/>
</request>
<request pattern="/path/to/scripts/.*.rb">
 <invocation method-name="net.openkoncept.vroom.vrd.jruby.JRubyRequestDispatcher.dispatch"/>
</request>
<request pattern="/path/to/scripts/.*.groovy">
 <invocation method-name="net.openkoncept.vroom.vrd.groovy.GroovyRequestDispatcher.dispatch"/>
</request>
<request pattern="/path/to/scripts/.*.js">
 <invocation method-name="net.openkoncept.vroom.vrd.javascript.JavaScriptRequestDispatcher.dispatch"/>
</request>
</vrd-config>

For Jython, you need to add JVM parameter as follows:

-Dpython.path=/path/to/jython-home/Lib:/path/to/jython-home/Lib/site-packages

Like servlet, there is an entry point for these scripts and that is a no argument public method named vrd_main , to request and response objects are accessible in the script using variables vrd_hreq (javax.servlet.http.HttpServletRequest) and vrd_hres (javax.servlet.http.HttpServletResponse). Below are the samples in each scripting language:

Jython:

def vrd_main():
   res = vrd_hres
   res.contentType = 'text/html'
   w = res.writer
   w.print('Hello World')
   w.flush()

JRuby:

def vrd_main()
   res = $bsf.lookupBean('vrd_hres')
   res.contentType = 'text/html'
   w = res.writer
   w.print('Hello World')
   w.flush()
end

Groovy:

def vrd_main() {
   res = vrd_hres
   res.contentType = 'text/html'
   w = res.writer
   w.print('Hello World')
   w.flush()
}

JavaScript:

function vrd_main() {
   res = vrd_hres
   res.contentType = 'text/html'
   w = res.writer
   w.print('Hello World')
   w.flush()
}

How to write vrd-config.xml file?

It's very important to understand how we should write vrd-config.xml. There is a file named vrd-config-1.0.xsd which is available with the API and can be used to validate vrd-config.xml however it is not required. Below is a quick guide:

The root element of the configuration file is vrd-config. It may have 0 or many request elements. E.g.

<vrd-config>
<request ...>
 ...
</request>
</vrd-config>

The request elements take two attributes, pattern (mandatory) and exclude. Both accepts java regular expressions, e.g.

<request pattern=".*" exclude="/scripts/.*">
...
</request>

The above definition is to intercept all URIs except those followed by /script/ .

Each request element can have either response or invocation as child element. The response element takes two attributes, url (mandatory) and redirect (optional with default value false), e.g.

<request pattern=".*">
<response url="http://www.google.com" redirect="true"/>
</request>

Normal if the response is a forward, the redirect attribute is not specified. To do a response redirect on the same web application, you need to specify #{contextPath} as prefix in the path attribute, e.g.

<request pattern="/|/index.jsp">
<response path="#{contextPath}/welcome.jsp" redirect="true"/>
</request>

The invocation element of the response object is used to invoke java method. There are two attributes, method-name (mandatory) and bean-class. There are two ways to specify the method to invoke:

1. Using method-name and bean-class attributes:

<request pattern=".*">
<invocation bean-class="Foo" method-name="bar"/>
</request>

2. Using only the method-name attribute:

<request pattern=".*">
<invocation method-name="Foo.bar"/>
</request>

The above mentioned methods are only applicable to public static methods of a public class. If the method is public but not static, there are two additional (optional) attributes, var and scope. The var attribute is used to specify a variable name to refer instance of bean-class. The scope is the scope of the instance. The possible values of scope are application, session, and request. If not specified, the scope is local. E.g.

<request pattern=".*">
<invocation bean-class="Foo" method-name="bar" var="foo" scope="request"/>
</request>

Note: The method that can be invoked must satisfy one of the following method signatures:

public (static) void|Object methodName();
public (static) void|Object methodName(javax.servlet.http.HttpServletRequest);
public (static) void|Object methodName(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse);

The Object can be an instance of any java class, but if it is a String, it can be used to define navigation. For navigation, you must use result element of invocation element. The result element takes two attributes, pattern and exclude and allows either response or invocation element just like request element.

<invocation method-name="java.util.Date.toString" var="dt" scope="application">
 <result pattern="(Sat|Sun).*">
     <response url="#{contextPath}/access-denied.html" redirect="true"/>
 </result>
</invocation>

Or

<invocation method-name="A.m1">
  <result pattern="value1">
      <invocation method-name="B.m2">
          <result pattern="value2">
              <response url="http://www.someurl.com" redirect="true"/>
          </result>
      </invocation>
  </result>
</invocation>

This is all about writing vrd-config.xml file.

What is Vroom Request Dispatcher?

Vroom Request Dispatcher or simply VRD is a small API for Java Web Applications. It consists of a small set of Java classes and a Java web filter (VRDFilter) which is configured in web.xml. The filter looks for a file named vrd-config.xml under /WEB-INF folder of the web application to work.

The API written after the inspiration of the powerful url pattern mapping in Python based web applications. Now in Java you can easily map url patterns to redirect/forward to other urls and/or invoke any public java method. Furthermore the API also helps to define application navigation. All these mappings and navigations are defined in /WEB-INF/vrd-config.xml file.

For download the library please visit the project website (http://code.google.com/p/vroom-request-dispatcher).

Once you download the library, configure it with the IDE you are using to build Java Web Applications. If you're not using any IDE, then either you can place the library files under classpath or you can copy them in /WEB-INF/lib folder. Once the Library is available, you need to add following entry in web.xml:

<filter>
<filter-name>VRDFilter</filter-name>
<filter-class>net.openkoncept.vroom.vrd.VRDFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>VRDFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>

After setting up the library and updating the web.xml file, you need to create an xml file name vrd-config.xml file. To learn about please the read the blog entry How to write vrd-config.xml file?