Describe the purpose and semantics for each of the following deployment descriptor
elements: error-page, init-param,
mime-mapping, servlet,
servlet-class, servlet-mapping,
servlet-name, and welcome-file.
Error pages.
To allow developers to customize the appearance of content returned to a Web client
when a servlet generates an error, the deployment descriptor defines a list of error
page descriptions. The syntax allows the configuration of resources to be returned
by the container either when a servlet or filter calls sendError
on the response for specific status codes, or if the servlet generates an exception
or error that propagates to the container.
If the sendError method is called on the response, the
container consults the list of error page declarations for the Web application that
use the status-code syntax and attempts a match. If there is a match, the container
returns the resource as indicated by the location entry.
A servlet or filter may throw the following exceptions during processing of a request:
runtime exceptions or errors
ServletExceptions or subclasses thereof
IOExceptions or subclasses thereof
The Web application may have declared error pages using the
exception-type element.
In this case the container matches the exception type by comparing
the exception thrown with the list of error-page definitions
that use the exception-type element. A match results in
the container returning the resource indicated in the location entry. The
closest match in the class heirarchy wins.
If no error-page declaration containing an
exception-type fits using the class-heirarchy match, and the
exception thrown is a ServletException or
subclass thereof, the container extracts the wrapped exception, as defined by the
ServletException.getRootCause method. A second pass is
made over the error page declarations, again attempting the match against the error
page declarations, but using the wrapped exception instead.
error-page declarations using
the exception-type element in the
deployment descriptor MUST be unique up to the class name of the
exception-type. Similarly, error-page
declarations using the status-code element MUST be unique in the
deployment descriptor up to the status code.
If a servlet generates an error that is not handled by the error page mechanism
as described above, the container must ensure to send a response with status 500.
The default servlet and container will use the sendError
method to send 4xx and 5xx status responses, so that the error mechanism may
be invoked. The default servlet and container will use the
setStatus method for 2xx and 3xx responses and will not
invoke the error page mechanism.
You can specify a mapping between the status code returned in an HTTP response
or a Java programming language exception returned by any Web component and a
Web resource. To set up the mapping, you add an error-page
element to the Web application deployment descriptor.
<!--
The error-page element contains a mapping between an error code or
exception type to the path of a resource in the web application
-->
<!ELEMENT error-page ((error-code | exception-type), location)>
The error-page contains a mapping between an error code or
an exception type to the path of a resource in the Web application. The
sub-element exception-type contains a fully qualified class
name of a Java exception type. The sub-element location
element contains the location of the resource in the web application relative to
the root of the web application. The value of the location MUST have a leading '/'.
<web-app>
...
<error-page>
<exception-type>exception.BookNotFoundException</exception-type>
<location>/errorpage.html</location>
</error-page>
</web-app>
<web-app>
...
<error-page>
<exception-type>exception.OrderException</exception-type>
<location>/errorpage.jsp</location>
</error-page>
</web-app>
<web-app>
...
<error-page>
<error-code>404</error-code>
<location>/404.html</location>
</error-page>
</web-app>
Init parameters.
After the servlet object is instantiated, the container must initialize the servlet before
it can handle requests from clients. Initialization is provided so that a servlet can
read persistent configuration data, initialize costly resources (such as JDBC
connections), and perform other one-time activities. The container initializes
the servlet instance by calling the init method of
the Servlet
interface with a unique (per servlet declaration) object implementing
the ServletConfig interface.
This configuration object allows the servlet to access name-value initialization
parameters from the Web application's configuration information.
<!--
The init-param element contains a name/value pair as an
initialization param of the servlet
-->
<!ELEMENT init-param (param-name, param-value, description?)>
A servlet configuration object used by a servlet container to pass information to a servlet
during initialization.
getInitParameter
Returns a String containing the value of the named
initialization parameter, or null if the parameter
does not exist.
getInitParameterNames
Returns the names of the servlet's initialization parameters as an
Enumeration of String objects,
or an EMPTY Enumeration if the servlet has no
initialization parameters.
public interface ServletConfig {
public java.lang.String getInitParameter(java.lang.String name);
public java.util.Enumeration getInitParameterNames();
}
<web-app>
...
<servlet>
<servlet-name>catalog</servlet-name>
<servlet-class>com.mycorp.CatalogServlet</servlet-class>
<init-param>
<param-name>bgcolor</param-name>
<param-value>yellow</param-value>
</init-param>
</servlet>
...
</web-app>
...
private String bgcolor;
public void init(ServletConfig config) throws ServletException {
super.init(config);
try {
bgcolor = config.getInitParameter("bgcolor");
System.out.println("bgcolor: " + bgcolor);
} catch (Exception e) {
System.out.println("error: " + e.toString());
}
}
MIME mapping.
The mime-mapping defines a mapping between an extension
and a mime type (example: "text/plain"). The extension
element contains a string describing an extension, such as "txt".
<!--
The mime-mapping element defines a mapping between an extension and
a mime type.
-->
<!ELEMENT mime-mapping (extension, mime-type)>
<web-app>
...
<mime-mapping>
<extension>pdf</extension>
<mime-type>application/pdf</mime-type>
</mime-mapping>
...
</web-app>
Servlet.
The servlet is used to declare a servlet. It contains the
declarative data of a servlet. The jsp-file element contains
the full path to a JSP file within the web application beginning with a "/". If
a jsp-file is specified and the
load-on-startup element is present, then the JSP should be
precompiled and loaded. The servlet-name element contains the
canonical name of the servlet. Each servlet name is UNIQUE within the web
application. The element content of servlet-name MUST NOT be
empty. The servlet-class contains the fully qualified class name of
the servlet. The run-as element specifies the identity to be
used for the execution of a component. It contains an optional description, and
the name of a security role specified by the role-name element.
The element load-on-startup indicates that this servlet should
be loaded (instantiated and have its init() called) on the
startup of the Web application. The element content of this element must be an
INTEGER indicating the order in which the servlet should be loaded. If the value is a
negative integer, or the element is not present, the container is free to load the servlet
whenever it chooses. If the value is a positive integer or 0, the container must load
and initialize the servlet as the application is deployed. The container must
guarantee that servlets marked with lower integers are loaded before servlets
marked with higher integers. The container may choose the order of loading of
servlets with the same load-on-startup value. The
security-role-ref element declares the security role reference
in a component's or in a deployment component's code. It consists of an optional
description, the security role name used in the code
(role-name), and an optional link to a security role
(role-link).
If the security role is not specified, the deployer must choose an appropriate security
role.
The servlet-class element contains the fully qualified class name
of the servlet.
<!--
The servlet element contains the declarative data of a
servlet.
If a jsp-file is specified and the load-on-startup element is
present, then the JSP should be precompiled and loaded.
-->
<!ELEMENT servlet (icon?, servlet-name, display-name?, description?,
(servlet-class|jsp-file), init-param*, load-on-startup?,
security-role-ref*)>
Servlet mapping.
The servlet-mapping defines a mapping between a
servlet and a URL pattern.
The path used for mapping to a servlet is the request URL from the request
object minus the context path and the path parameters. The URL path mapping
rules below are used in order. The first successful match is used with no further
matches attempted:
The container will try to find an exact match of the path of the request to the
path of the servlet. A successful match selects the servlet.
The container will recursively try to match the longest path-prefix. This is done
by stepping down the path tree a directory at a time, using the '/' character as
a path separator. The longest match determines the servlet selected.
If the last segment in the URL path contains an extension (e.g. .jsp), the
servlet container will try to match a servlet that handles requests for
the extension. An extension is defined as the part of the last segment
after the last '.' character.
If neither of the previous three rules result in a servlet match, the
container will attempt to serve content appropriate for the resource
requested. If a "default" servlet is defined for the application, it
will be used.
In the Web application deployment descriptor, the following syntax is used to define
mappings:
A string beginning with a '/' character and ending with a '/*' suffix is used
for path mapping.
A string beginning with a '*.' prefix is used as an extension mapping.
A string containing only the '/' character indicates the "default" servlet of
the application. In this case the servlet path is the request URI minus
the context path and the path info is null.
All other strings are used for exact matches only.
http://server.com/my_app_context[1]/catalog[2]/product[3]?mode=view[4]
Context path.
Specifies the path prefix associated with a web application mapping. For a default
application (rooted at the base of the web server's URL namespace), the context path is an
empty string. For a non-default application, the context path starts with a forward
slash ('/') but does not end with one. For example, /my_app_context maps
requests that include /my_app_context to the
my_app_context application. The
HttpServletRequest.getContextPath() method returns a string representing the context
path.
Servlet path.
Specifies the portion of the URL that matches the servlet mapping. This starts with a
slash ('/'). The HttpServletRequest.getServletPath() method returns a string
representing the servlet path.
Path information.
Comprises the remaining portion of the request path prior to query string parameters.
The HttpServletRequest.getPathInfo() method returns a string
representing the remainder of the path.
Query string.
Is contained in the request URL after the path.
The HttpServletRequest.getQueryString() method returns
null
if the URL does not have a query string. Same as the value of the CGI variable
QUERY_STRING.
<web-app>
...
<servlet-mapping>
<servlet-name>catalog</servlet-name>
<url-pattern>/catalog/*</url-pattern>
</servlet-mapping>
...
</web-app>
<!--
The servlet-mapping element defines a mapping between a servlet and
a url pattern
-->
<!ELEMENT servlet-mapping (servlet-name, url-pattern)>
Welcome files.
Web Application developers can define an ordered list of partial URIs called
welcome files in the Web application deployment descriptor.
The purpose of this mechanism is to allow the deployer to specify an ordered
list of partial URIs for the container to use for appending to URIs when there is a
request for a URI that corresponds to a directory entry in the WAR not mapped to
a Web component. This kind of request is known as a valid partial request.
The use for this facility is made clear by the following common example: A
welcome file of 'index.html' can be defined so that a request to a
URL like host:port/webapp/directory/, where
'directory' is an entry in the WAR that is
not mapped to a servlet or JSP page, is returned to the client as
'host:port/webapp/directory/index.html'.
If a Web container receives a valid partial request, the Web container must
examine the welcome file list defined in the deployment descriptor. The welcome
file list is an ordered list of partial URLs with no trailing or leading '/'. The Web
server must append each welcome file in the order specified in the deployment
descriptor to the partial request and check whether a static resource or servlet in
the WAR is mapped to that request URI. The Web container must send the request
to the first resource in the WAR that matches.
If no matching welcome file is found in the manner described, the container
may handle the request in a manner it finds suitable. For some configurations this
may mean returning a directory listing or for others returning a 404 response.
Consider a Web application where:
<welcome-file-list>
<welcome-file>index.html</welcome-file>
<welcome-file>default.jsp</welcome-file>
</welcome-file-list>
/foo/index.html
/foo/default.jsp
/foo/orderform.html
/foo/home.gif
/catalog/default.jsp
/catalog/products/shop.jsp
/catalog/products/register.jsp
A request URI of /foo will be redirected to a URI of
/foo/.
A request URI of /foo/ will be returned as
/foo/index.html.
A request URI of /catalog will be redirected to a URI of
/catalog/.
A request URI of /catalog/ will be returned as
/catalog/default.jsp.
A request URI of /catalog/index.html will cause a 404 (not found).
A request URI of /catalog/products will be redirected to a
URI of /catalog/products/.
A request URI of /catalog/products/ will be passed to the
"default" servlet, if any. If no "default" servlet is mapped, the request may
cause a 404 (not found), may cause a directory listing including
shop.jsp and register.jsp, or may cause other
behavior defined by the container.
<web-app>
...
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.html</welcome-file>
<welcome-file>index.htm</welcome-file>
</welcome-file-list>
...
</web-app>
The Java 2 Platform, Enterprise Edition defines a naming environment that allows applications to easily access
resources and external information without explicit knowledge of how the external information is named or organized.
As servlets are an integral component type of J2EE technology, provision has been made in the Web application
deployment descriptor for specifying information allowing a servlet to obtain references to
resources and enterprise beans. The deployment elements that contain this information are:
env-entry, ejb-ref, ejb-local-ref,
resource-ref, resource-env-ref.
NOTE, you NEED TO KNOW for the SCWCD Exam how to code the deployment descriptor and what it means for all of
the following tags:
env-entry
ejb-ref
ejb-local-ref
resource-ref
resource-env-ref
env-entry element
The env-entry declares an application's environment entry. The
sub-element
env-entry-name contains the name of a deployment component's environment
entry. The name is a JNDI name relative to the java:comp/env context. The name
MUST be unique within a deployment component. The env-entry-type contains
the fully-qualified Java type of the environment entry value that is expected by the
application's code. The sub-element env-entry-value designates the value of a
deployment component's environment entry. The value MUST be a String that is valid
for the constructor of the specified type that takes a single String as a parameter, or a
single character for java.lang.Character.
The following are the legal values of env-entry-type: java.lang.Boolean,
java.lang.Byte, java.lang.Character, java.lang.String,
java.lang.Short, java.lang.Integer, java.lang.Long,
java.lang.Float, java.lang.Double.
Example:
<env-entry>
<env-entry-name>test/MyEnv1</env-entry-name>
<env-entry-type>java.lang.Integer</env-entry-type>
<env-entry-value>10</env-entry-value>
</env-entry>
<env-entry>
<env-entry-name>test/MyEnv2</env-entry-name>
<env-entry-type>java.lang.Boolean</env-entry-type>
<env-entry-value>true</env-entry-value>
</env-entry>
ejb-ref element
The ejb-ref declares the reference to an enterprise bean's home. The
ejb-ref-name specifies the name used in the code of the deployment component
that is referencing the enterprise bean. The ejb-ref-type is the expected type of the
referenced enterprise bean, which is either Entity or Session. The home defines
the fully qualified name of the the referenced enterprise bean's home interface. The
remote defines the fully qualified name of the referenced enterprise bean's remote
interface. The ejb-link specifies that an EJB reference is linked to
the enterprise bean.
Example:
<ejb-ref>
<ejb-ref-name>ejb/RemoteSession</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>com.example.RemoteSessionHome</home>
<remote>com.example.RemoteSession</remote>
</ejb-ref>
ejb-local-ref element
The ejb-local-ref declares the reference to the enterprise bean's local home.
The local-home defines the fully qualified name of the enterprise bean's local
home interface. The local defines the fully qualified name of the enterprise bean's
local interface.
Example:
<ejb-local-ref>
<ejb-ref-name>ejb/LocalSession</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local-home>com.example.LocalSessionHome</local-home>
<local>com.example.LocalSession</local>
<ejb-link>LocalSession</ejb-link>
</ejb-local-ref>
resource-ref element
The resource-ref contains the declaration of a deployment component's
reference to the external resource. The res-ref-name specifies the name of a
resource manager connection factory reference. The name is a JNDI name relative
to the java:comp/env context. The name MUST be unique within a deployment file.
The res-type element specifies the type of the data source.
The type is the fully qualified Java language class or the interface expected to be implemented by the
data source. The res-auth specifies whether the deployment component code
signs on programmatically to the resource manager, or whether the container will
sign on to the resource manager on behalf of the deployment component. In the
latter case, the container uses the information supplied by the deployer.
The res-sharing-scope specifies whether connections obtained through the given
resource manager connection factory reference can be shared. The value, if specified, MUST be
either Shareable or Unshareable.
Example:
<resource-ref>
<res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
resource-env-ref element
The resource-env-ref contains the deployment component's reference to the
administered object associated with a resource in the deployment component's environment.
The resource-env-ref-name specifies the name of the resource
environment reference. The value is the environment entry name used in the deployment component code
and is a JNDI name relative to the java:comp/env context and MUST be
unique within the deployment component. The resource-env-ref-type specifies the type
of the resource environment reference. It is the fully qualified name of a Java language class or the interface.
Example:
<resource-env-ref>
<resource-env-ref-name>jms/StockQueue</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>
