Java Servlet Specification

This book is targeted for the Connected Edition. The Java Card 3 Platform consists of two editions.

• The Classic Edition is based on an evolution of the Java Card Platform, Version 2.2.2 and is backward compatible with it, targeting resource-constrained devices that solely support applet-based applications. You may disregard the specifications for the Connected Edition if you are interested in the functionality found only in the Classic Edition.
• The Connected Edition features a significantly enhanced runtime environment and a new virtual machine. It includes new network-oriented features, such as support for web applications, including the Java Servlet APIs, and also support for applets with extended and advanced capabilities. An application written for or an implementation of the Connected Edition may use features found in the Classic Edition. Therefore, you will need to use the specifications for both the Classic Edition and the Connected Edition.

This chapter introduces the use of servlets and servlet containers in the Java Card 3 Platform, Connected Edition.

---

1.1 Definition of a Servlet

A servlet is a Java technology-based web component, managed by a container, that generates dynamic content. Like other Java technology-based components, servlets are platform-independent Java classes that are compiled to platform-neutral byte code that can be loaded dynamically into and run by a Java technology-enabled web server. Containers, sometimes called servlet engines, are web server extensions that provide servlet functionality. Servlets interact with web clients via a request/response paradigm implemented by the servlet container.

---

1.2 Definition of a Servlet Container

The servlet container is a part of a web server or application server that provides the network services over which requests and responses are sent, decodes MIME-based requests, and formats MIME-based responses. A servlet container also contains and manages servlets through their life cycle.

A servlet container can be built into a host web server or installed as an add-on component to a web Server via that server’s native extension API. Servlet containers can also be built into, or possibly installed into, web-enabled application servers.

All servlet containers must support HTTP as a protocol for requests and responses, but additional request/response-based protocols such as HTTPS (HTTP over SSL) may be supported. The required versions of the HTTP specification that a container must implement are HTTP/1.0 and HTTP/1.1. Because the container may have a caching mechanism described in RFC2616(HTTP/1.1), it may modify requests from the clients before delivering them to the servlet, may modify responses produced by servlets before sending them to the clients, or may respond to requests without delivering them to the servlet under the compliance with RFC2616.

A servlet container may place security restrictions on the environment in which a servlet executes. In a Java Card Platform environment, these restrictions should be placed using the permission architecture. For example, some environments may limit the creation of a Thread object to insure that other components of the container are not negatively impacted.

---

1.3 Example of Servlet Invocation

The following is a typical sequence of interactions that occur when a servlet is invoked:

1. A client (for example, a web browser) accesses a web server and makes an HTTP request.

2. The request is received by the web server and handed off to the servlet container.

3. The servlet container determines which servlet to invoke based on the configuration of its servlets, and calls it with objects representing the request and response.

4. The servlet uses the request object to find out who the remote user is, what HTTP POST parameters may have been sent as part of this request, and other relevant data. The servlet performs whatever logic it was programmed with, and generates data to send back to the client. It sends this data back to the client via the response object.

5. Once the servlet has finished processing the request, the servlet container ensures that the response is properly flushed, and returns control back to the host web server.

---

1.4 Compatibility With Java Servlet Specification Version 2.4

The Java Servlet API for the Java Card Platform is a subset of the Java Servlet API v2.4. This section describes this subset and the compatibility issues introduced in the Java Card Platform version of the specification.

1.4.1 Features Not In The Java Card Platform Version

The following features that were in the Java Servlet Specification, v2.4, are not supported by this specification and have been removed from it:

• Dependencies on unsupported APIs (java.io.File, java.net.URL, java.util.Map, java.util.Set, java.security.cert.X509Certificate...)
• Dependencies on floating point support
• Dependencies on serialization and cloning support (java.io.Serializable, java.lang.Cloneable)
• Configuration of filters that are invoked under request dispatcher forward and include calls or under the error page mechanism
• Support for distributed container and session migration
• Some of the programmatic and declarative security features
• Support for deployment in web containers that are JavaServer Pages (JSP) enabled or part of a Java Platform, Enterprise Edition (“Java EE”) application server, especially web application environment and dependencies on other Java platform specifications:
• Java EE, version 1.4
• Java Server Pages (JSP), version 2.0
• Java Naming and Directory Interface (“J.N.D.I.”).

• All deprecated features

1.4.2 Backward Compatibility Support of Web Applications

Servlet containers implementing this specification are not required to support backward compatibility of applications written to any prior version of the Servlet API, such as the 2.2 and 2.3 versions of the API.

Servlet containers implementing this specification must support applications written to the Servlet API, version 2.4, provided they do not use any of the removed features listed below. Such applications may be developed and packaged using tools such as Integrated Development Environments (IDE) supporting the Servlet API, version 2.4.

1.4.3 Temporary Working Directories

