Skip Headers
Oracle® Application Server Web Services Developer's Guide
10g (10.1.3.5.0)
Part Number E13982-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

19 Packaging and Deploying Web Services

This chapter describes the packaging of Web service files and deployment support offered by Oracle Application Server Web Services. Except for a few details, Web services are packaged and deployed in the same manner as any other J2EE application.

This chapter has the following sections.

Note:

This chapter does not describe deployment itself. The deployment of Web modules and EJBs is covered in detail in the Oracle Containers for J2EE Deployment Guide.

Understanding Web Service Packaging

Web service files can be assembled and packaged by using either Oracle JDeveloper or WebServicesAssembler. The tools ensure that the correct files and deployment descriptors are included for the packaged application. Options in Oracle JDeveloper wizards and arguments to WebServicesAssembler commands allow you to configure values in the deployment descriptors that the Web service will use at runtime. The files are packaged into a deployable EAR file according to the rules outlined in the Enterprise Web Services 1.1 specification.

You can also assemble and package a Web service application by hand. Although this chapter describes Web service package structure and contents, it does not describe the details of manual assembly.

Deployment can be performed by using admin_client.jar on the command line, Ant tasks, or by using the Oracle JDeveloper or Application Server Control tools.

Table 19-1 summarizes the Oracle tools that can perform Web service packaging and deployment.

Table 19-1 Packaging and Deployment Support Offered by Oracle Tools


 WebServices- Assembler Oracle JDeveloper
 Application Server Control admin_client.jar Ant Tasks

Packaging

Yes

Yes

No

No

No

Deployment

No

Yes

Yes

Yes

Yes

As a final step, you can publish your deployed Web service to the Universal Description, Discovery, and Integration (UDDI) registry.

Note:

Packaging Structure for Web Service Applications

The Web service files which are intended for deployment to OC4J are included in a component deployment module. This component deployment module can be a JAR file for an EJB or a WAR file for Java classes. The component deployment module is then stored in a deployable EAR. The package structure for Web service files in an EAR file follows the rules defined by the Enterprise Web Services 1.1 specification. The following sections describe the packaging structure for Web services based on Java classes and EJBs.

Packaging for a Web Service Based on Java Classes

For a Web service based on Java classes, the EAR file contains a WAR file. The deployment and class files reside under the WEB-INF directory in the WAR. The WEB-INF directory contains the web.xml, webservices.xml, oracle-webservices.xml, and the JAX-RPC mapping file. It also contains a classes directory for the class files, a lib directory for the JAR files, and a wsdl directory for the WSDL.

The META-INF directory contains the MANIFEST.MF manifest file which defines extension and package related data and the application.xml file which specifies the components of a J2EE application.

Example 19-1 illustrates the packaging structure for a Web service based on Java classes.

Example 19-1 Packaging Structure for a Web Service Based on Java Classes

<serviceName>.ear        contains 
      META-INF/
         |--MANIFEST.MF
         |--application.xml

      <serviceName>.war  contains 
          WEB-INF/
             |--web.xml
             |--webservices.xml
             |--oracle-webservices.xml
             |--<mapping file>
             |--wsdl/
                  |--<serviceName>.wsdl
             |--classes/
                  |--class files
             |--lib/
                  |--*jar files

Packaging for a Web Service Based on EJBs

The packaging structure for a Web service based on EJBs is similar to Java classes, except the EAR file contains a META-INF directory for the manifest and a JAR file. Within the JAR file is another META-INF directory which contains the deployment and class files for the EJB. The META-INF directory within the JAR contains the ejb-jar.xml, webservices.xml, oracle-webservices.xml, and the JAX-RPC mapping file. It also contains the class files and a wsdl directory for the WSDL. Example 19-2 illustrates the packaging structure for a Web service based on EJBs.

Example 19-2 Packaging Structure for a Web Service Based on EJBs

<serviceName>.ear  contains
        META-INF/
           |--MANIFEST.MF
           |--application.xml

        <serviceName>.jar contains
              class files
              META-INF/
                  |--ejb-jar.xml
                  |--webservices.xml
                  |--oracle-webservices.xml
                  |--<mapping file>
                  |--wsdl/
                       |--<serviceName>.wsdl

Descriptions of Packaged Files

