Using JADE with Java Server Pages (JSP)

Authors: Daniel Le Berre (leberre@cril.univ-artois.fr), Olivier Fourdrinoy

Last modified: mercredi 5 juin 2002

JSP platform: Sun Java Server Web Development Kit (JSWDK) 1.0.1 , Jakarta Tomcat 3.X/4.0

JADE versions 1.4 and over.

One of the major interest when adopting the Java Server Pages approach to generate dynamic HTML, is to be able to use available Java APIs to handle various work such as database connection, authentication, etc... One interesting feature of JSP is also the convenient way to handle forms with JavaBeans.

Since JADE is written in Java, it is pretty easy to integrate JADE agents with JSP. This allows you to have for instance an agent looking at all the connections made to a particularly sensitive web page, and report you each of them (this is particularly interesting in the Java Server Pages context for the error page for instance). This will be the application we are going to design in this tutorial.

This tutorial assumes that:

you are familiar with Java and have Java correctly installed.

you are familiar with JADE and have JADE correctly installed.

you are familiar with JSP and have a JSP enabled web server correctly installed.

you have downloaded the JADE tag library add-on from the JADE web site and you have executed the scripts 'ant lib' and 'ant examples' that create the appropriate jar files.

The problem

We have three agents, namely snooper, buffer and client. Snooper is the agent that is living on the sensitive web page, client is an agent that must display the information concerning the connections to the web page to the webmaster. Since the latter can not be logged on his computer, buffer is an agent that will keep the information if the webmaster is not reachable. Furthermore, the snooper client must act quickly to not delay the availability of the web page, so it will just send the information for the webmaster trough the buffer, that will always be reachable. buffer will manage the connection with client: the latter will subscribe/unsubscribe when it is launched/stopped. It will check that the client has really received the information before deleting it.

Drawing 1 JADE agents

Creating the agents

The three agents are really easy to construct. The code should work both under JADE 1.4 and JADE 2.0 after minor syntactical modifications given in the code.

Snooper.java

Buffer.java

Client.java

There are two tips in this code:

I am using the block() method both on Client and Buffer agents to avoid CPU consumption overhead.

To be able to know if the client is alive or not, I need to wait for a reply from the client during 10 seconds. If no confirmation arrive, I suppose that the agent is not there and I do not clear the message in the buffer agent.

Agent and JSP (Updated June 2002 with jade taglib)

Now we have all our JADE agents defined. We need to integrate the Snooper agent in our web page. Here is how to proceed.

Without jade taglib

We first need to import some jade classes using the page import statement. Then we declare our agent, with an application scope. This is important because it means that the agent will have the same life than the enclosing servlet (the JSP page). So the agent will still living even if there is no connections to the page. Furthermore, all the initialization code defined between the useBean tags will be only executed once.

To be able to use JADE agent, we need at least one agent container on the JVM running the servlet. So we need to integrate the call to JADE platform or container, usually done from the command line, directly in the JSP page. Here I simulate a command line call with no option for JADE 1.4, with the "-container" for JADE 2.0, which means that the JADE platform is running on the same machine than the JSP web server. A JADE Agent Platform cannot be created within a JSP page because of security restrictions. In the next releases of JADE this limitation will probably be removed.

Once the JADE container is created, we need to register our Snooper agent to the container. This is done using the doStart() method. Note that the reference to our agent is the ID defined in the useBean declaration.

formertestjade.jsp

Now we can use our agent to snoop each connection to this JSP page. Here the message sends the name of the remote host, the date and the name of the web page.

The main problem with that approach is that:

The user need to manipulate directly the agent in the code.

To solve the second problem, JADE team released wrappers for manipulatig agents from objects, in the java.wrapper package. To solve the first one, the best solution is to create a new tag.

With jade taglib

Here the solution is more elegant in the JSP page, but a bit more difficult to deploy.

What is needed:

