The IlvManagerServlet class

Programmer's documentation > Building Web applications > Developing basic JViews JavaScript Web applications > The IlvManagerServlet class

Describes the predefined servlet and how to use it.

Overview of the predefined servlet

Presents the predefined servlet.

The servlet requests and parameters

Presents the requests to which the servlet can respond and the parameters they take.

Multiple sessions

Describes the need for multiple sessions and gives an example.

Multithreading issues

Describes the use of single-thread and multithread versions of servlets and resulting synchronization requirements.

Overview of the predefined servlet

Developing the server side of a JavaScript Web application consists of creating a servlet that can produce an image to the client. Rogue Wave® JViews Framework provides a predefined servlet to achieve this task. The predefined servlet class is named IlvManagerServlet. This class can be found in the package ilog.views.servlet.

The IlvManagerServlet class is an abstract Java™ subclass of the HTTPServlet class from the Java servlet API.

The servlet requests and parameters

The servlet can respond to three different types of HTTP requests, the “image” request, the “image map” request, and the “capabilities” request. The image request returns an image from the Rogue Wave® JViews manager. The capabilities request returns information to the client, such as the layers available in the manager and the global area of the manager. This information allows the client to know the capabilities of the servlet in order to build the image request. When developing the client side of your application, you can use the JavaScript scripts or the JavaBeans™ provided by Rogue Wave JViews; both create the HTTP request for you, so you do not really need to write the HTTP request yourself.

The image request

The image request produces a JPEG image from the manager. The request has the following syntax, assuming that myservlet is the name of the servlet:

http://host/myservlet?request=image

&bbox=x,y,width,height (area in the manager coordinate system)

&width=width of the returned image

&height=height of the returned image

&layer=comma separated list of layers

&format=JPEG

&bgcolor=0xFFFFFF

Here is a list of parameters and their meanings.

Parameters of the IlvManagerServlet
Parameter Name	Parameter Value	Description
request	image	Asks the servlet to generate an image.
bbox	Float, Float, Float, Float	The area of the manager that is displayed in the image. The first two values are the upper left corner of the area. The last two values are the width and height of the area.
width	Integer	Width of the resulting image.
height	Integer	Height of the resulting image.
format	JPEG	The format of the resulting image.
layer	Comma-separated list of strings. For example: Cities, Roads	The layers of the IlvManager that are visible.
bgcolor	0xrrggbb For example, 0xffffff for white	The background color of the resulting image. This parameter is optional.
action	actionName(param1, param2)	Specifies an action to be executed on the server before the image is generated.

The following request produces a JPEG image of size (250, 250) showing the area (0, 0, 1000, 1000) of the manager; only the layers named “Cities” and “Roads” are visible:

http://host/myservlet?request=image

&bbox=0,0,1000,1000

&width=250

&height=250

&layer=Cities,Roads

&format=JPEG

The capabilities request

The capabilities request produces information to the client. This request returns information on the manager.

The capabilities request has the following syntax:

http://host/myservlet?request=capabilities

&format=(html|octet-stream)

[ &onload= <a string> ]

The request parameter set to capabilities instead of image tells the servlet to return the capabilities information. The format parameter tells which format should be returned.

The result can be of two different formats, HTML or Octet stream.

HTML format

The HTML format is used when the client is a JavaScript client. In this case, the result is a empty HTML page that contains some JavaScript™ code. The JavaScript code is executed on the client side, and some information variables are then available.

<html>

<head>

var minx=0.0;

var miny=0.0;

var maxx=1024.0;

var maxy=512.0;

var themes=new Array();

var overviewthemes=new Array();

themes[0]="a layer name";

overviewthemes[0]=true;

themes[1]="another layer";

overviewthemes[1]=true;

themes[2]="a third layer";

overviewthemes[2]=true;

var maxZoom=6;

</script>

</head>

<body>

</body>

</html>

The variables minx, miny, maxx, maxy are defining the global area of the manager that can be queried. The themes variable is the list of layers available on the server side. The overviewthemes variable tells if a layer should be visible in the overview window. The maxZoom variable is the maximum level of zoom the application should perform.

The onload parameter allows you to specify a String that is used for the onload event of the generated HTML page. When an onload parameter is specified, the body tag of the HTML page is:

Octet-stream format

The octet-stream format is used when the client is a Java™ applet. In this case, the result is a stream of octets. The data is produced using a java.io.DataOutput and can be read using a java.io.DataInput. It is organized as follows:

Float: left coordinate of manager’s bounding box.

Float: top coordinate of manager’s bounding box.

Float: right coordinate of manager’s bounding box.

Float: bottom coordinate of manager’s bounding box.

Int: number of layers.

for each layer:

String (UTF format): name of the layer.

Boolean: is the layer an overview layer.

Float: Maximum zoom level

You see that this format gives the same type of information as the HTML format. Once again, you do not need to decode or read these formats. The client-side components provided by Rogue Wave JViews does that for you.

The image map request

The image map request produces an image and a client-side image map. The parameters for this request are the same as for the image request except that the request parameter must have the value imagemap.

For example, the following code to the servlet:

http://host/myservlet?request=imagemap

&width=400

&height=200

&bbox=0,0,500,500

&format=JPEG

&layer=Cities,Links,background%20Map

can produce, for example:

<html>

<body>

....

</map>

<img usemap="#imagemap" width="400" height="200"

src="myservlet?request=image&layer=Cities,Links,background%20Map&width=400

&format=JPEG&bbox=0,0,500,500&height=200" border=0>

</body>

</html>

The call generates an HTML document containing the client-side image map and an image. The contents of the image are then generated by another call to the servlet.

The graphic objects that are taken into account when generating the map can be specified as well as the shape of the clickable area and what appends when you click it. All this is explained in Generating a client-side image map.

The image map request has two additional optional parameters:

The mapname parameter allows you to specify the name of the map. The default name is imagemap.

The onload parameter allows you to specify a String that is used for the onload event of the generated HTML page. When an onload parameter is specified, the body tag of the HTML page is:

Multiple sessions

The XML Grapher is a very simple example that creates a single manager view for the servlet. This means that all calls to the servlet (that is, all clients) are looking at the same view. This is fine when the same data is used for all clients but in some applications—for example, when you want to allow the user to edit the graphic representation—you might want to have a view (and thus a manager) for each client. In this case, you might use the notion of HTTP sessions. You can then create a view and a manager and store them as parameters of the session.

Here is a slightly modified version of the XML Grapher servlet using sessions:

package demo.xmlgrapher.servlet;

import javax.servlet.*;

import javax.servlet.http.*;

import java.net.*;

import ilog.views.*;

import ilog.views.servlet.*;

import demo.xmlgrapher.*;

public class XmlGrapherServlet extends IlvManagerServlet

{

String xmlfile;

public void init(ServletConfig config)

throws ServletException

{

xmlfile = config.getInitParameter("xmlfile");

if (xmlfile == null)

xmlfile = config.getServletContext().

getRealPath("/data/world.xml");

setVerbose(true);

}

protected void prepareSession(HttpServletRequest request)

{

HttpSession session = request.getSession();

if (session.isNew()) {

XmlGrapher xmlGrapher = new XmlGrapher();

try {

xmlGrapher.setNetwork(new URL("file:" + xmlfile));

} catch (MalformedURLException ex) {

}

session.putValue("IlvManagerView", xmlGrapher);

}

public IlvManagerView getManagerView(HttpServletRequest request)

throws ServletException

{

HttpSession session = request.getSession(false);

if (session!= null)

return (IlvManagerView)session.getValue("IlvManagerView");

else

throw new ServletException("session problem");

}

protected float getMaxZoomLevel(HttpServletRequest request,

IlvManagerView view)

{

return 30;

}

The init method does not create any XmlGrapher object any more. Instead, the prepareSession method (which has a default empty implementation) is overwritten to get the HTTP session. If this is a new session, an XmlGrapher object is created and stored as a parameter of the session. The getManagerView method returns the XmlGrapher object stored in the session.

Multithreading issues

The IlvManagerServlet class does not implement the SingleThreadModel interface from the Servlet API, so you can create servlets that use the multithread or single-thread model.

If your servlet implements the SingleThreadModel interface, then you do not have to deal with concurrent access to your servlet. The servlet be thread safe. However, this interface does not prevent synchronization problems that result from servlets accessing shared resources such as static class variables or classes outside the scope of the servlet.

If your servlet does not implement the SingleThreadModel interface, then you might have to be concerned with concurrent access to the servlet. All basic operations done by the IlvManagerServlet on the IlvManagerView are already synchronized. This means that you have to take care of concurrent access only if you are doing additional actions on the IlvManagerView. In this case you can define a locking object and use the getLock method of the IlvManagerServlet. Each request handling is implemented in the following way:

... reads the request parameters ...

synchronized(getLock(request)) {

IlvManagerView view = getManagerView(request);

... handle the request ...

}

By default, the getLock method returns a new object each time. This means that the section is not synchronized.