The following list describes the files that are packaged for deployment.

Relationships Between Deployment Descriptor Files

This section illustrates the relationships between the webservices.xml file and the ejb-jar.xml, oracle-webservices.xml, and web.xml files.

Relationships Between webservices.xml and ejb-jar.xml

Figure 19-1 illustrates the relationship between the contents of webservices.xml and ejb-jar.xml for Web services based on EJBs. The <ejb-link> element in webservices.xml provides the same value as <ejb-name> in ejb-jar.xml. This mapping identifies the EJB that is to be exposed as a Web service and hence over HTTP (SOAP over HTTP). The <service-endpoint-interface> element in webservices.xml provides the same value as <service-endpoint> element in ejb-jar.xml. This serves as an additional uniqueness constraint on the EJB.

Figure 19-1 Relationship Between webservices.xml and ejb-jar.xml

Described in the surrounding text.
Description of "Figure 19-1 Relationship Between webservices.xml and ejb-jar.xml"

Relationships Between webservices.xml and oracle-webservices.xml

Figure 19-2 illustrates the relationship between the contents of the J2EE standard webservices.xml deployment descriptor and the oracle-webservices.xml proprietary deployment descriptor. This relationship allows metadata to be mapped between files. The <port-component-name> element in webservices.xml provides the same value as the name attribute in <port-component name="..."> in oracle-webservices.xml. The <webservice-description-name> element in webservices.xml provides the same value as the name attribute in <webservice-description name="..."> in oracle-webservices.xml.

Figure 19-2 Relationship Between webservices.xml and oracle-webservices.xml

Described in the surrounding text.
Description of "Figure 19-2 Relationship Between webservices.xml and oracle-webservices.xml"

Relationships Between webservices.xml and web.xml

Figure 19-3 illustrates the relationship between the contents of webservices.xml and web.xml to identify the servlet that is to be exposed as a Web service The <servlet-link> element in webservices.xml provides the same value as the <servlet-name> present in web.xml. This allows the Web service implementation to be exposed as a servlet and hence over HTTP (SOAP over HTTP). This generalized approach allows application packages to be portable across J2EE containers implementing JAX-RPC and the Enterprise Web Services 1.1 specification. An application adhering to these standards can be deployed to any container that complies with the Enterprise Web Services 1.1 specification and can be invoked using any Web service client.

Figure 19-3 Relationship Between webservices.xml and web.xml

Described in the surrounding text.
Description of "Figure 19-3 Relationship Between webservices.xml and web.xml"

Tool Support for Packaging

This section describes the tool support for packaging Web service files offered by OracleAS Web Services. Packaging can be performed by WebServicesAssembler and by Oracle JDeveloper.

Packaging Support with WebServicesAssembler

This section describes the packaging support offered by WebServicesAssembler. The commands that assemble a Web service also package it in a deployable EAR file. In the course of assembling the files, many of these commands also create the deployment descriptors. The deployment descriptors contain the declarative data required to deploy the components as well as the assembly instructions that describe how the components are composed into an application.

WebServicesAssembler Commands that Perform Packaging

WebServicesAssembler provides several commands that assemble all of the files needed for a Web service.

WebServicesAssembler handles the generation of all relevant deployment descriptors and maps the proprietary configuration needed by the applications into Oracle specific deployment files. It also packages all of the relevant files so that they can be deployed to an application server.

These commands support arguments that let you package or save the generated files in a number of ways. The ear argument saves the files as a deployable EAR file. The war argument saves the files as a WAR file. The files are also be saved un-archived, in a directory that contains the contents of a WAR.

See Also:

Managing Deployment Descriptors

A number of WebServicesAssembler commands create deployment descriptors in the course of assembling a Web service. WebServicesAssembler does not perform deployment, but arguments to WebServicesAssembler commands will allow you to set values in the deployment descriptors.

Commands that Create Deployment Descriptors

Several of the WebServicesAssembler commands generate the application.xml, web.xml, webservices.xml, and oracle-webservices.xml deployment descriptors as part of their output. The commands that generate these files are:

Arguments that Affect Deployment Descriptor Contents

This section lists deployment descriptor files and identifies the WebServicesAssembler arguments that can affect their content.

application.xml:

  • context—when used for web applications, adds the <context-root> element.

