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:

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.

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:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

The container MUST use case-sensitive string comparisons for matching.

In the Web application deployment descriptor, the following syntax is used to define mappings:

Request_URI = Context_Path [1] + Servlet_Path [2] + Path_Info [3] + Query_String [4]

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 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>
					
					

Professional hosting     Belorussian informational portal         Free SCBCD 1.3 Study Guide     Free SCDJWS 1.4 Study Guide     SCDJWS 1.4 Quiz     Free IBM Certified Associate Developer Study Guide     Free SCJP 5.0 (Tiger) Study Guide     Free Mock Exam Engine     IBM Test 000-287. Enterprise Application Development with IBM WebSphere Studio, V5.0 Study Guide