Deploying JSEs





Deploying JSEs

Once you've developed the endpoint interface and implementation class for your JSE, you package it in a WAR file and deploy it into your J2EE application server. The following sections provide an overview of the JSE deployment process and detailed coverage of WAR packaging and the web.xml deployment descriptors.

1 Packaging JSEs in a WAR File

A WAR is just a JAR, except it has .war as the extension instead of .jar. WAR files, like JAR files, follow the zlib compression standards, which define algorithms for compressing and decompressing files, and packaging them in a single file. If you have ever used WinZip or any other ZIP program, then you've used zlib. In fact, you can create and open WAR and JAR files using WinZip and other zlib-based products. A WAR file usually contains compressed files that are organized into directories. Understanding that you can organize the contents of a WAR file into directories that are relative to the WAR file's root directory is important to understanding the rest of this section.

WAR files are used exclusively with Web components (servlets, JSPs, and JSEs) and must follow a specified directory structure. This structure dictates where the deployment descriptors, servlets, JSPs, JSEs, HTML pages, and images and other supporting files should be located in the WAR file. Basically, the directory structure must have a root and at least two subdirectories named META-INF and WEB-INF. In addition, you may include arbitrary subdirectories for images, HTML pages, etc. For example, an index.html page is customarily located in the root directory, while JPEG and GIF files may be contained in an images subdirectory, sound files in an audio subdirectory, and so on (see Figure).

The WAR Directory Structure

graphics/22fig01.gif

A WAR file defines a Web application, which is composed of servlets, JSPs, Web pages, and/or JSEs, all of which share a common set of resources, configuration properties, and an XML deployment descriptor. When a Web application is deployed, it's associated with a URL, so that the contents of the root directory and subdirectories of the WAR are mapped to that URL. For example, if the Web application were associated with the URL http://www.Monson-Haefel.com/jwsbook/, then the contents of the images subdirectory would be available at http://www.Monson-Haefel.com/jwsbook/images/. Similarly, if the WAR's root directory contained an index.html file, its URL would be http://www.Monson-Haefel.com/jwsbook/index.html.

