March 17, 2011, 11:38 a.m.
posted by maxidax
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).
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.
<?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.
<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.
188.8.131.52 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.
<?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).
<?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.