In this version of the specification, a servlet container is not required to provide a private, temporary directory for each servlet context and make it available via the javax.servlet.context.tempdir context attribute. The javax.servlet.context.tempdir context attribute was therefore removed.

1.4.4 SSL Attributes

In this version of the specification, the javax.servlet.request.X509Certificate request attribute used for retrieving the SSL certificate associated with a request as an array of objects of type java.security.cert.X509Certificate was removed.

Developers must instead use the javacardx.servlet.request.X509Certificate request attribute. The object associated with this attribute is an object of type javax.microedition.pki.Certificate which corresponds to the web client’s subject certificate.

1.4.5 Removed Elements of the Deployment Descriptor

The following sections describe the elements removed from the Java Servlet Specification, Version 2.4 when creating this version of the specification, the Java Servlet Specification for the Java Card Platform, Version 3.0.1, Connected Edition.

1.4.5.1 Removed Elements for Deployment in Web Container JSP Pages Enabled or Part of a Java EE Application Server

The following elements, which exist in the web application deployment descriptor to meet the requirements of web containers that are JSP pages enabled or are part of a Java EE application server, were removed from this specification. They are not required to be supported by containers wishing to support only the servlet specification.

• Syntax for JSP configuration (jsp-config, jsp-file)
• Syntax for looking up JNDI objects (env-entry, ejb-ref, ejb-local-ref, resource-ref, resource-env-ref)
• Syntax for specifying the message destination (message-destination, message-destination-ref)
• Reference to a web service (service-ref)

1.4.5.2 distributable Element Removed

The following element was removed from the deployment descriptor schema in this version of the specification:

• The distributable element indicates that a web application is programmed appropriately to be deployed into a distributed servlet container.

This specification does not support session migration or distributed containers.

1.4.5.3 run-as Element Removed

The following element (part of the declarative security features) was removed from the deployment descriptor schema in this version of the specification:

• The run-as element specifies the identity to be used for the execution of a component (for example, a servlet).

1.4.5.4 dispatcher Element Removed

The following element was removed from the deployment descriptor schema in this version of the specification:

• The dispatcher element has four legal values: FORWARD, REQUEST, INCLUDE, and ERROR which indicate respectively that a Filter will be applied under RequestDispatcher.forward() calls, under ordinary client calls to the path or servlet, under RequestDispatcher.include() calls or under the error page mechanism. The absence of any dispatcher elements in a filter-mapping indicates a default of applying filters only under ordinary client calls to the path or servlet.

In this version of the specification, filters are only applied under ordinary client calls to the path or servlet.

1.4.5.5 auth-method Element Value CLIENT-CERT Removed

The following element value was removed from the deployment descriptor schema in this version of the specification:

• The CLIENT-CERT content in a sub-element auth-method element configures the authentication mechanism for the web application to use HTTPS (HTTP over SSL) client certificates for end user authentication.

1.4.6 realm-name Element Extended Applicability

The realm-name element may now be used for all authentication schemes and not just for BASIC authentication. The realm-name indicates the realm name to use for the authentication scheme chosen for the Web application.

1.4.7 Filtering of Authorization Request Header

This version of the specification requires that when an application is configured for container-managed HTTP Basic or Digest authentication, the web container filters out Authorization request headers so that they are not accessible to the application.

1.4.8 Web Application Deployment Hierarchy and Directory Structure

The following subdirectory of the web application directory structure is not supported in this version of the specification:

