JServer tutorial

Starting the StandAlone JServer

To run the JServer as a standalone web server, cd to the bin directory and enter the following

C:\jk-0.91\bin> jview /cp:p . cornell.slk.jkernel.std.Main cornell.slk.jos.manager.Main -config config\jserver-config SERVER_TYPE=STANDALONE

Welcome to JOS v0.91
Booting...
Starting service cornell.slk.jos.rpc.subsystem.RPCSubsystem
RPCEndpointManager: Accepting RPC connections at port 45678
IIS_HOST=null
SERVER_TYPE=STANDALONE
ServletLoader servlet installed.
SubsystemLoader servlet installed.
Boot completed.
Press any key to shutdown.
StandAloneServer: Now accepting connections on port 8008.

You should see the above message, indicating that your JServer is up and running. The URL of your standalone JServer is:

http://<your machine>:8008/

To stop the server, simply hit any key. Ignore the exception ThreadDeath$LRMI exception thrown.

Starting the IIS plug-in JServer (NT only)

To run the JServer as as Microsoft IIS plug-in, first install the JServer binaries on IIS. Make sure the WorldWideWeb service has been started in your machine by checking the services tab under the control panel. The URL of your IIS/JServer is:

http://<IIS machine>/jserver/win32/jserver.dll/

IIS will automatically load the JServer ISAPI dll when processing the first HTTP request to the above URL. With IIS 2.0 or 3.0, there is not explicit way to unload an ISAPI extension besides stopping the WWW service and restarting it using the Services tab in the Control Panel.

Using the JServer

Open your favorite web browser and open a URL connection to JServer. The JServer processes the HTTP request and sends back the following response in HTML, displayed in your browser window:

Welcome to the J-Server 0.91
Use the servlet loader to load/unload servlets.
Use the subsystem loader to load/unload subsystems.
J-Server Help
SLK Home Page

The servlet URL space in the JServer has a flat structure, that is, a valid URL connection to the JServer has the following format:

<JServer URL>/<servlet name>/[<optional path info>][?<optional query string>]

For example, the following URL reaches the servlet loader:

<JServer URL>/loader

Writing Servlets

Please refer to the Sun's Java Servlet API for documentation on writing servlets. The JServer provides a custom implementation of the servlet API in the cornell.slk.jserver.servlet package. Most demo servlets that come with Sun's Java Web Server should run without problems. Just make sure the servlets import the JServer packages (cornell.slk.jserver.servlet and cornell.slk.jserver.servlet.http) instead of Sun's (javax.servlet.* and javax.servlet.http.*).

The following is the source code of the HelloWorld servlet:

package cornell.slk.jserver.demoservlets;

import cornell.slk.jserver.servlet.*;        // replaces javax.servlet.*
import cornell.slk.jserver.servlet.http.*;   // replaces javax.servlet.http.*
import java.io.*;

public class HelloWorldServlet extends HttpServlet
{
    public void init(ServletConfig config)
    {
        System.out.println("HelloWorldServlet: Init called");
    }

    public void service(HttpServletRequest req, HttpServletResponse rep)
        throws ServletException, IOException
    {       
        ServletOutputStream os = rep.getOutputStream();
        String name = req.getParameter("name");
        rep.setContentType("text/html");
        os.println("<HTML><HEAD><TITLE>HelloWorldServlet</TITLE>");
        if (name == null) {
            os.println("</HEAD><P><H3>Hello World!! </H3>");
        } else {
            os.println("</HEAD><P><H3>Hello " + name + "!! </H3>");
        }
    }
   
    public void destroy() { }
}

Launching Servlets in the JServer

Click on the servlet loader link, and you will get an HTTP form that looks as follows,

servlet HTTP handle [mandatory]:

action [load=0, unload=1]:

servlet entry class [mandatory if loading]:

packages [mandatory if loading]:

additional classes [optional]:

Enter the path and/or url where the entry class, packages, and additional classes are found. Use ; as separators. [mandatory if loading]
path:

url:

Additional resolvers [optional, use ; as separators] :

