vqServer Java servlets


Java servlets are a way to add extra functions and capabilities to web servers. They are an alternative to CGI scripts. However, servlets are more efficient and more powerful than CGI scripts. vqServer is a very efficient host for Java servlets because it is itself a Java application.

Servlets run on the server (as opposed to Java applets which run in a browser). They are written in Java and conform to the servlet specification published by and available from Sun. For more information about servlets, including more very good reasons why you should use them, please see Sun's online documentation.

vqServer version 1.9 implements version 2.0 of Sun's servlet specification and API (but see API notes below).

vqServer
FAQs
Register (free!)
Support

Contents

Security
CGI scripts

Samples
Internal servlets
Calling servlets
Libraries
Parameters
Classes & Instances
CLASSPATH
Security
API notes

Sample servlets

Three sample servlets are included with vqServer:

  • vq.demos.Hello: This very basic servlet produces a web page which displays a Hello world message. Follow the link from the sample home page to see it work. The source code is in website/servlets/vq/demos/Hello.java.
  • vq.demos.Info: This servlet produces a web page which displays some diagnostic information about the web server, the servlet's initialisation parameters and the request which invoked the servlet. Follow the link from the sample home page to see it work. The source code is in website/servlets/vq/demos/Info.java.
  • vq.demos.SessionDemo: This servlet illustrates the use of JavaSoft sessions with vqServer. Follow the link from the sample home page to see it work. The source code is in website/servlets/vq/demos/SessionDemo.java.
vqServer
Contents
Servlets

Security
CGI scripts

Internal servlets

Some of vqServer's functions are provided by special internal servlets which have access to the inner workings of vqServer. These are:

  • vq.server.Admin: The control centre servlet.
  • vq.server.FileUpload: Provides a file upload facility. See the uploading files page for more information.
  • vq.server.ShtmlParser: Lets you use the <servlet>....</servlet> tag pair in your web pages. At present, these are the only SHTML tags supported by vqServer.
  • vq.server.UserReg: Allows you to require visitors to your web site to register for access to files and services.
  • vq.server.UserLogin: Enables use of custom login pages.
  • vq.server.UserPwd: Allows registered users to change their passwords.
  • vq.server.UserLogout: Facilitates logout.

The vq.server.UserXxx servlets are discussed on the special security features page.

vqServer
Contents
Servlets

Security
CGI scripts

Calling servlets and servlet aliases

There are three ways to invoke servlets:

  1. directly, for example by following a link on a web page which refers to a servlet or by typing a servlet's uniform resource locator in the Address box of a web browser. The output of the servlet is returned to the client
  2. by requesting a file whose type is associated with a filter servlet. The contents of the file are passed through the filter before it is sent to the client.
  3. by including the <servlet>...</servlet> tag pair in an .shtml page. These tags and the HTML code between them are replaced by the output of the servlet before the file is sent to the client.

In all three cases, vqServer expects servlets to be specified by their alias (see the aliases page for more information about aliases):

  1. direct servlet call: the link or uniform resource locator must be an alias corresponding to a servlet..
  2. filter servlet: the filter specified in the Filter line for a file type or alias must be an alias corresponding to a servlet (or several aliases separated by ;).
  3. <servlet>...</servlet> tag pair: The name= attribute of the <servlet> tag must be an alias corresponding to a servlet. The code= attribute and initialisation parameter attributes of the <servlet> tag are ignored by vqServer.

Note that aliases always begins with /. By convention, servlet aliases begin with /servlet/, although they can in fact be anything you like.

An alias can refer to a Java package. If so, the alias and its real name should end with a dot. In the default configuration supplied with vqServer, this method is used to alias the special internal servlets. It's almost impossible for vqServer to check such aliases (the package might be in an archive or on the CLASSPATH) so you'll have to carefully check any such aliases yourself. You can't use this method if the package is on the CLASSPATH and its name confilicts with the name of a subdirectory of website/.

vqServer expects the real name resulting from the translation of a servlet's alias to match servletdir/package.classname (see the aliases page for information about alias translation). Note:

  • The real name should not end in .class.
  • vqServer expects to find classname.class in the servletdir/package subdirectory of your website directory.
  • If the servlet author did not specify a package name the real name should be servletdir/package/classname.
  • vqServer looks for classes referenced by the servlet in the following places (in the order listed):
    • website/servletdir
    • the Java libraries known to vqServer
    • your CLASSPATH
  • If the real name does not include servletdir/ vqServer expects to find package/classname.class in the Java libraries known to vqServer or your CLASSPATH. This is how the special vqServer internal servlets are called.

vqServer can also load servlets and their associated resources from .JAR or .ZIP archives. If a servlet is in a .JAR archive the real name resulting from the translation of its alias should match archivedir/archivename.jar/classname. Servlet class files cannot be in subdirectories within .JAR or .ZIP files unless the subdirectories represent package names.