oracle-webservices.xml:

  • callScope—adds the <param name="scope">call</param> element.

  • context—when used for EJB 2.1, adds the <context-root> element.

  • dataSource—adds the following param name attribute to the <implementor> element. In the following example, dataSource value is the value specified for the dataSource argument.

    <param name="databaseJndiName">dataSource value</param>

  • ddFileName—when used with the *Assemble commands, management and custom serialization information will be copied from the specified file to the oracle-webservices.xml file in the archive.

  • mtomSupport—adds the boolean <mtom-support> subelement to the <port-component> element.

  • restSupport—adds a boolean <rest-support> subelement to the <port-component> element and the <provider-port> element.

  • session—adds the <param name="scope">session</param> element.

  • timeout—adds the <param name="session-timeout">integer</param> element.

  • uri—when used for EJB 2.1, adds the <endpoint-address-uri> element.

  • useDimeEncoding—adds the <use-dime-encoding> element.

serviceName-java-wsdl-mapping.xml:

In this file name, serviceName indicates the name of the Web service (which is specified by the serviceName argument).

  • interfaceName—when used with the commands to assemble a Web service from database resources (plsqlAssemble, sqlAssemble, dbJavaAssemble, or aqAssemble) adds the <service-endpoint-interface> element.

web.xml:

  • className—adds the <servlet-class> element.

  • recoverable—adds a boolean <distributable> element.

  • uri—when used for web applications, adds the <url-pattern> element.

webservices.xml:

  • ejbName—adds the <ejb-link> element to webservices.xml for EJB 2.1 only.

  • interfaceName—adds the <service-endpoint-interface> element.

  • mappingFileName—adds the <jaxrpc-mapping-file> element. Note that the location and name of the file may be changed when put in the deployment descriptor. The contents of the file may be modified before being placed in the archive if some mappings were not defined in the original file.

  • <handler> tags—the data in handler tags are added to webservices.xml. These tags can be used only in Ant tasks.

Packaging Support with Oracle JDeveloper

Oracle JDeveloper provides wizards that can package your Web service application for deployment. For more information on the support offered by Oracle JDeveloper, see the following topics in the Oracle JDeveloper on-line help.

  • About J2EE Archive Formats

    Lists the archive types and their associated module types and contents, as supported by Oracle JDeveloper.

  • Configuring Applications for Deployment

    Provides links to topics dealing with the configuration and packaging of deployment descriptors, client applications, EJBs, and applets.

  • Configuring EJBs for Deployment

    Takes you through the steps of creating a EJB JAR File deployment profile and adding an ejb-jar.xml deployment descriptor.

  • Configuring a Client Application for Deployment

    Takes you through the steps of creating a client JAR file deployment profile and creating the application-client.xml deployment descriptor file.

  • Configuring an Applet for Deployment

    Takes you through the steps of creating a WAR File deployment profile and adding a web.xml deployment descriptor.

Understanding Web Service Deployment

Deployment is the process which transfers application files to the server where the application will run. The deployment of Web modules and EJBs is covered in detail in the following chapters of the Oracle Containers for J2EE Deployment Guide.

Web services can be deployed by using Oracle JDeveloper or Application Server Control. You can also deploy Web services by using Ant tasks or by using admin_client.jar on the command line.

See Also:

"Tool Support for Deployment" for more information on using these tools for deployment.

Tool Support for Deployment

This section describes the tool support for deployment offered by OracleAS Web Services. Deployment can be performed through the command line, Oracle JDeveloper, and Application Server Control.

Command Line Support for Deployment

The admin_client.jar command-line utility provided with OC4J can be used to deploy Web services packaged within an EAR file. You may want to use this utility if you plan to script the application deployment process. However, deploying standalone modules, such as a Web module packaged in a WAR file, is not supported using admin_client.jar.

See Also:

"Deploying Applications with admin_client.jar" in the Oracle Containers for J2EE Deployment Guide for instructions on deploying applications with this tool.

A Sample Deployment Using admin_client.jar

An EAR file containing files for a Web service can be deployed in the same way as other J2EE applications. The following is a sample deployment command.

