This chapter describes how to create servlets to control web application interactions running on a Sun Java System Web Server 7.0. In addition, this chapter describes the Sun Java System Web Server 7.0 features used to augment the Java Servlet 2.4 standards.
This chapter has the following sections:
Servlets, like applets, are reusable Java applications. Servlets, however, run on a web server rather than in a web browser.
Servlets provide a component-based, platform-independent method for building web-based applications without the performance overheads, process limitations, and platform-specific liabilities of CGI programs.
Servlets supported by the Sun Java System Web Server 7.0 are based on the Java Servlet 2.4 specification. Servlets are created compiled and packed into a Java web application archive WAR file and then deployed to the Web Server and managed at runtime by the servlet engine
Basic characteristics of servlets include the following:
Operate on input data that is encapsulated in a request object
Respond to a query with data encapsulated in a response object
Provide user session information persistence between interactions
Allow dynamic reloading while the server is running
Can be addressed with URLs. For examples, buttons on an application's pages often point to servlets
Can call other servlets and/or JSP pages
When a user clicks a Submit button, information entered in a display page is sent to a servlet. The servlet processes the incoming data and responds to generate content. Once the content is generated, the servlet creates a response page, usually by forwarding the content to a JSP. The response is sent back to the client, which sets up the next user interaction.
Information flows to and from the servlet according to the following high-level process:
The servlet processes the client request.
The servlet generates content.
The servlet creates a response and either sends back directly to the client or dispatches the task to JSP or to another servlet. The servlet remains in memory, available to process another request.
The two main servlet types are, generic and HTTP.
Generic servlets:
Extend javax.servlet.GenericServlet.
Contain no inherent HTTP support or any other transport protocol, so that protocol is independent.
HTTP servlets:
Extend javax.servlet.HttpServlet.
Contain built-in HTTP protocol support and are more useful in a Sun Java System Web Server 7.0 environment.
For both servlet types, you must implement the initializer method init() to allocate and initialize the servlet, and the destructor method destroy() to deallocate resources.
All servlets must implement a service() method, which is responsible for handling servlet requests. For generic servlets, override the service method to provide routines for handling requests. HTTP servlets provide a service method that automatically routes the request to another method in the servlet based on which HTTP transfer method is used. For HTTP servlets, override doPost() to process POST requests, doGet() to process GET requests, and so on.
To create a servlet, create a class that extends either GenericServlet or HttpServlet, overriding the appropriate methods so that the servlet handles request.
This section discusses the following topics:
To create a servlet, write a public Java class that includes basic I/O support as well as the package javax.servlet. The class must extend either GenericServlet or HttpServlet. Because Sun Java System Web Server 7.0 servlets exist in an HTTP environment, the latter class is recommended. If the servlet is part of a package, you must also declare the package name so the class loader can properly locate it.
The following example header shows the HTTP servlet declaration called MyServlet:
import java.io.*; import javax.servlet.*; import javax.servlet.http.*; public class myServlet extends HttpServlet { ...servlet methods... } |
Next, override one or more methods to provide the servlet with instructions to perform its intended task. All processing by a servlet is done on a request-by-request basis and happens in the service methods, either service() for generic servlets or one of the doOperation() methods for HTTP servlets. This method accepts requests processes them according to the instructions you provide, and directs the output appropriately. You can create other methods in a servlet as well.
Override the class initializer init() to initialize or allocate resources for the servlet instance's life, such as a counter. The init() method runs after the servlet is instantiated but before it accepts any requests. For more information, see the servlet API specification.
When extending GenericServlet or HttpServlet, you must either override init(ServletConfig) to first call super.init(ServletConfig) or simply override the init() method that takes no arguments. This your servlet's ServletConfig enables be saved locally and later returned by calls to your servlet's getServletConfig() method.
The following example of the init() method initializes a counter by creating a public integer variable called thisMany:
public class myServlet extends HttpServlet { int thisMany; public void init (ServletConfig config) throws ServletException { super.init(config); thisMany = 0; } } |
This method enables other servlet methods to access the variable.
Override the class destructor destroy() to write log messages or to release resources that have been opened in the servlet's cycle. Resources should be appropriately closed and de-referenced so that they are recycled or garbage collected. The destroy() method runs just before the servlet itself is deallocated from memory. For more information, see the servlet API specification.
For example, the destroy() method could write a log message like the following example, based on the example for Overriding init():
out.println("myServlet was accessed " + thisMany " times.\\n"); |
When a request is made, Sun Java System Web Server 7.0 sends incoming data to the servlet engine to process the request. The request includes form data, cookies, session information, and URL name-value pairs, all in a type HttpServletRequest object called the request object. Client metadata is encapsulated as a type HttpServletResponse object called the response object. The servlet engine passes both objects as the servlet's service() method parameters.
The default service() method in an HTTP servlet routes the request to another method based on the HTTP transfer method (POST, and GET). For example, HTTP POST requests are routed to the doPost() method, HTTP GET requests are routed to the doGet() method. This routing enables the servlet to perform different request data processing depending on the transfer method. Because the routing takes place in service(), you do not need to override service() in an HTTP servlet. Instead, override doGet(), anddoPost() depending on the expected request type.
The automatic routing in an HTTP servlet is based on a call to request.getMethod(), which provides the HTTP transfer method.
Override the service() method for generic servlets or the doGet() or doPost() methods for HTTP servlets to perform tasks needed to answer the request. Very often, these tasks collate the needed information (in the request object or in a JDBC result set object), and then passing the newly generated content to a JSP for formatting and delivery back to the client.
Most operations that involve forms use either a GET or a POST operation, so for most servlets you override either doGet() or doPost(). Implement both methods to provide for both input types or pass the request object to a central processing method, as shown in the following example:
public void doGet (HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { doPost(request, response); } |
All request-by-request traffic in an HTTP servlet is handled in the appropriate doOperation() method, including session management, user authentication, JSP pages, and accessing Sun Java System Web Server 7.0 features.
If a servlet calls the RequestDispatcher method include() or forward(), the request information is no longer sent as HTTP POST, and GET. In other words, if a servlet overrides doPost(), it may not process other servlets if the calling servlet happens to receive its data through HTTP GET. For this reason, be sure to implement routines for all possible input types. RequestDispatcher methods always call service().
For more information, see Calling a Servlet Programmatically.
Incoming data is encapsulated in a request object. For HTTP servlets, the request object type is HttpServletRequest. For generic servlets, the request object type is ServletRequest. The request object contains all request parameters, including custom values called attributes.
To access all incoming request parameters, use the getParameter() method, for example:
String username = request.getParameter("username"); |
Set and retrieve values in a request object using setAttribute() and getAttribute(), respectively, for example:
request.setAttribute("favoriteDwarf", "Dwalin"); |
From a Web Server's perspective, a web application is a series of unrelated server hits. No automatic recognition occurs if a user has visited the site before, even if the last interaction was seconds before. A session provides a context between multiple user interactions by remembering the application state. Clients identify themselves during each interaction by a cookie, or, in the case of a cookie-less browser, by placing the session identifier in the URL.
After a successful login, you should direct a servlet to establish the user's identity in a standard object called a session object that holds information about the current session, including the user's login name and any additional information to retain. Application components can then query the session object to obtain user authentication.
A session object can store objects, such as tabular data, information about the application's current state, and information about the current user. Objects bound to a session are available to other components that use the same session.
For more information about session objects, see Chapter 6, Session Managers.
By default, servlets are not thread-safe. The methods in a single servlet instance are usually executed numerous times simultaneously up to the available memory limit. Each execution occurs in a different thread, though only one servlet copy exists in the servlet engine.
This efficient system resource usage, is dangerous because of the way the environment Java language manages memory. Because variables belonging to the servlet class are passed by reference, different threads can overwrite the same memory space as a side effect. To make a servlet or a block within a servlet thread-safe, do one of the following:
Synchronize write access to all instance variables, as in public synchronized void method() (whole method) or synchronized(this) {...} (block only). Because synchronizing slows response time considerably, synchronize only blocks, or make sure that the blocks in the servlet do not need synchronization.
Web containers synchronize all access to their servlets only when javax.servlet.SingleThreadModel servlet is implemented.
javax.servlet.singleThreadModel is deprecated in Servlet 2.4.
For example, the following servlet has a thread-safe block in doGet() and a thread-safe method called mySafeMethod():
import java.io.*; import javax.servlet.*; import javax.servlet.http.*; public class myServlet extends HttpServlet { public void doGet (HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { //pre-processing synchronized (this) { //code in this block is thread-safe } //other processing; } public synchronized int mySafeMethod (HttpServletRequest request) { //everything that happens in this method is thread-safe } } |
Use the SingleThreadModel class to create a single-threaded servlet. When a single-threaded servlet is deployed to the Sun Java System Web Server 7.0, the servlet engine creates a servlet instance pool used for incoming requests, multiple copies of the same servlet in memory. You can change the number of servlet instances in the pool by setting the singleThreadedServletPoolSize property in the Sun Java System Web Server 7.0
Web application deployment descriptor. For more information, see Chapter 9, Deploying Web Applications. Servlet performance becomes slower due to traffic load, and any new requests must wait for a free instance in order to proceed. However, with distributed, load-balanced applications, the load automatically shifts to a less busy process.
For example the following servlet is completely single-threaded:
import java.io.*; import javax.servlet.*; import javax.servlet.http.*; public class myServlet extends HttpServlet implements SingleThreadModel { servlet methods... } |
If a servlet is specifically written as a single thread, the servlet engine creates a pool of servlet instances to be used for incoming requests. If a request arrives when all instances are busy, the request is queued until an instance becomes available.
The final user interaction activity is to provide a response page to the client. The response page can be delivered by creating a servlet response page or JSP response page.
Generate the output page within a servlet by writing to the output stream. The recommended generation method depends on the output type.
Always specify the output MIME type using setContentType() before any output commences, as follows
response.setContentType("text/html"); |
For textual output, such as plain HTML, create a PrintWriter object and then write to it using println, for example:
PrintWriter output = response.getWriter(); output.println("Hello, World\\n"); |
For binary output, write to the output stream directly by creating a ServletOutputStream object and then write to it using print(), for example:
ServletOutputStream output = response.getOutputStream(); output.print(binary_data); |
Servlets can invoke JSP files in two ways, the include() method and the forward() method.
The include() method in the RequestDispatcher interface calls a JSP file and waits for it to return before continuing to process the interaction. The include() method can be called multiple times within a given servlet.
This example shows a JSP file using include():
RequestDispatcher dispatcher = getServletContext().getRequestDispatcher("JSP_URI"); dispatcher.include(request, response); ... //processing continues |
The forward() method in the RequestDispatcher interface handles the JSP interaction control. The servlet is no longer involved with the current interactions output after invoking forward() therefore only one call to the forward() method can be made in a particular servlet.
You cannot use the forward() method if you have already defined a PrintWriter or ServletOutputStream object.
This example shows a JSP page using forward():
RequestDispatcher dispatcher = getServletContext().getRequestDispatcher("JSP_URI"); dispatcher.forward(request, response); |
You identify which JSP noun to call by specifying a Universal Resource Identifier (URI). The path is a String describing a path within the ServletContext scope. You can also use the getRequestDispatcher() method in the request object that takes a String argument indicating a complete path.
Identify
The getRequestDispatcher method is similar to the RequestDispatcher in the ServletContext. The servlet container uses the information in the request object to transform the given relative path to a complete current servlet path, for example:
RequestDispatcher dispatcher = req.getRequestDispatcher(“foo/bar”);
In the previous example getRequestDispatcher does not start with “/”. In Web Server 6.1, this syntax resulted in a URI such as /webapp/foo/bar. In Sun Java System Web Server 7.0, the URI appears as /webapp/current_servlet_path/foo/bar
For more information about JSP pages, see Chapter 5, Developing JavaServer Pages.
You can invoke a servlet by directly addressing it from a Web page with a URL or by calling it programmatically from an already running servlet.
You can call servlets by using URLs embedded as links in HTML or JSP pages. The format of these URLs is as follows:
http://server:port/context_roott/servlet/servlet_name?name=value
The following table describes each URL section.
Table 4–1 URL Fields for Servlets Within a Web Application
URL Element |
Description |
---|---|
server:port |
The IP address or host name and optional port number. To access the default web application for a virtual server, specify only this URL section. You do not need to specify the context_root or servlet_name unless you also wish to specify name-value parameters. |
context_root |
The context path without the leading “/” at which the web application is installed. |
servlet |
Only needed if no servlet-mapping is defined in the web.xml file. |
servlet_name |
The servlet-name (or servlet-mapping if defined) as configured in the web.xml file. |
?name=value... |
Optional servlet name-value parameters. |
In this example, example is the host name, MortPages is the context root, and calcMortgage is the servlet name:
http://www.example.com/MortPages/servlet/calcMortgage?rate=8.0&per=360&bal=180000
First, identify which servlet to call by specifying a URI. This URI is normally a path relative to the current application. For example, if your servlet is part of an application with a context root named OfficeFrontEnd, the URL to a servlet called ShowSupplies from a browser is as follows:
http://server:port/OfficeFrontEnd/servlet/ShowSupplies?name=value
You can call this servlet programmatically from another servlet in one of two ways.
To include another servlet's output, use the include() method from the RequestDispatcher interface. This method calls a servlet by its URI and waits for it to return before continuing to process the interaction. The include() method can be called multiple times within a given servlet.
For example:
RequestDispatcher dispatcher = getServletContext().getRequestDispatcher("/servlet/ShowSupplies"); dispatcher.include(request, response); |
To handle interaction control to another servlet, use the RequestDispatcher interfaces forward() method with the servlet's URI as a parameter.
This example shows a servlet using forward():
RequestDispatcher dispatcher = getServletContext().getRequestDispatcher("/servlet/ShowSupplies"); dispatcher.forward(request, response); |
By default, the System.out and System.err output of servlets is sent to the server log. During startup, server log messages are echoed to the System.err output. On Windows, no console is created for the System.err output.
You can change these defaults using the Admin Console. For more information, see Setting Up Logging for Your Server in Sun Java System Web Server 7.0 Administrator’s Guide.
Sun Java System Web Server 7.0 can cache the results of invoking a servlet, a JSP page, or any URL pattern to make subsequent invocations of the same servlet, JSP page, or URL pattern faster. The Sun Java System Web Server 7.0 caches the request results for a specific amount of time. In this way, if another data call occurs, the Sun Java System Web Server 7.0 can return the cached data instead of performing the operation again. For example, if your servlet returns a stock quote that updates every 5 minutes, you set the cache to expire after 300 seconds.
If caching is enabled, Sun Java System Web Server 7.0 can cache the results produced by the servlet javax.servlet.RequestDispatcher.include() or javax.servlet.RequestDispatcher.forward(). In Sun ONE releases, the result generated by a resource for which caching was enabled was never cached if that resource was the target of a javax.servlet.RequestDispatcher.include() or javax.servlet.RequestDispatcher.forward(). This result cached only if the resource was the target of the initial request.
<sun-web-app> <cache enable="true"> <cache-mapping> <servlet-name>TestServlet</servlet-name> <dispatcher>REQUEST</dispatcher> <dispatcher>FORWARD</dispatcher> </cahce-mapping> </cache> </sun-web-app>
Whether to cache results and how to cache them depends on the data involved. For example, you do not need to cache the results of a quiz submission because the input to the servlet is different each time. However, you could cache a high-level report showing demographic data taken from quiz results that is updated once an hour.
You can define how a Sun Java System Web Server 7.0 web application handles response caching by editing specific fields in the sun-web.xml file. In this way, you can create programmatically standard servlets that still take advantage of this feature.
For more information about JSP caching, see JSP Cache Tags.
Sun Java System Web Server 7.0 has the following web application response caching capabilities:
Caching is configurable based on the servlet name or the URI.
When caching is based on the URI, the URI can include user-specified parameters in the query string. For example, a response from /garden/catalog?category=roses is different from a response from /garden/catalog?category=lilies. These responses are stored under different keys in the cache.
Cache size, entry timeout, and other caching behaviors are configurable.
Entry timeout is measured from the time an entry is created or refreshed. You can override this timeout for an individual cache mapping by specifying the cache-mapping element timeout.
You can determine caching criteria programmatically by writing a cache helper class. For example, if a servlet only stores the time when a back-end data source was last modified, you can write a helper class to retrieve the last-modified timestamp from the data source and decide whether to cache the response based on that timestamp. See CacheHelper Interface.
You can determine cache key generation programmatically by writing a cache key generator class. See CacheKeyGenerator Interface.
All non-ASCII request parameter values specified in cache key elements must be URL encoded. The caching subsystem attempts to match the raw parameter values in the request query string.
The newly updated classes affect data what gets cached. The web container clears the cache during dynamic deployment or reloading of classes.
The following HttpServletRequest request attributes are:
com.sun.appserv.web.cachedServletName, the cached servlet target
com.sun.appserv.web.cachedURLPattern, the URL pattern being cached
If you enable caching but do not provide any special configuration for a servlet or JSP page, the default cache configuration is as follows:
The default cache timeout is 30 seconds.
Only the HTTP GET method is eligible for caching.
HTTP requests with cookies or sessions automatically disable caching.
No special consideration is given to Pragma:, Cache-control:, or Vary: headers.
The default key consists of the servlet path minus pathInfo and the query string.
A least-recently-used list is maintained to delete cache entries if the maximum cache size is exceeded.
Key generation concatenates the servlet path with key field values, if any are specified.
The CacheHelper interface includes the following information:
package com.sun.appserv.web.cache; import java.util.Map import javax.servlet.ServletContext; import javax.servlet.http.HttpServletRequest; /** CacheHelper interface is an user-extensible interface to customize: * a) the key generation b) whether to cache the response. */ public interface CacheHelper { // name of request attributes public static final String ATTR_CACHE_MAPPED_SERVLET_NAME = "com.sun.appserv.web.cachedServletName"; public static final String ATTR_CACHE_MAPPED_URL_PATTERN = "com.sun.appserv.web.cachedURLPattern"; public static final int TIMEOUT_VALUE_NOT_SET = -2; /** initialize the helper * @param context the web application context this helper belongs to * @exception Exception if a startup error occurs */ public void init(ServletContext context, Map props) throws Exception; /** getCacheKey: generate the key to be used to cache this request * @param request incoming <code>HttpServletRequest</code> object * @returns the generated key for this requested cacheable resource. */ public String getCacheKey(HttpServletRequest request); /** isCacheable: is the response to given request cacheable? * @param request incoming <code>HttpServletRequest</code> object * @returns <code>true</code> if the response could be cached. or * <code>false</code> if the results of this request must not be cached. */ public boolean isCacheable(HttpServletRequest request); /** isRefreshNeeded: is the response to given request to be refreshed? * @param request incoming <code>HttpServletRequest</code> object * @returns <code>true</code> if the response needs to be refreshed. * or return <code>false</code> if the results of this request * dont need to be refreshed. */ public boolean isRefreshNeeded(HttpServletRequest request); /** get timeout for the cached response. * @param request incoming <code>HttpServletRequest</code> object * @returns the timeout in seconds for the cached response; a return * value of -1 means the response never expires and a value of -2 indicates * helper cannot determine the timeout (container assigns default timeout) */ public int getTimeout(HttpServletRequest request); /** * Stop the helper from active use * @exception Exception if an error occurs */ public void destroy() throws Exception; }
The following example cache element in the sun-web.xml file:
<cache max-capacity="8192" timeout="60"> <cache-helper name="myHelper" class-name="MyCacheHelper"/> <cache-mapping> <servlet-name>myservlet</servlet name> <timeout name="timefield">120</timeout> <http-method>GET</http-method> <http-method>POST</http-method> </cache-mapping> <cache-mapping> <url-pattern> /catalog/* </url-pattern> <!-- cache the best selling category; cache the responses to -- this resource only when the given parameters exist. Cache -- only when the catalog parameter has qliliesq or qrosesq -- but no other catalog varieties: -- /orchard/catalogbest&category=lilies -- /orchard/catalogbest&category=roses -- but not the result of -- /orchard/catalog?best&category=wild --> <constraint-field name=best scope=request.parameter/> <constraint-field name=category scope=request.parameter> <value> roses </value> <value> lilies </value> </constraint-field> <!-- Specify that a particular field is of given range but the -- field does not need to be present in all the requests --> <constraint-field name=SKUnum scope=request.parameter> <value match-expr=qin-range> 1000 - 2000 </value> </constraint-field> <!-- cache when the category matches with any value other than -- a specific value --> <constraint-field name="category" scope="request.parameter> <value match-expr="equals" cache-on-match-failure="true">bogus</value> </constraint-field> </cache-mapping> <cache-mapping> <servlet-name> InfoServlet </servlet name> <cache-helper-ref>myHelper</cache-helper-ref> </cache-mapping> </cache>
For more information about the sun-web.xml caching settings, see Caching Elements.
The built-in default CacheHelper implementation enables web applications to customize the key generation. An application component in a servlet or JSP can set up a custom CacheKeyGenerator implementation as an attribute in the ServletContext.
The name of the context attribute is configurable as the value of the cacheKeyGeneratorAttrName property in the default-helper element of the sun-web.xml deployment descriptor. For more information, see default-helper.
The CacheKeyGenerator interface contains the following information:
package com.sun.appserv.web.cache; import javax.servlet.ServletContext; import javax.servlet.http.HttpServletRequest; /** CacheKeyGenerator: a helper interface to generate the key that * is used to cache this request. * * Name of the ServletContext attribute implementing the * CacheKeyGenerator is configurable via a property of the * default-helper in sun-web.xml: * <default-helper> * <property * name="cacheKeyGeneratorAttrName" * value="com.acme.web.MyCacheKeyGenerator" /> * </default-helper> * * Caching engine looks up the specified attribute in the servlet * context; the result of the lookup must be an implementation of the * CacheKeyGenerator interface. */ public interface CacheKeyGenerator { /** getCacheKey: generate the key to be used to cache the * response. * @param context the web application context * @param request incoming <code>HttpServletRequest</code> * @returns key string used to access the cache entry. * if the return value is null, a default key is used. */ public String getCacheKey(ServletContext context, HttpServletRequest request); }
Consider the following guidelines for improving servlet performance:
Increase the Java heap size to help garbage collection. The Java heap size can be adjusted by adjusting the values specified to the —Xms and —Xmx jvm- options in server.xml. For example, <jvm-options>-Xms128m-Xmx256m</jvm-options> sets the minimum Java heap size to 128 MB and 256 MB. For more information, see Sun Java System Web Server 7.0 Administrator’s Guide.
Set the stack space if applications use deep recursion, or in any cases where very complex JSP pages are used.
You can set the stack space using set-thread-pool-prop wadm command. For example, $wadm set-thread-pool-prop [other args] stack-size=544288. For more information, see Sun Java System Web Server 7.0 Update 1 NSAPI Developer’s Guide.
Use the NSAPI cache improve servlet performance in cases where the obj.conf configuration file has many directives. To enable the NSAPI cache, include the following line in magnus.conf:
Init fn="nsapi-cache-init" enable=true
Check whether the session ID generator that is used for servlet sessions employs cryptographically unique random number generation algorithms. This method might present a performance problem on older, slow machines. For more information, see Chapter 6, Session Managers.
Reduce the number of directories in the classpath.
Disable dynamic reloading.
Disable the Java Security Manager.
This section describes how Sun Java System Web Server 7.0 determines the character encoding for the servlet request and the servlet response. For information about encodings, see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html.
When processing the servlet request, the server uses the following order of precedence, first to last, to determine the character encoding for the request parameters:
The ServletRequest.setCharacterEncoding() method.
A hidden field in the form, if specified using the form-hint-field attribute of the parameter-encoding element in the sun-web.xml file. For more information about this element, see parameter-encoding Element.
The character encoding specified in the default-charset attribute of the parameter-encoding element in the sun-web.xml file. For more information about this element, see parameter-encoding Element.
When processing a servlet response, the server uses the following order of precedence, first to last, to determine the response character encoding:
The ServletResponse.setContentType () method or the ServletResponse.setLocale () method.
The default encoding, which is ISO-8859–1.
To specify the character encoding that should be set in the Content-type header of the response if the response locale is set using the ServletResponse.setLocale method, use the locale-charset-map under the locale-charset-info element in the sun-web.xml file. For more information about this element, see locale-charset-info Element
Netscape Enterprise Server/ iPlanet Web Server versions 4.0 and 4.1 supported the Java Servlet 2.1 specification. This specification did not include web applications. A deployment scheme was developed to make servlet deployment simpler. With the advent of Java web applications (WAR files) and their deployment descriptors, maintaining a proprietary deployment system is no longer necessary.
iPlanet Web Server 6.0 supported both types of deployment schemes, but the 4.x implementation (referred to as legacy servlets) was marked as deprecated (See Chapter 8 Legacy Servlet and JSP Configuration of the iPlanet Web Server, Enterprise Edition Programmer's Guide to Servlets).
Web Server versions 6.1 and 7.0 no longer support legacy servlets. The legacy properties files for the server you want to migrate (servlet.properties, context.properties, and rules.properties) are removed during migration.
Because no one-to-one mapping is possible for all of the features, legacy servlets cannot be migrated automatically. This section describes the main features involved in migrating legacy servlets to web applications.
This section includes the following topics:
In Sun Java System Web Server 7.0, JSP file by extension works as it did in previous releases. Any file name in the document tree with a suffix of .jsp is treated as a JSP environment as long as the Java is turned on for the virtual server.
Servlet extension is not supported in Sun Java System Web Server 7.0. You can deploy a web application to respond to a directory, but all of the servlets must be in the WEB-INF/classes directory of the web application. You can no longer copy a servlet in the .class file into the document tree and have it run as a servlet or have all of the contents of a directory run as a servlet. The web application treats only .class files as servlets.
The legacy servlet system used a two-step process of registering servlets (servlet.properties) and mapping them to a URL (rules.properties). In Sun Java System Web Server 7.0, the servlets must be moved into a web application. These settings will be maintained in the web.xml file of that web application.
A registered servlet has entries in both the servlet.properties and rules.properties files.
The following example uses a servlet file called BuyNow1A.class, which responds to /buynow. It is assumed that the web application is deployed at '/'
The servlet.properties file containing:
servlet.BuyNowServlet.classpath=D:/Netscape/server4/docs/ servlet/buy;D:/Netscape/server4/docs/myclasses servlet.BuyNowServlet.code=BuyNow1A servlet.BuyNowServlet.initArgs=arg1=45,arg2=online,arg3="quick shopping"
The rules.properties file has:
/buynow=BuyNowServlet
These settings must be translated to a web.xml setting. The servlet.properties setting translates into the servlet element.
The classpath is automated so no classpath setting is necessary. All classes to be used must be in the WEB-INF/classes directory or in a .jar file in the WEB-INF/lib directory of the web application.
The servlet-name element appears between the dots in the servlets.properties file. The code translates to the servlet-class, IntArgs translate to init-params. This entry will translate to the following entry:
<servlet> <servlet-name> BuyNowServlet </servlet-name> <servlet-class> BuyNow1A </servlet-class> <init-param> <param-value> arg1 </param-name> <param-value> 45 </pram-value> </init-param> <init-param> <param-name> arg2 </param-name> <param-value> online </param-value> </init-param> <init-param> <param-name> arg3 </param-name> <param-value> 'quick shopping" </param-value> </init-param> </servlet>
The rules.properties entries translate to servlet-mapping elements. This entry translates to the following entry:
<servlet-mapping> <servlet-name> BuyNowServlet </servlet-name> <url-pattern> /buynow </url-pattern> </servlet-mapping>
Some other entries in the servlet.properties file map to the web.xml file. This includes the following information:
Servlets.startup: This servlet should contain the load-on-startup element.
Servlets.config.reloadInterval: This setting translates to the dynamicreloadinterval attribute of the jvm element in servlet.xml. This instance-wide setting affects all virtual servers and all web applications.
Servlet.sessionmgr: This element translates to the session-manager element in the sun-web.xml.