vqServer
Contents
Servlets

Security
CGI scripts

Java libraries

Complex servlet-based applications increasingly rely on support classes distributed in several .JAR or .ZIP files in addition to the .JAR or .ZIP file that contains the actual servlet. You can make the classes in these additional files available to servlets invoked by vqServer without adding them to your CLASSPATH by adding them to the list of Java libraries displayed by clicking on Java libraries in the vqServer control centre menu.

Classes loaded from Java libraries:

  • are shared by all servlets.
  • share the same namespace.
  • share the same classloader.
  • are not dynamically reloaded when the library is modified.

Note: On Sun's Java platforms version 1.2 and above you can achieve the same result as adding .JAR or .ZIP files to vqServer's Java libraries using the JVM's extension mechanism (just copy the files to your jre/lib/ext/ directory). This is usually more efficient than using vqServer's Java libraries.

Java libraries page

This page is displayed when you click on Java libraries in the control centre menu. See Java libraries for a brief overview. The page lists each Java library known to vqServer.

The following is displayed for each library.

Location

The location of the library, relative to your website/ directory. This must be a directory name or the name of an archive ending in .JAR or .ZIP.
Description This information isn't used by vqServer. It's just a useful place to record the function, source and version of the library.
Edit Displays a page which allows you to edit the location and description of the library.
Delete Removes the library from the list.

The New library link on the control centre menu on this page allows you to add a new library to the list.

vqServer
Contents
Servlets

Security
CGI scripts

Servlet initialisation parameters

You can specify initialisation parameters for a servlet by clicking on Aliases in the control centre menu and then clicking on the icon in the parameters column next to the corresponding alias (see Alias parameters). You may want to create an alias specifically for each servlet for which you need to provide initialisation parameters.

The data vqServer returns to servlets in response to the getParameterNames() and getParameter() methods of the ServletConfig interface is that which is in force at the time the method is invoked, not that which was in force when the servlet is initialised and can therefore change during the life of the servlet instance.

Modifying and reloading servlets

vqServer checks each servlet's .class file before calling the servlet (unless the servlet was loaded from a Java library or from your CLASSPATH). If the .class file has changed since the servlet was last called vqServer calls the servlet's destroy() method  (and the destroy() method of any other servlets that were loaded from the same directory) and reloads and re-initialises the servlet. If the servlet was loaded from a .JAR or .ZIP archive, the servlet (and any other servlets loaded from the same archive) is destroyed if the archive has changed.

You can force vqServer to call the destroy() method and unload all active servlets by clicking Other in the control centre menu and then clicking Stop all servlets.

vqServer
Contents
Servlets

Security
CGI scripts

Classes and instances

You can have more than one instance of the same servlet, each with different initialisation parameters, by using different aliases which correspond to the same servlet class (in the same servlet directory). Different instances of the same servlet and other servlets and classes loaded from the same directory share static class data. Servlets cannot "see" servlets and classes loaded from other servlet directories (except for Java libraries and the system CLASSPATH). In other words, the directory from which a servlet is loaded defines its name space.

The servlet CLASSPATH

The classes which a servlet can refer to are:

  1. classes in the same servlet directory or archive as the servlet.
  2. classes in any of the Java libraries known to vqServer.
  3. classes in any CLASSPATH directories specified on the command line when you start vqServer.
  4. classes in the system CLASSPATH.
vqServer
Contents
Servlets

Security
CGI scripts

Security considerations

vqServer doesn't impose any restrictions whatsoever on servlet activity. For example servlets can read, write and delete any file on your computer. So make sure that any servlets you deploy on your web site come from a reputable source or are thoroughly debugged.

vqServer
Contents
Servlets

Security
CGI scripts

API notes

Servlet writers should note the following concerning the vqServer implementation of the Sun servlet API:

  • ServletContext.getServletNames() returns the names of initialised servlets only.
  • ServletContext.getServlets() returns initialised servlets only. vqServer does not require servlets to be named before they are called and therefore has no way of knowing what servlets are available on the server computer. Further, vqServer will destroy servlets when the maximum number of servlet instances allowed (set in the system settings page of the control centre) is exceeded and forget about them completely.
  • You can use the file name part of an HTTP request to pass information to a servlet (PATH_INFO) but this is extremely inefficient unless the servlet is explicitly named in its own alias.
  • Beware of using System.out in a servlet. This works fine if you're using the vqServer console, and the output will be displayed on the console. If you're not using the console, your servlet may seem to work correctly (except that the output isn't displayed anywhere), but vqServer will eventually stop working when the output buffer is full.


vqServer version 1.9. Copyright © 1997-2000 Steve Shering and vqSoft. Last updated 17 June 2000.

vqServer
Contents
Servlets

Security
CGI scripts