The Util Module

The Util module (util.jar) includes the embedded server, common servlets, and a collection of utility classes used in CTP, MIRC2 (TFS), Geneva, FileSender and other MIRC tools. This article describes the theory of operation of the packages contained in the Util module. The intended audience for this article is software engineers extending or maintaining CTP and TFS or any of the other MIRC software that uses it.

See Setting Up a MIRC Development Environment for information on obtaining and building the Util module.

The Util module contains five packages:

• org.rsna.server contains an embedded servlet container, with user authentication and servlet mapping from requested resource paths.
• org.rsna.multipart provides built-in support for multipart forms.
• org.rsna.servlets contains the Servlet base class and servlets that are used for authentication and system management.
• org.rsna.service contains code that simplifies the implemention of HTTP services.
• org.rsna.util contains utility classes.

Each of these packages will be described in the sections below, with example code where necessary to illustrate the theory of operation. I recommend that you get the code and build it so you can reference the Javadocs as you go along.

1 org.rsna.server

The embedded servlet container is implemented in the in the HttpServer class. The implementation is not W3C-compliant; it is designed to minimize the need for configuration outside the application program within which it is embedded.

The HttpServer constructor requires a boolean indicating whether the server is to operate in SSL, the port on which the server is to listen, and an instance of the ServetSelector class.

The ServletSelector provides a mapping between requested resource paths and servlets. It also defines the root of the server file tree for served files. Servlets are added into the ServetSelector programmatically. Adding servlets can be done while the server is running.

When the server receives a connection, it creates an instance of the HttpHandler class to service the request. The instance is managed by an instance of java.util.concurrent.ExecutorService set to handle a maximum of 20 concurrent threads. When the HttpHandler is instantiated, it creates instances of the HttpRequest and HttpResponse classes. It then calls the ServletSelector to obtain an instance of the servlet that matches the requested resource. If no servlet matches the request, the ServletSelector returns the Servlet base class, which acts as a web server. The HttpHandler then calls the servlet's method specified in the HttpRequest.

The HttpRequest parses the request and calls the Authenticator to authenticate the user.

The Authenticator supports three methods of authentication:

• If the RSNASESSION cookie is contained in the request, it is used as an index into a session table.
• If no session is found for the request, the Authorization header is used to obtain credentials via basic authorization.
• If the user cannot be authenticated by the Authorization header, the RSNA header is used to obtain credentials. This header is supported only for backward compatibility with obsolete MIRC software. No current MIRC software uses the RSNA header to pass credentials.

When authenticating credentials, the Authenticator calls the Users implementation to do the actual authentication. The Users class is the base class for classes that represent users. There are two Users class implementations:

• org.rsna.server.UsersXmlFileImpl represents users in an XML file (users.xml).
• org.rsna.server.UsersLdapFileImpl represents users in an XML file (users.xml), but uses an external LDAP server to authenticate the users' credentials.

In both Users implementations, the user's roles are represented in the XML file.

1.1 Example Server Startup

This is an example of how to instantiate an HttpServer. It is loosely based on the way CTP starts the server, and it uses a singleton Configuration class to access the configured values for the Users implementation, the SSL boolean, and the server port.

//Get the configuration
Configuration config = Configuration.getInstance();

//Instantiate the singleton Users class
Users users = Users.getInstance(config.getUsersClassName(), config.getServerElement());

//Create the ServletSelector for the HttpServer
ServletSelector selector =
	new ServletSelector(
		new File("ROOT"),
		config.getRequireAuthentication());

//Add in the servlets
selector.addServlet("login", LoginServlet.class);
selector.addServlet("users", UserManagerServlet.class);
//etc.

//Instantiate the server.
int port = config.getServerPort();
boolean ssl = config.getServerSSL();
HttpServer httpServer = null;
try { httpServer = new HttpServer(ssl, port, selector); }
catch (Exception ex) {
	logger.error("Unable to instantiate the HTTP Server on port "+port, ex);
	System.exit(0);
}

1.2 Example Server Shutdown

If the application has servlets that must be shut down gracefully, the server's shutdown method should be called before the application exits. This causes the server to stop the ExecutorService's processing of HttpHandler requests and to call the ServletSelector's shutdown method, which in turn causes it to call each servlet's destroy method.

//Stop the server
httpServer.shutdown();

2 org.rsna.multipart

The multipart package provides support for multipart forms. The basic model is:

• Test the content type of the HttpRequest.
• Call the getParts method of the HttpRequest object.
• Access the parameters and files.

2.1 Example Multipart Parsing

This example demonstrates how to obtain the parts of a multipart form.

String ct = req.getContentType().toLowerCase();
if (ct.contains("multipart/form-data")) {

	//Make a directory to receive any uploaded files
	File dir = new File("dirName");
	dir.mkdirs();

	//Get the parameter parts and the posted files
	int maxsize = 75 * 1024 * 1024; //max allowed upload in bytes
	LinkedList<UploadedFile> files = req.getParts(dir, maxsize);

	//At this point, any parameter parts are available through the
	//getParameter methods of the HttpRequest object.
	String param = req.getParameter("paramName", "defaultValue");

	//The file parts are obtained from the List object
	for (UploadedFile uFile : files) {
		File file = uFile.getFile();
		//do something with the file
	}
}