The jspagents.jar file: it contains the Snooper, Buffer and Client classes (actually, you just need the Snooper agent here).

The jade.tld file: it maps each tag to a class.

The web.xml file: this files maps the jade taglib id « jade » to the jade.tld file.

Suppose that you are creating a JSP application myapp in Tomcat. Then you will put all the files related to myapp in the directory $tomcat/webapps/myapp. You should have the following directory structure:

$tomcat/webapps/myapp
  all the jsp files (jestjade.jsp, testagade.jsp, testagade1.jsp)

$tomcat/webapps/myapp/WEB-INF
  web.xml, jade.tld

$tomcat/webapps/myapp/WEB-INF/lib
 all jade jar files (jade.jar, jadeTools.jar, etc.) + the jadetaglib.jar file + jspagents.jar

Note that is it necessary to put all the jar files in the same lib directory. For instance, if one want to share jade classes between several JSP applications, then putting jade jar files in the main lib directory ($tomcat/lib) is possible if you also move the jadetaglib.jar and jspagents.jar files there.

To declare the jade taglib in a jsp page, one must put this line at the very begining of the file:

<%@ taglib uri="jade.wrapper.taglib" prefix="jade" %>

Then it is possible to use the three tags container, useAgent and sendObject:

container:

The container tag creates a JADE container with an application scope. The options available are the ones available from jade command line: hostname, port and a string parameter for future extensions. Note that for the moment one can only creates new containers for an existing JADE platform, due to security restrictions.

<jade:container id="mycontainer" host="myhost" port="1099"/>

useAgent:

The useAgent tag creates a new agent in a given container for a given scope. The agent id is the name of the agent in the container, and the name of the proxy agent in the jsp page.

<jade:useAgent id="snooper" classname="examples.jsp.Snooper" container="mycontainer" scope="application"/>

sendObject:

The last tag should replace the agent.putO2AObject() method. Unfortunately, for the moment, only String objects can be sent to the agent.

The following code:

<% snooper.putO2AObject(request.getRemoteHost()+" "+(new java.util.Date())+" "+request.getRequestURI(),false); %>

is equivalent to:

<jade:sendObject id="snooper" blocking="false"><%= request.getRemoteHost()+" "+(new java.util.Date())+" "+request.getRequestURI() %></jade:sendObject>

If one to to pass an object an not a String to an object, he should use the first approach.

The following jsp files creates one container and two agents, using those tags:

testagade.jsp

Putting everything to work

Here is the architecture of our working JADE environment with a JSP page.

Drawing 2 JADE containers

The server contains two different JVM: one to run JSP/servlet plus one JADE container, and another one to run JADE platform. I don't see how to change this design since it does not seem possible to run the JADE platform directly inside JSP/Servlet JVM.

The client is running another instance of the JVM to run a second JADE container.

The interesting feature of this design is that the platform (and the buffer agent) is dissociated from the JSP page. Since each time that you change the JSP page you delete the snooper agent and his container, using a separate container for the buffer avoid to loose all the information it contains.

To run this example, compile the three agent java files. Put Snooper.class and Buffer.class in the server in a directory of the classpath of your JSP web server (the classes directory with tomcat, the webpages/WEB-INF/jsp/beans/ with JSWDK for instance). Do not forget to add JADE jar files in the lib directory of the JSP web server. (they will be added automatically on the JSP web server classpath). Put Client.class on the client computer. (I assume that JADE is installed on this computers). Remember that if you use the package examples.jsp, you have to put the class files in a subdirectory examples/jsp/. Put the file testjade.jsp in a directory accessible from your JSP web server (webpages/ for instance).

1. Run JADE platform with buffer agent on the server

java jade.Boot -platform buffer:examples.jsp.Buffer

2. Run the JSP page with the snooper agent on the server

request the testjade.jsp from your JSP web server

3. Run the client agent into a jade container on the client

java jade.Boot -container -host server.domain daniel:examples.jsp.Client