Although the contents of the root and its subdirectories are accessible as URLs (once they're deployed), the contents of the META-INF and WEB-INF subdirectories are not publicly accessible—they may be accessed only by the container system and the Web components themselves. The META-INF directory contains meta-data about the JAR file and is generated automatically when you create the JAR file. The WEB-INF subdirectory is the most important directory for JSE deployments. It contains the deployment descriptors and the JSE endpoint and implementation class files, as well as any other classes or libraries that your JSE code depends on. Specifically, deployment descriptors are located directly in WEB-INF itself, while the Java classes and supporting libraries (usually other JAR files) are located in the WEB-INF/classes and WEB-INF/lib subdirectories. Figure depicts the locations of files in a WAR file. The gray areas are directories and file types that are optional for JSEs, the black areas are required.

Although the web.xml and webservices.xml deployment descriptors must be placed directly in the WEB-INF subdirectory, as in Figure, the WSDL documents, in this case bookquote.wsdl, are placed in the WEB-INF/wsdl subdirectory. In Figure the BookQuote application's WSDL document is placed in the wsdl directory under the WEB-INF directory. At runtime, the wsdl directory can be accessible to Web service clients directly. For example, you could access the bookquote.wsdl at http://www.Monson-Haefel.com/jwsbook/wsdl/bookquote.wsdl. In addition, WSDL and XSD documents imported by bookquote.wsdl must be stored in the /META-INF/wsdl directory, or its subdirectory, if they are imported using relative references—as opposed to explicit URLs.

When you're deploying Web services, you are mostly concerned with the WEB-INF and its wsdl subdirectory, and not with HTML pages, images, and other resources, because Web browsers do not usually access JSEs. They're typically accessed by client applications rather than people, and therefore do not generally provide HTML pages, images, and other visual artifacts. There are exceptions: You might want to document your Web service in HTML pages, or package JSEs with other servlets and JSPs.

22.3.2 The web.xml File

The usual role of a servlet deployment descriptor—always named web.xml—is to describe the runtime attributes of a servlet or JSP component. Because JSEs are actually embedded in a servlet at runtime, however, the servlet deployment descriptor —the web.xml file—has been co-opted to describe a JSE deployment. Actually, you can deploy servlets, JSPs, and JSEs all in the same WAR file, with the same web.xml file, but in this chapter we will be deploying a JSE by itself. The simplest web.xml file for deployment of the BookQuote JSE in J2EE 1.4, which is based on the Java Servlet 2.4 specification, looks like Listing 22-6.

Listing 22-6 A Simple web.xml File
<?xml version='1.0' encoding='UTF-8'?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                        http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4">

    <servlet>
        <servlet-name>BookQuoteJSE</servlet-name>
        <servlet-class>com.jwsbook.jaxprc.BookQuote_Impl</servlet-class>
    </servlet>
</web-app>

This web.xml file declares the BookQuote_Impl class in the servlet-class element. Normally, the servlet-class element describes a type of custom servlet, so using it for a JSE is a misnomer if there ever was one. BookQuote_Impl is not a servlet at all, so why declare it as such? The reason is simple: Declaring the JSE as the servlet-class is a way of supporting JSEs without having to change the existing format of the web.xml deployment descriptor.

The Web services deployment descriptor, webservices.xml, tells the container which "servlets" in the web.xml are actually JSEs. It does this by identifying a JSE and then referring to the servlet name that appears in the web.xml file. For example, the webservices.xml file in Listing 22-7 identifies the servlet named "Book QuoteJSE" in the web.xml file as a JSE, and tells the container where its WSDL file is located in the WAR, along with other information.

Listing 22-7 Identifying a JSE in a web.xml File
<webservices ...>
   <webservice-description>
       <webservice-description-name>BookQuote</webservice-description-name>
       <wsdl-file>/WEB-INF/wsdl/bookquote.wsdl</wsdl-file>
       <jaxrpc-mapping-file>/WEB-INF/bookquote.map</jaxrpc-mapping-file>
       <port-component>
          <port-component-name>BookQuoteJSE</port-component-name>
          <wsdl-port>
              <!-- the fully qualified name of the WSDL port goes here -->
          </wsdl-port>
          <service-endpoint-interface>com.jwsbook.jaxprc.BookQuote
          </service-endpoint-interface>
          <service-impl-bean>
             <servlet-link>BookQuoteJSE</servlet-link>
          </service-impl-bean>
       </port-component>
    </webservice-description>
</webservices>

The webservices.xml file provides information about the JSE that is not provided by the web.xml deployment descriptor. The same webservices.xml file is used for both JSEs and EJBs, so rather than repeat a description of the elements several times in this chapter, the webservices.xml file is covered in detail in Chapter 23: Web Service Descriptors.

22.3.2.1 Configuring the ServletContext

Because the JSE is embedded in a servlet at runtime, it can take advantage of many of the configuration capabilities of web.xml. For example, Section 10.2.3.2.3 explains that the JSE has access to the ServletContext interface at runtime. This interface provides, among other things, access to initialization properties, which can be very useful to your JSE. The web.xml file can configure the initialization properties using the context-param elements, as shown in Listing 22-8.

Listing 22-8 A web.xml File with Initialization Properties
<?xml version='1.0' encoding='UTF-8'?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                        http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4">

    <context-param>
        <param-name>Webmaster</param-name>
        <param-value>[email protected]</param-value>
    </context-param>
    <servlet>
        <servlet-name>BookQuoteJSE</servlet-name>
        <servlet-class>com.jwsbook.jaxprc.BookQuote_Impl</servlet-class>
    </servlet>
</web-app>

The JSE should be able to access the initialization parameters set by the context -param element at any time by invoking the ServletContext.getInit Parameter() method. See Section 10.2.3.2.3 for details on how to use the ServletContext interface.

2.2 Configuring the JNDI ENC

You also use web.xml to set the JNDI ENC entries used by the JSE. For example, Listing 22-9 shows a configuration for accessing a JDBC driver, an environment variable, and a local EJB reference using the JNDI ENC (access to these resources via the JNDI ENC is covered in Section 10.2.2).

Listing 22-9 Configuring the JNDI ENC in a web.xml File
<?xml version='1.0' encoding='UTF-8'?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                        http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4">

    <servlet>
        <servlet-name>BookQuoteJSE</servlet-name>
        <servlet-class>com.jwsbook.jaxprc.BookQuote_Impl</servlet-class>
    </servlet>
    <resource-ref>
         <res-ref-name>jdbc/BookDatabase</res-ref-name>
         <res-type>javax.sql.DataSource</res-type>
         <res-auth>Container</res-auth>
    </resource-ref>
    <env-entry>
         <env-entry-name>max_value</env-entry-name>
         <env-entry-type>java.lang.Double</env-entry-type>
         <env-entry-value>3929.22</env-entry-value>
    </env-entry>
    <ejb-local-ref>
         <ejb-ref-name>/ejb/BookHomeLocal</ejb-ref-name>
         <ejb-ref-type>Entity</ejb-ref-type>
         <local-home>com.companyz.BookHomeLocal</local-home>
         <local>com.companyz.BookLocal</local>
         <ejb-link>BookEJB</ejb-link>
     </ejb-local-ref>
</web-app>
2.3 Configuring Other Aspects of a JSE

In addition to setting up access to the initial parameters and the JNDI ENC, you can configure a variety of other aspects of the JSE's deployment, using configuration elements normally associated with servlets and JSPs. Detailed coverage of these configuration elements is outside the scope of this book, but Figure provides a list of elements and their meaning. For a complete understanding of servlet configuration, I suggest you consult the Java Servlet 2.4 specification, which can be downloaded from Sun Microsystems' Java Servlet home page, http://java.sun.com/products/servlet/index.html.

Configuration Elements

Configuration Element

Use or Meaning

<filter>
  <filter-name>SecurityFilter</filter-name>
  <filter-class>com.xyz.SecurityFilter
  </filter-class>
</filter>

You can configure filters that can pre-process a servlet request and post-process a servlet response. A filter is similar in purpose to a JAX-RPC handler, except it operates on the raw data stream rather than a SAAJ SOAP Message object. A filter class implements the javax.servlet.Filter interface.

It's possible to use filter objects in conjunction with handlers or instead of handlers to provide more control over the entire incoming and outgoing data stream, including HTTP headers.

<listener>
  <listener-class>com.xyz.SessionListener
  </listener-class>
</listener>

Servlet listeners are custom classes that are notified of state changes in ServletContext and HttpSession objects. ServletContext listeners are used to monitor and manage state and resources associated with servlets, while HttpSession listeners are used to monitor and manage state and resources associated with client sessions.

<servlet-mapping>
  <servlet-name>BookQuoteJSE</servlet-name>
  <url-pattern>/BookQuote</url-pattern>
</servlet-mapping>

A servlet-mapping element assigns a JSE to handle requests for a specific URL. Unlike servlets and JSPs, JSEs are not allowed to use wild-card characters—the URL specified must be an exact URL. In addition, there may be only one URL specified for a JSE.

When a JSE is deployed, the deployment tool will use this element to set the endpoint address of the JSE in the port element of the WSDL file.

<session-config>
  <session-timeout>60</session-timeout>
</session-config>

This element dictates the time, in minutes, that a client session will last before it times out. This is the period of inactivity, so as long as the client accesses the JSE before N minutes elapses, its session won't time out. A value of zero or less indicates that the session should never time out.

<security-constraint>
  <web-resource-collection>
    <web-resource-name>BookQuote
    </web-resource-name>
    <url-pattern>/BookQuote/*</url-pattern>
    <http-method>POST</http-method>
  </web-resource-collection>
  <auth-constraint>
    <role-name>employee</role-name>
    <role-name>client</role-name>
  </auth-constraint>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL
    </transport-guarantee>
  </user-data-constraint>
</security-constraint>

The security-constraint allows you to declare who can access which resources (servlets, JSPs, and JSEs) based on the URL of the request and, optionally, the type of HTTP request (GET or POST).

The URL and HTTP request type are set in the web-resource-collection element, while the names of parties authorized to access the resource are set in the auth-constraint element. The security names used in auth-constraint map to the security-role element, which is a logical identity that must be mapped to real security identities (individuals or groups) in the target environment at deployment time. Optionally, an asterisk (*) can be used to indicate that everyone has access.

The user-data-constraint allows you to configure the confidentiality and integrity of HTTP messages exchanged with a client. In most cases, a value of CONFIDENTIAL or INTEGRAL indicates the use of SSL (Secure Sockets Layer), while a value of NONE indicates that SSL is not used.[a]

<login-config>
  <auth-method>BASIC</auth-method>
  <realm-name>Monson-Haefel</realm-name>
</login-config>

The login-config element indicates the type of authentication used and the security realm that the client is to be authenticated in.

The auth-method element may have one of four values (BASIC, CLIENT-CERT, DIGEST, or FORM), but only two of them must be supported for Web services: BASIC, which corresponds to HTTP Basic Authentication and CLIENT-CERT, which corresponds to Symmetric HTTP. These types of authentication are explained in more detail in Section 10.2.3.2.1.

The value of the realm-name element may correspond to a security-policy domain, or some other mechanism. Its exact meaning depends on the J2EE vendor and the target environment.

<servlet>
  <servlet-name>BookQuoteJSE</servlet-name>
  <servlet-class>
    com.jwsbook.jaxprc.BookQuote_Impl
  </servlet-class>
  <init-param>
    <param-name>limit</param-name>
    <param-value>1000</param-value>
  </init-param>
</servlet>

The init-param elements, which are nested under the servlet element, are similar to the context-param elements, in that they provide initialization information to an individual servlet.

There is no way for a JSE to access values configured in the init-param elements, however, so they are essentially useless to you as a Web service developer. Use the context-param elements discussed in Section 22.3.2.1; they set context-wide initialization parameters that can be accessed via the ServletContext.

<servlet>
  <servlet-name>BookQuoteJSE</servlet-name>
  <servlet-class>
    com.jwsbook.jaxprc.BookQuote_Impl
  </servlet-class>
  <load-on-startup>5</load-on-startup>
</servlet>

The load-on-startup element, which is nested in the servlet element, indicates when the servlet container should load the JSE for receiving incoming messages. The value of this element must be a positive or negative integer. If it's negative, or if the element is omitted, the servlet container will not load the JSE until the first request for it is received. This option can conserve resources for infrequently used JSEs or other resources.

If the value of the load-on-startup element is a positive integer, it is loaded immediately, which avoids a slow response to the first request. The servlet container loads all Web components (servlets, JSPs, and JSEs) in the order of their load-on-startup element values. The lower the value, the sooner a component is loaded. Web components with a load-on-startup value of 1, for example, are loaded before resources with a load-on-startup value of 10.

<servlet>
  <servlet-name>BookQuoteJSE</servlet-name>
  <servlet-class>
    com.jwsbook.jaxprc.BookQuote_Impl
  </servlet-class>
  <run-as>
    <role-name>MHApplication</role-name>
  <run-as>
</servlet>

The run-as element, which is nested in the servlet element, determines the logical security identity under which the JSE will execute while processing requests. When the JSE accesses resources (JDBC, JMS, and so on) or EJBs, it propagates this identity as its own, for authentication and authorization purposes. The run-as element contains exactly one role-name element, whose value is a logical security name, which must be mapped to a real security identity in the target environment at deployment time.

<servlet>
  <servlet-name>BookQuoteJSE</servlet-name>
  <servlet-class>
    com.jwsbook.jaxprc.BookQuote_Impl
  </servlet-class>
  <security-role-ref>
    <role-name>MNGR</role-name>
    <role-link>manager</role-link>
  </security-role-ref>
</servlet>

The security-role-ref element, which is nested in the servlet element, can be used to test the principal identity of a client accessing the Web component (servlet, JSP, or JSE). This element is used with the HttpServlet Request object and is normally not available to the JSE, unless you are implementing a servlet filter.

[a] CONFIDENTIAL actually means that some type of security technology that ensures confidentiality of the communication is required. This may be TSL or some other mechanism, but in most cases vendors use SSL. INTEGRAL means that the message must use some type of integrity mechanism such as XML Digital Signature, or SSL/TSL or the like.


     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows