This is the second draft specification of the Java Servlet Application Programming Interface (API). This draft is being distributed for public review. We will evaluate your feedback and incorporate comments into the next revision of the Servlet API, which will be part of the upcoming Jeeves Embedding Toolkit release. Please send comments to jeeves@java.sun.com
Servlets are Java objects that extend the functionality of information servers, such as HTTP or Web servers. A plain HTML document that a Web server retrieves is static. A servlet, on the other hand, is executed for every request so that it can output dynamic information. For example, a browser generates a request to a server for a document that contains dynamic information. The server examines the request and maps it to a particular servlet. It then invokes the servlet which creates the document with dynamic content and returns it to the client.
Servlets can do more than just return documents. Once a connection is established to the servlet both the client and servlet can speak a custom protocol using a new connection. Servlets can be thought of as server side applets. The difference is that servlets are faceless objects without a user interface. Servlets can be long-lived. A new servlet does not have to be created for every request. The server just needs to call the servlet method that can respond to the request. Servlets don't necessarily need to be running in an HTTP server. The servlet API is designed to be generic enough so that servlets can run in other types of servers on the web. Nevertheless, additional classes are provided for those servlets requiring access to HTTP protocol specific information.
Servlets can be dynamically loaded in a running server. They can be loaded from the local disk or from the network. Agents are programs that can roam a network, interact with the host, gather information, and come to the host where they originated. Servlet technology is an important step forward in achieving this goal.
The Java servlet application programming interface (API) is a standard for interfacing servlets with information servers, such as HTTP or Web servers. The servlet API contains methods for initializing a servlet, processing the request, getting servlet information, and destroying the servlet. The servlet API is simple, flexible, and stable. Application developers can write platform independent servlets and expect them to run on any server that supports the servlet API. This includes, but is not necessarily restricted to, servers supporting the HTTP protocol.
When the Web and HTTP servers became popular, the Common Gateway Interface (CGI) standard was devised for interfacing external applications with Web servers. A CGI application can be written in any language, for example C and PERL. CGI uses environment variables to send parameters to the application, for example QUERY_STRING and PATH_INFO. [1]. The two main drawbacks of using CGI are low performance (a new process has to be created for every request) and platform dependence. Also interaction between two CGI scripts running in the same server is complex.
FastCGI is an extension to CGI which uses persistent processes for for running external applications [2]. So a process does not have to be created for every request. But still the communication between the server and the application process can be slow since they are different processes.
To solve the performance problem C APIs (for example, NSAPI and ISAPI) were devised. The C modules run in the server process. The drawbacks of this approach are platform dependence, complexity, and lack of security.
Servlets solve the above problems and are flexible enough that you can write servlets to support applications written using the above approaches. For example one could write a FastCGIServlet which intercepts a request and communicates with the application using the FastCGI protocol.
Servlets are objects that implement the Servlet interface. This can be done automatically for most servlets by simply extending the GenericServlet base class, or HttpServlet in the case of a servlet that requires running in an HTTP server. The server uses the Servlet interface to exchange information with servlets. The server passes request and response objects that implement the ServletRequest and ServletResponse interfaces, respectively. The servlets use the ServletContext interface to exchange information with the server environment itself.
The server does the following:
Additional information on the servlet API can be found in the reference documentation for the packages java.servlet and java.servlet.http. There is also a package java.servlet.html containing utility classes for the dynamic generation of HTML.
The host server needs to ensure that a servlet does not compromise its security. In this section we describe one possible strategy which we have followed. We distinguish between two classes of servlets - trusted and untrusted. The decision to trust a servlet is up to the server. For example a server may decide to trust all local servlets and mistrust network servlets. Or it may decide to trust servlets that are signed by known entities.
Untrusted servlets are started in a separate threadgroup. The servlet security manager checks if the servlet is allowed to perform risky operations. Currently, there is no way in the java runtime to monitor the resource usage of a servlet.
SimpleServlet sends some basic HTML text when it is invoked.
import java.servlet.*;
public class SimpleServlet extends GenericServlet {
public void service(ServletRequest req, ServletResponse res) {
res.setContentType("text/html");
ServletOutputStream out = res.getOutputStream();
out.println("<HTML><HEAD>);
out.println("<TITLE>SimpleServlet Output</TITLE>");
out.println("</HEAD><BODY>");
out.println("<H1>SimpleServlet Output</H1>");
out.println("<P>This is output from SimpleServlet.");
out.println("</BODY></HTML>");
}
public String getServletInfo() {
return "A simple servlet";
}
}
IsPrimeServlet takes in a number as input and checks if it is prime.
import java.servlet.*;
public class IsPrimeServlet extends GenericServlet {
public void service(ServletRequest req, ServletResponse res) {
int number = Integer.parseInt(req.getParameter("number"));
boolean prime = isPrime(number);
res.setStatus(SC_OK);
res.setContentType("text/html");
res.writeHeaders();
ServletOutputStream out = res.getOutputStream();
out.println("<HTML><HEAD>);
out.println("<TITLE>IsPrimeServlet Output</TITLE>");
out.println("</HEAD><BODY>");
out.println("<H1>IsPrimeServlet Output</H1>");
out.println("<P>");
String output = "The number " + number + "is " +
+ prime?"":"not " + "prime.";
out.println(output);
out.println("</BODY></HTML>");
log(output);
}
static boolean isPrime(int i) {
int j;
if ((i<=0) || (i==1)) {
return false;
}
for (j = 2; j < i; j++) {
if ((i % j) == 0) {
return false;
}
}
return true;
}
public String getServletInfo() {
return "A servlet to test for prime numbers";
}
}