java -jar <oc4jHome>/j2ee/home/admin_client.jar deployer:oc4j:<oc4jHost>:<oc4jOrmiPort> <adminId> <adminPassword>
            -deploy 
            -file dist/hello.ear 
            -deploymentName hello 
            -bindWebApp default-web-site

The following list describes the parameters in this code example.

  • <oc4jHome>—The directory containing the OC4J installation.

  • <oc4jHost>:<oc4jOrmiPort>—The host name and port of the OC4J server to which you are deploying the EAR file or J2EE application.

  • <adminId>—The user name for the OC4J instance. The user assigns this value when OC4J is installed.

  • <adminPassword>—The password for the OC4J instance. The user assigns this value when OC4J is installed.

  • default-web-site —The Web site to which the application will be bound. This is usually default-web-site. To configure Web sites, see the server.xml file in <oc4jHome>/j2ee/home/config.

Ant Task Support for Deployment

OracleAS Web Services provides a set of Ant tasks for deploying and undeploying J2EE applications and modules to an OC4J instance. "Deploying with the OC4J Ant Tasks" in the Oracle Containers for J2EE Deployment Guide describes the Ant tasks and provides guidelines for integrating the tasks into your application build process. This chapter includes the following topics.

  • "Incorporating the OC4J Ant Tasks into Your Environment" outlines the procedure for incorporating the OC4J Ant tasks into the build environment.

  • "Invoking the OC4J Ant Tasks" includes descriptions of how to invoke the following Ant tasks:

    • bindAllWebApps—The bindAllWebApps task binds the Web modules within a previously deployed EAR to a specified Web site.

    • bindWebApp—The bindWebApp task binds the application to the Web site that will be used to access it.

    • deploy—The deploy task deploys a J2EE application or module packaged in an archive.

    • deployerUri—The deployerUri task specifies the target OC4J instance or instances for the task.

    • modifySharedLibrary—The modifySharedLibrary task enables you to make changes to an existing shared library installed in an OC4J instance or in a group of instances across an Oracle Application Server cluster.

    • publishSharedLibrary—The publishSharedLibrary task installs a shared library in an OC4J instance or in a group of instances across an Oracle Application Server cluster.

    • removeSharedLibrary—The removeSharedLibrary task removes a shared library from an OC4J instance or from a group of instances across an Oracle Application Server cluster.

    • start, stop—The start and stop tasks start, stop, or restart an application and its child applications as part of a deployment operation on a specific OC4J instance.

    • undeploy—The undeploy task removes the specified application or module from the OC4J instance. This task also unbinds the application from the Web site automatically.

    • updateEjbModule—The updateEjbModule task allows incremental or partial redeployment of EJB modules within an application running in an OC4J instance or in a group of instances across an Oracle Application Server cluster.

Deployment Support with Oracle JDeveloper

The following list describes the topics available in the Oracle JDeveloper online help for deploying Web services. For more information on each of these topics, see the Oracle JDeveloper on-line help

  • Simple JAR Deployment

    Takes you through the steps of deploying your application to an executable JAR file, or a JAR file on your file system.

  • Deploying Web Services to Embedded OC4J

    Takes you through the steps of deploying your Web service to Oracle Application Server or an embedded instance of OC4J that runs on your local server.

  • Deploying Web Services to External OC4J

    Takes you through the steps of deploying your Web service to Oracle Application Server or an external instance of OC4J that runs on a remote server.

  • Deploying Secure Oracle Application Server Web Services

    Takes you through the steps of deploying a J2EE 1.4 Web service that uses security. The steps describe how to bundle the keystore with the Web service for deployment.

Deployment Support with Application Server Control

The following list describes the topics available in the Application Server Control on-line help for deploying Web services. For more information on each of these topics, see the Application Server Control on-line help

  • Deploy: Deployment Settings Page

    The deployment plan page provided with the Application Server Control Console includes the ability to set values in the OracleAS Web Services deployment descriptor (oracle-webservices.xml) at deployment time.

  • Deploy: Application Attributes Page

    Describes the deployment attributes that you can configure by using Application Sever Control.

  • Deploying an Application

    Takes you through the steps of deploying an application.

  • Redeploying and Undeploying Applications

    Takes you through the steps of redeploying or undeploying an application.

Limitations

See "Packaging and Deploying Web Services".

Additional Information

For more information on:

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us