• The /WEB-INF/lib/*.jar area for Java Archive (JAR) files. These files contain servlets, beans, and other utility classes useful to the web application. The web application class loader must be able to load classes from any of these archive files.

Web applications depending on libraries external to the Web Archive (WAR) file must use an alternate deployment mechanism specific to the Java Card Platform, Version 3, Connected Edition.

The web container is not required to recognize the dependencies of a web application on specific versions of libraries external to the Web Archive (WAR), expressed in the manifest entry of the WAR following the rules defined by the Optional Package Versioning mechanism (http://java.sun.com/j2se/1.4/docs/guide/extensions/).

The contents of the WEB-INF/classes, WEB-INF/lib and META-INF directories, and the deployment descriptor WEB-INF/web.xml are not visible to servlet code using the getResourceAsStream method calls on the ServletContext, and are not exposed using the RequestDispatcher calls.

1.4.9 Usage of URL Patterns for Servlet Mapping, Filter Mapping and Security Constraints Restricted

This Java Card Platform version of the specification imposes the following restriction on the use of url-pattern for servlet mapping: the url-pattern values of the servlet-mapping elements must not overlap.

This Java Card Platform version of the specification imposes the following restriction on the use of url-pattern for filter mapping and security-constrained web resource collections: the url-pattern value for filter mapping and security-constrained web resource collections must exactly correspond to the url-pattern of one of the servlet-mapping elements defined for mapping request URI to servlets in the deployment descriptor.

The web container on a Java Card Platform implementation must reject any application that declares:

• values of servlet-mapping/url-pattern elements that overlap;
• a value of a filter-mapping/url-pattern element that does not correspond to one of the declared values of servlet-mapping/url-pattern elements;
• a value of a security-constraint/web-resource-collection/url-pattern element that does not correspond to one of the declared values of servlet-mapping/url-pattern elements.

1.4.10 Combination of Security Constraints Precluded

This Java Card Platform version of the specification imposes the following restriction on security constraints: the same url-pattern and http-method value pair must not appear in multiple constraints. This restriction also applies to security constraints which do not have an http-method element as it stands for all the possible values of the http-method element.

The web container on a Java Card Platform implementation must reject applications declaring in their deployment descriptors multiple security constraints with the same url-pattern and http-method value pair.

1.4.11 Default Servlet Implementation

In this Java Card Platform version of the specification, the doOptions and doTrace methods respond by default with an HTTP status code 501 (Not implemented). These methods must be explicitly implemented by servlet developers who want to support these features.

1.4.12 Classes, Interfaces and Methods Depending on API Not Supported on the Java Card Platform

Note that the following removals cause source incompatibility in some cases, such as when a developer uses these methods in a Servlet API v2.4 development environment and intends to deploy on the Java Card Platform.

1.4.12.1 java.io.Serializable Implementation Removed

The following classes are not serializable in this version of the specification:

• public abstract class GenericServlet implements javax.servlet.Servlet, javax.servlet.ServletConfig
• public abstract class HttpServlet extends javax.servlet.GenericServlet

1.4.12.2 java.lang.Cloneable Implementation Removed

The following class is not cloneable in this version of the specification:

public class Cookie

1.4.12.3 HttpSessionActivationListener Interface Removed

The following interface was removed in this version of the specification:

public interface HttpSessionActivationListener extends java.util.EventListener

Objects that are bound to a session may listen to container events notifying them that sessions will be made passive and that session will be activated. A container that migrates session between VMs or persists sessions is required to notify all attributes bound to sessions implementing HttpSessionActivationListener.

This specification does not support session migration or distributed containers.

1.4.12.4 ServletContext methods getResource and getResourcePaths Removed

The following methods were removed from the ServletContext interface in this version of the specification:

• public java.net.URL getResource(java.lang.String path) throws MalformedURLException

Returns a URL to the resource that is mapped to a specified path. The path must begin with a “/” and is interpreted as relative to the current context root.

• public java.util.Set getResourcePaths(java.lang.String path)

Returns a directory-like listing of all the paths to resources within the web application whose longest sub-path matches the supplied path argument.

1.4.12.5 ServletRequest and ServletRequestWrapper method getParameterMap Removed

The following method was removed from the ServletRequest interface and from the ServletRequestWrapper class in this version of the specification:

• public java.util.Map getParameterMap()

Returns a java.util.Map of the parameters of this request. Request parameters are extra information sent with the request.

1.4.12.6 getUserPrincipal method of HttpServletRequest and HttpServletRequestWrapper Removed

The following method (part of the programmatic security features) was removed from the HttpServletRequest interface and from the HttpServletRequestWrapper class in this version of the specification:

• public java.security.Principal getUserPrincipal()

Returns a java.security.Principal object containing the name of the current authenticated user.

1.4.12.7 ServletOuputStream methods print(float), print(double), println(float) and println(double) Removed

The following methods were removed from the ServletOutputStream class in this version of the specification:

• public void print(double d) throws IOException

Writes a double value to the client, with no carriage return-line feed (CRLF) at the end.

• public void print(float f) throws IOException

Writes a float value to the client, with no carriage return-line feed (CRLF) at the end.

• public void println(double d) throws IOException

Writes a double value to the client, followed by a carriage return-line feed (CRLF).

• public void println(float f) throws IOException

Writes a float value to the client, followed by a carriage return-line feed (CRLF).

1.4.13 Removed Classes, Interfaces and Methods Deprecated in Java Servlet API Specification Version 2.4

Note that the following removals cause source incompatibility in some cases, such as when a developer uses these methods in a Servlet API v2.4 development environment (where this deprecated classes, interfaces and methods may still be supported) and intends to deploy on the Java Card Platform.

1.4.13.1 SingleThreadModel Interface Removed

The following deprecated interface was removed in this version of the specification:

• public interface SingleThreadModel

Deprecated- As of Java Servlet API v2.4, with no direct replacement. Ensures that servlets handle only one request at a time. This interface has no methods.

1.4.13.2 HttpSessionContext Interface Removed

The following deprecated interface was removed in this version of the specification:

• public interface HttpSessionContext

Deprecated- As of Java Servlet API v2.1 for security reasons, with no replacement.

1.4.13.3 HttpUtils Class Removed

The following deprecated class was removed in this version of the specification:

• public class HttpUtils

Deprecated- As of Java Servlet API v2.3. These methods were only useful with the default encoding and have been moved to the request interfaces.

1.4.13.4 ServletContext methods getServlet, getServletNames, getServlets, and log Removed

The following deprecated methods were removed from the ServletContext interface in this version of the specification:

• public Servlet getServlet(java.lang.String name throws ServletException

Deprecated- As of Java Servlet API v2.1, with no direct replacement. This method was originally defined to retrieve a servlet from a ServletContext.

• public java.util.Enumeration getServletNames()

Deprecated- As of Java Servlet API v2.1, with no replacement. This method was originally defined to return an Enumeration of all the servlet names known to this context.

• public java.util.Enumeration getServlets()

Deprecated- As of Java Servlet API v2.0, with no replacement. This method was originally defined to return an Enumeration of all the servlets known to this servlet context.

• public void log(java.lang.Exception exception, java.lang.String msg)

Deprecated- As of Java Servlet API v2.1, use log(String, Throwable) instead. This method was originally defined to write an exception’s stack trace and an explanatory error message to the servlet log file.

1.4.13.5 getRealPath method of ServletRequest and ServletRequestWrapper Removed

The following deprecated method was removed from the ServletRequest interface and from the ServletRequestWrapper class in this version of the specification:

• public java.lang.String getRealPath(java.lang.String path)

Deprecated- As of Version 2.1 of the Java Servlet API, use ServletContext.getRealPath(String) instead.

1.4.13.6 UnavailableException constructors and method getServlet Removed

The following deprecated constructors and method were removed from the UnavailableException class in this version of the specification:

• public UnavailableException(int seconds, Servlet servlet, java.lang.String msg)

Deprecated- As of Java Servlet API v2.2, use UnavailableException(String, int) instead.

• public UnavailableException(Servlet servlet, java.lang.String msg)

Deprecated- As of Java Servlet API v2.2, use UnavailableException(String) instead.

• public Servlet getServlet()

Deprecated- As of Java Servlet API v2.2, with no replacement. Returns the servlet that is reporting its unavailability.

1.4.13.7 isRequestedSessionIdFromUrl method of HttpServletRequest and HttpServletRequestWrapper Removed

The following deprecated method was removed from the HttpServletRequest interface and from the HttpServletRequestWrapper class in this version of the specification:

• public boolean isRequestedSessionIdFromUrl()

Deprecated- As of Version 2.1 of the Java Servlet API, use isRequestedSessionIdFromURL() instead.

1.4.13.8 HttpServletResponse and HttpServletResponseWrapper methods encodeRedirecUrl, encodeUrl and setStatus Removed

The following deprecated methods were removed from the HttpServletResponse interface and from the HttpServletResponseWrapper class in this version of the specification:

• public java.lang.String encodeRedirectUrl(java.lang.String url)

Deprecated- As of version 2.1, use encodeRedirectURL(String url) instead.

• public java.lang.String encodeUrl(java.lang.String url)

Deprecated- As of version 2.1, use encodeURL(String url) instead.

• public void setStatus(int sc, java.lang.String sm)

Deprecated- As of version 2.1, due to ambiguous meaning of the message parameter. To set a status code use setStatus(int), to send an error with a description use sendError(int, String). Sets the status code and message for this response.

1.4.13.9 HttpSession methods getSessionContext, getValue, getValueNames, putValue and removeValue Removed

The following deprecated methods were removed from the HttpSession interface in this version of the specification:

• public HttpSessionContext getSessionContext()

Deprecated- As of Version 2.1, this method is deprecated and has no replacement. It will be removed in a future version of the Java Servlet API.

• public java.lang.Object getValue(java.lang.String name)

Deprecated- As of Version 2.2, this method is replaced by getAttribute(String).

• public java.lang.String[] getValueNames()

Deprecated- As of Version 2.2, this method is replaced by getAttributeNames().

• public void putValue(java.lang.String name, java.lang.Object value)

Deprecated- As of Version 2.2, this method is replaced by setAttribute(String, Object).

• public void removeValue(java.lang.String name)

Deprecated- As of Version 2.2, this method is replaced by removeAttribute(String).

1.4.13.10 Attributes Deprecated or Redundant in Java Servlet API Specification Version 2.4

The following attributes have been removed.

Error Handling Request Attributes exception-type and message Removed

In this version of the specification, the request attributes javax.servlet.error.exception_type and javax.servlet.error.message are not set by the container when the location of the error handler is a servlet. These attributes are redundant with the javax.servlet.error.exception request attribute.

Java Servlet Specification

5-30-09

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.