servlet arguments [= pairs, use ; as separators (e.g. foo=1;bar=goo]):

where:

name is your servlet's HTTP handle. The URL of the servlet is servlet's handle appended to the J-Server's URL. Servlets run in their own protection domains, or task. The servlet name uniquely identifies a servlet task, and is used internally to manage information about the servlet. You must specify a name in order to load and unload servlets.

action specifies whether you want to load (action = 0) or unload (action=1) your servlet. To unload a servlet, the only other information you need to submit is the servlet handle. The rest of the information in the form is ignored.

class is fully-qualified name (i.e. with the package name prepended to the class name without the .class extension) of the Java class that implements the servlet entry points (servlet API). You cannot enter more than one fully-qualified name here. This information is mandatory when you are loading servlets.

packages are all the Java packages used by your servlet, including the package to which your servlet belongs (if any). This information is mandatory when you are loading servlets.

classes allows you to specify the fully-qualified names of additional Java classes that are not in any packages listed above, or classes that don't belong to any package.

path and/or url is a (list of ) file system path(s) and URLs respectively where the servlet entry class, packages, and classes are found. Use ; as separator. When using the J-Server that runs within IIS, you can only specify local IIS directories. These directories CANNOT be IIS virtual ones. If the path includes directories on remote disks, make sure the disk is actually mounted on your machine before specifying it as a path.

resolvers allows you to specify one or more pre-built resolvers for your domain. The following is a list of pre-built resolvers:

servlet arguments are a list of pairs <key, value> that are passed to the servlet initialization routine.

Example: The form below loads the HelloWorld servlet program introduced in the previous section.

servlet HTTP handle [mandatory]:
hello
action [load=0, unload=1]:
0
servlet entry class [mandatory if loading]:
cornell.slk.jserver.demoservlets.HelloWorldServlet
packages [mandatory if loading]:
cornell.slk.jserver.demoservlets;cornell.slk.jserver.servlet;cornell.slk.jserver.servlet.http
additional classes [optional]:

Enter the path and/or url where the entry class, packages, and additional classes are found. Use ; as separators. [mandatory if loading]
path:
c:\jk-0.91\bin
url:

Additional resolvers [optional, use ; as separators] :

servlet arguments [= pairs, use ; as separators (e.g. foo=1;bar=goo]):

You should get the following message in your browser after hitting "Submit Query":

Servlet hello loaded successfully.
Back to loader

Finally, to run the servlet, append the servlet handle hello to your JServer's URL:

http://<machine>:8008/hello

and you should see

Hello World!

in your browser window.

Troubleshooting:

  1. The most common problem developers face when loading servlets is having the java.lang.ClassNotFoundException thrown. If your servlet uses the Java File classes from the standard java.io package, or the java.net package, or the java.reflection package, don't forget the include the appropriate resolvers in the list. Also make sure every package and class you've listed can be found in the list of paths. The documentation on JKernel resolvers can be helpful.

Launching JOS Subsystems from the JServer

Click on the subsystem loader link, and you will get an HTTP form that looks as follows,

subsystem handle [mandatory]:

action [load=0, unload=1]:

subsystem configuration file [mandatory]:

where:

name is the subsystem's handle.The subsystem name uniquely identifies a subsystem task, and is used internally to manage information about the subsystem. You must specify a name.

action specifies whether you want to load (action = 0) or unload (action=1) the subsystem. To unload a subsystem, the only other information you need to submit is the name. The rest of the information in the form is ignored.

subsystem configuration file is a file name that contains a valid subsystem configuration. The file name is relative w.r.t. to the bin directory, but you can also enter a file name with a full path. For documentation about subsystem configurations, click here. This information is mandatory when you are loading subsystems.

For example, the following form loads the TestSubsystem described in the JOS overview:

subsystem handle [mandatory]:
test  
action [load=0, unload=1]:
0  
subsystem configuration file [mandatory]:
config\test-config.txtornell.slk.jserver.demoservlets.HelloWorldServlet

You should get a message acknowledging the loading of the subsystem.

Next: JServer Overview

Home