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
Parameters
Classes & Instances
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 website/servletdir first and then in your CLASSPATH.
  • If the real name does not include servletdir/ vqServer expects to find package/classname.class in 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

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. 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 the system CLASSPATH). In other words, the direcotory from which a servlet is loaded defines its name space.

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.
  • ServletResponse.getCharacterEncoding() always returns text/plain.
  • You can't use the file name part of an HTTP request to pass information to a servlet (pathinfo) unless the servlet is explicitly named in its own alias.


vqServer version 1.9. Copyright © 1997-99 Steve Shering and vqSoft. Last updated 21 July 1999.

vqServer
Contents
Servlets

Security
CGI scripts