Skip Headers

Oracle® Application Server Web Services Developer's Guide 10g Release 3 (10.1.3) B14434-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 18 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 does not describe deployment itself. The deployment of Web modules and EJBs is covered in detail in the Oracle Containers for J2EE Deployment Guide. For more information, see the Oracle Containers for J2EE Deployment Guide.

Web service files can be assembled and packaged by using either JDeveloper or WebServicesAssembler. The tools ensure that the correct files and deployment descriptors are included for the packaged application. Options in 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 JDeveloper or Application Server Control tools.

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

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

| WebServices- Assembler | 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. Discussion of UDDI is beyond the scope of this documentation. For more information about working with UDDI, see the following Web address.

`http://www.uddi.org/specification.html`

This chapter has the following sections.

- Packaging Web Service Applications

- Tool Support for Packaging

- Understanding Web Service Deployment

- Tool Support for Deployment

- oracle-webservices.xml Deployment Descriptor

## Packaging 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 following sections provide more detail on the packaging of Web service files.

- Packaging Structure for Web Service Applications

- Description of Packaged Files

### Packaging Structure for Web Service Applications

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

- Packaging for a Web Service Based on 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 18-1 illustrates the packaging structure for a Web service based on Java classes.

Example 18-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 18-2 illustrates the packaging structure for a Web service based on EJBs.

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

### Description of Packaged Files

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

- `application.xml`—describes all of the WARs and EJB JARs in the EAR. It specifies the components of a J2EE application, such as EJB and Web modules, can specify additional configuration for the application as well. This descriptor must be included in the `/META-INF` directory of the application's EAR file. The `application.xml` file is defined by the `application_1_4.xsd` schema located at the following Web site.

  `http://java.sun.com/xml/ns/j2ee/application_1_4.xsd`

- `ejb-jar.xml`—the deployment descriptor for an EJB component. It defines the specific structural characteristics and dependencies of the Enterprise JavaBeans within a JAR, and provides instructions for the EJB container about how the beans expect to interact with the container.

  There is a relationship between the contents of `webservices.xml` and `ejb-jar.xml` to identify the EJB exposed as a Web service. Figure 18-1 illustrates this relationship.

  The `ejb-jar.xml` file is defined by the schema located at the following Web site.

  `http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd`

- `<`mapping file`>.xml` (for example, serviceName`_java-wsdl-mapping.xml`)—the JAX-RPC mapping file that maps Java interfaces, methods, and parameters to the WSDL. For more information on this file, see JAX-RPC Mapping File Descriptor in the Oracle Application Server Advanced Web Services Developer's Guide.

- `oracle-webservices.xml`—a deployment descriptor that defines deployment properties specific to a Web service application running on OracleAS Web Services. For more information on the contents of this file, see "oracle-webservices.xml Deployment Descriptor".

- `web.xml`—this deployment descriptor is defined by the Java Servlet 2.4 specification. This deployment descriptor can be used to deploy a Web application on any J2EE-compliant application server. For more information on the `web.xml` file, see the Java Servlet 2.4 specification at the following Web site.

  `http://jcp.org/aboutJava/communityprocess/final/jsr154/index.html`

  There is a relationship between the contents of `webservices.xml` and `web.xml` to identify the servlet exposed as a Web service. Figure 18-2 illustrates this relationship.

  The `web.xml` file is defined by the `web-app_2_4.xsd` schema located at the following Web site:

  `http://java.sun.com/xml/ns/j2ee/`

- `webservices.xml`—a standard configuration file for a Web Service application packaged within a component deployment module. It defines the Web service endpoint, associated configuration files, WSDL information, and JAX-RPC mapping data. It provides the location of the WSDL file (`<wsdl-file>`), the mapping file (`<jaxrpc-mapping-file>`), the `<port-component>` corresponding to the ports in the WSDL, the Java service endpoint interface (`<service-endpoint-interface>`), the Java representation of the WSDL, and the servlet name (`<servlet-link>`) or EJB name (`<ejb-link>`).

  There is a relationship between the contents of `webservices.xml` and the `ejb-jar.xml`, `oracle-webservices.xml`, and `web.xml` files. These relationships identify the component being exposed as a Web service and to pass metadata between files. "Relationships Between Deployment Descriptor Files" provides more information on these relationships.

  The `webservices.xml` file is defined by the `j2ee_web_services_1_1.xsd` schema located at the following Web site:

  `http://java.sun.com/xml/ns/j2ee/`

- WSDL file—describes the interface of the Web service and the format of the messages used to invoke it. If an archive containing a Web service does not include a Web Services Description Language (WSDL) document, OracleAS Web Services will generate a WSDL document at deployment time. The WSDL is defined by the specification located at the following Web site.

  `http://www.w3.org/TR/wsdl`

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

##### webservices.xml and ejb-jar.xml

Figure 18-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 18-1 Relationship Between webservices.xml and ejb-jar.xml

Description of "Figure 18-1 Relationship Between webservices.xml and ejb-jar.xml"

##### webservices.xml and oracle-webservices.xml

Figure 18-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 18-2 Relationship Between webservices.xml and oracle-webservices.xml

Description of "Figure 18-2 Relationship Between webservices.xml and oracle-webservices.xml"

##### webservices.xml and web.xml

Figure 18-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 18-3 Relationship Between webservices.xml and web.xml

Description of "Figure 18-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 JDeveloper.

- Packaging Support with WebServicesAssembler

- Packaging Support with 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 Packaging Commands

- Managing Deployment Descriptors

#### WebServicesAssembler Packaging Commands

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

- aqAssemble

- assemble

- corbaAssemble

- dbJavaAssemble

- ejbAssemble

- jmsAssemble

- plsqlAssemble

- sqlAssemble

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. For more information on these commands, see "Web Service Assembly Commands".

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 can also be saved un-archived, in a directory that contains the contents of a WAR. For more information on these arguments, see "ear" and "war".

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

- Creating Deployment Descriptors

- Arguments that Affect Deployment Descriptor Contents

##### Creating 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:

- aqAssemble

- assemble

- corbaAssemble

- dbJavaAssemble

- ejbAssemble

- jmsAssemble

- plsqlAssemble

- sqlAssemble

- topDownAssemble

- genApplicationDescriptor (generates `application.xml` only)

- genDDs

##### Arguments that Affect Deployment Descriptor Contents

Calling WebServicesAssembler commands with the following arguments will affect the content of elements in the following deployment descriptors.

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.

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

query-java-wsdl-mapping.xml:

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

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

- About J2EE Archive Formats

  Lists the archive types and their associated module types and contents, as supported by 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.

- For guidelines on deploying WAR files into OracleAS Web Services, see "Deploying Web Modules".

- For guidelines on deploying EJB archives, see "Deploying Enterprise JavaBeans".

- For guidelines on deploying applications from the command line, see "Deploying Applications with admin_client.jar".

- For guidelines on deploying applications from Ant tasks, see "Deploying with the OC4J Ant Tasks".

Web services can be deployed by using 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. For more information on using these tools for deployment, see "Tool Support 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, JDeveloper, and Application Server Control.

- Command Line Support for Deployment

- Ant Task Support for Deployment

- Deployment Support with JDeveloper

- Deployment Support with 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 "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 the Build 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:

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

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

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

### Deployment Support with JDeveloper

The following list describes the topics available in the JDeveloper online help for deploying Web services. For more information on each of these topics, see the 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

T he 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.

## oracle-webservices.xml Deployment Descriptor

The `oracle-webservices.xml` deployment descriptor is used in conjunction with the standard `webservices.xml`. It contains deployment and run-time information that is specific to OracleAS Web Services. For example, it contains the context-URI, the Web service end-point address, and so on. All of the elements in `oracle-webservices.xml` are optional. If the file is not provided, the application will still deploy and run, with appropriate default values for the unspecified elements.

Although you could manually create `oracle-webservices.xml` by examining the schema, you will typically use the version of the file created by WebServicesAssembler. You can edit this file to produce the functionality you want.

The `oracle-webservices.xml` deployment descriptor contains the Web services management information for security, reliability, auditing, and logging. On deployment, the file is parsed and its object representation is cached. The Web service management information is extracted from the file and saved as `wsmgmt.xml` in the OC4J container.

### Components in oracle-webservices.xml

The following sections describe the configuration elements in the `oracle-webservices.xml` deployment descriptor. Some elements in the file can be changed by WebServicesAssembler command line arguments. These arguments are listed in "Arguments that Affect Deployment Descriptor Contents".

This file also includes the configuration elements for Web services management: security, reliability, logging, and auditing. These configuration elements are described in "Understanding the Web Services Management Schema" in the Oracle Application Server Advanced Web Services Developer's Guide.

#### <oracle-webservices> Element

The `<oracle-webservices>` element captures information local to the Oracle container for Web services. It has one attribute: `noNamespaceSchemaLocation`. This attribute is the "standard" way of telling the parser which schema the XML document should adhere to.

Table 18-2 describes the sub-elements contained in the `<oracle-webservices>` element.

Table 18-2 oracle-webservices Sub-elements

Sub-element | Description
--- | ---
<web-site> | Type `web-site` Default: the location where the service endpoint interface is installed (Optional) This sub-element provides a name for the host and the port name which will be substituted inside the updated WSDL port location. For example, you might need to enter this sub-element in the `oracle-webservices.xml` file if you are accessing the Web service by `port-component-link` resolution, or if you are publishing the WSDL to a location specified by `wsdl-publish-location`. This sub-element has the following attributes: `host`—the name for the host `port`—the name for the port If this sub-element is not used, the host and port values of the HTTP request used to get the WSDL will be substituted.
<context-root> | Type `string` Default: the EJB archive file name without the`.jar` extension This sub-element specifies the root context of the exposed Web service. It is required only for a version 2.1 EJB exposed as a Web service. If `context-root` is not specified, it defaults to the EJB archive file name without the`.jar` extension. For example, if the EJB archive file is named `foo-ejb.jar`, then the context root will be `/foo-ejb`. For Java-class Web services, the context root is specified inside `application.xml`. The Oracle Containers for J2EE Configuration and Administration Guide provides more information on the `<context-root>` element.
<webservice-description> | See "<webservice-description> Element".

#### <webservice-description> Element

This element extends the `<webservice-description>` element in the standard deployment descriptor, `webservices.xml`. The `name` attribute maps to the `name` element in `webservices.xml`. Table 18-3 describes the sub-elements contained in `<webservice-description>`.

Table 18-3 <webservice-description> Sub-elements

Sub-element | Description
--- | ---
<expose-wsdl> | Type `Boolean` Default: `true` This sub-element specifies whether the WSDL should be exposed.
<expose-testpage> | Type `Boolean` Default: `true` This sub-element specifies whether the test-page should be exposed.
<resolve-relative-imports> | Type `Boolean` Default: `false` This sub-element is used to specify whether you want to resolve from relative imports to absolute URLs.
<download-external-imports> | Type `Boolean` Default: `false` This sub-element specifies whether the relative imports should be downloaded and resolved to absolute URLs. Note: if `download-external-imports` is set to `true`, then `resolve-relative-imports` is automatically set to `true`.
<wsdl-file> | Type `wsdl-file` Default: n/a This sub-element is generated at deployment time and cannot be specified by an end-user. Its `final-location` attribute specifies the location of the final updated WSDL.
<wsdl-publish-location> | Type: `anyURI` Default: n/a (Optional) This element is used to specify the location where the final WSDL and its dependent files (imports) can be placed. The value should be of the form `file:/`location`/`'
<port-component> | See "<port-component> Element".

#### <port-component> Element

This `<port-component>` element is used as a reference to map to similar elements in the standard deployment descriptor `webservices.xml` with a `-name` appended to them. The elements contain information pertaining to a particular port. The `name` attribute of `<port-component>` maps to the `name` element in `webservices.xml`. Table 18-4 describes the sub-elements contained in the `<port-component>` tag.

Table 18-4 <port-component> Sub-elements

Sub-element | Description
--- | ---
<endpoint-address-uri> | Type: `string` Default: n/a This sub-element, needed only for an EJB 2.1 Web service, specifies the sub-context of the HTTP URL at which this EJB is exposed as a Web service. If none is provided, it defaults to the `port-component` name. Two transport-level elements are provided to secure this URI. For more information on these elements, see "<ejb-transport-security-constraint> Element" and "<ejb-transport-login-config> Element". For a Web module, (Web services derived from Java classes), this information is already present in the `web.xml` file and is not required.
<implementor> | Type: `implementor` Default: n/a This sub-element captures information about OC4J's proprietary Web services. This sub-element has a `param` attribute.
<max-request-size> | Type: `long` integer Default: -1 This sub-element enables you to configure a maximum size, in bytes, for a message passed to the Web service. If the Web service reads a message that passes this number of bytes, then the transmission will fail and the connection will close. If a non-positive value is assigned, then it is assumed there is no limit. The default, `-1` means unlimited. There is no limit as to the size.
<ejb-transport-security-constraint> | Defines transport-level security for a Web service based on EJBs. See "<ejb-transport-security-constraint> Element".
<runtime> | Denotes the start of the Web services management information. For more information, see "Understanding the Web Services Management Schema" in the Oracle Application Server Advanced Web Services Developer's Guide.
<use-dime-encoding> | Type: `Boolean` Default: `false` If set to true, any SOAP responses returned from this service that have attachments will be encoded in DIME. If false (default), any SOAP responses with attachments will be returned in MIME encoding. See "Working with DIME Attachments" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on DIME-encoded attachments.
<jms-address> | Type: `jms-address` Default: n/a The address element used for providing JMS destination information. This is used when JMS transport is specified to send SOAP messages over JMS.
<rest-support> | Type: `Boolean` Default: `false` The rest element indicates whether this port supports REST-style `GET` and `POST` requests and responses.

### Securing EJB-Based Web Services at the Transport Level

The `oracle-webservices.xml` deployment descriptor provides two elements that allow you to define transport-level security for Web services that are based on EJBs. These elements are described in the following sections. For more information on this topic, see also "Adding Transport-level Security for Web Services Based on EJBs" and "Accessing Web Services Secured on the Transport Level" in the Oracle Application Server Web Services Security Guide.

- <ejb-transport-security-constraint> Element

- <ejb-transport-login-config> Element

#### <ejb-transport-security-constraint> Element

This element is used to associate transport-level security constraints for a version 2.1 EJB exposed as Web service. The URL of the EJB exposed as a Web service is indicated by the `<endpoint-address-uri>` element in the port component.

The sub-elements `<wsdl-url>` and `<soap-port>` are identifiers that let you choose whether the security constraints will apply to a WSDL URL or to a SOAP port. If `<wsdl-url>` and `<soap-port>` are both present or both absent in `<ejb-transport-security-constraint>` then the security constraints will apply to both the WSDL and the SOAP port. Table 18-5 describes the sub-elements of `<ejb-transport-security-constraint>`.

Table 18-5 <ejb-transport-security-constraint> Sub-elements

Sub-element | Description
--- | ---
<wsdl-url> | Type: (element identifier) Default: n/a If present, this sub-element specifies that the security constraints must apply only to the WSDL URL.
<soap-port> | Type: (element identifier) Default: n/a If present, this sub-element specifies that the security constraints must apply only to the SOAP port.
<role-name> | Type: `string` Default: n/a This sub-element identifies the name of a security role. The name must conform to the lexical rules for a token. The `role-name` used here must correspond to either: the role name of one of the security role elements defined for this EJB application, or the reserved role-name "`*`" that indicates all roles in the EJB application. If both "`*`" and role names are entered in this sub-element, the container interprets this as all roles. If no roles are defined, then no user is allowed access to the portion of the Web application described by the containing security constraint. The container matches role names in a case-sensitive manner.
<transport-guarantee> | Type: `transport-guarantee` Default: n/a This sub-element specifies constraints on the access to data transmitted between the client and server. This sub-element can have one of the following values: `NONE`—the application does not require any transport guarantees. `INTEGRAL`—the application requires that the data sent between the client and server must be sent in such a way that it cannot be changed in transit. `CONFIDENTIAL`—the application requires that the data be transmitted in a fashion that prevents other entities from observing the contents of the transmission. In most cases, the presence of the `INTEGRAL` or `CONFIDENTIAL` flag will indicate that SSL must be used.

#### <ejb-transport-login-config> Element

The `<ejb-transport-login-config>` element is used to configure the transport-level authentication method and the realm name that should be used for this EJB application. The URL of the EJB application exposed as a Web service is indicated by the `<endpoint-address-uri>` element in the port component. Table 18-6 describes the sub-elements of `<ejb-transport-login-config>`.

Table 18-6 <ejb-transport-login-config> Sub-elements

Sub-element | Description
--- | ---
<auth-method> | Type: `auth-method` Default: n/a This sub-element is used to configure the authentication mechanism for an EJB application. As a prerequisite to gaining access to any Web resources which are protected by an authorization constraint, a user must have authenticated using the configured mechanism. Legal values for this sub-element are `BASIC`, `DIGEST`, `CLIENT-CERT`, or a vendor-specific single sign-on authentication scheme.
<realm-name> | Type: `string` Default: n/a This sub-element specifies the realm name to use in HTTP Basic authorization for an EJB exposed as Web service.

### oracle-webservices.xml File Listing

Example 18-3 provides a listing of a sample `oracle-webservices.xml` deployment descriptor. Note that this sample file also includes the Web services management elements. These elements are described in the sections indicated in the file.

Example 18-3 Sample oracle-webservices.xml File

    <?xml version="1.0" encoding="UTF-8"?>
    <oracle-webservices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/oracle-webservices-10_0.xsd"
       deployment-version="String" deployment-time="String" schema-major-version="10"
       schema-minor-version="0">
       <web-site host="String" port="String"/>
       <context-root>String</context-root>
       <webservice-description name="String">
          <expose-wsdl>true</expose-wsdl>
          <expose-testpage>true</expose-testpage>
          <resolve-relative-imports>false</resolve-relative-imports>
          <download-external-imports>false</download-external-imports>
          <port-component name="String">
             <endpoint-address-uri>String</endpoint-address-uri>
             <ejb-transport-security-constraint>
                <wsdl-url/>
                <soap-port/>
                <role-name>Manager</role-name>
                <role-name>Administrator</role-name>
                <transport-guarantee>NONE</transport-guarantee>
             </ejb-transport-security-constraint>

<!-- For a listing and description of elements that define transport-level security constraints for EJBs, see "<ejb-transport-security-constraint> Element". -->

             <implementor type="database">
                <param name="String">String</param>
             </implementor>
             <runtime enabled="String">
                <owsm/>

<!-- For a description of the element for the Oracle Web Services Manager (<owsm>) see the Oracle Web Services Manager User and Administrator Guide -->

                <security>

<!-- For a description and listing of security elements, see the Oracle Application Server Web Services Security Guide. -->

                </security>
                <reliability>
                   <repository jndiLocation="..." name="..." type="..."/>

<!-- For a description and listing of port-level reliability elements, see "Port-Level Reliability Elements on the Server" in the Oracle Application Server Advanced Web Services Developer's Guide. -->

                </reliability>
                <logging/>
             </runtime>
             <operations>
                <operation name="String" input="String">
                   <runtime>
                      <security>

<!-- For a description and listing of security elements, see the Oracle Application Server Web Services Security Guide. -->

                      </security>
                      <reliability>
                         <duplication-elimination-required/>
                         <guaranteed-delivery-required/>

<!-- For a listing and description of operation-level reliability elements, see "Operation Level Reliability Elements on the Server" in the Oracle Application Server Advanced Web Services Developer's Guide. -->

                      </reliability>
                      <auditing request="false" response="false" fault="false"/>

<!-- For a listing and description of operation-level auditing elements, see "Server-Side Auditing Configuration Elements" in the Oracle Application Server Advanced Web Services Developer's Guide. -->

                      <logging>

<!-- For a listing and description of operation-level logging elements, see "Operation Level Logging Elements on the Server" in the Oracle Application Server Advanced Web Services Developer's Guide. -->

                      </logging>
                   </runtime>
                </operation>
             </operations>
          </port-component>
       </webservice-description>
       <ejb-transport-login-config>
          <auth-method>BASIC</auth-method>
          <realm-name>sec-ejb</realm-name>
       </ejb-transport-login-config>

<!-- For a listing and description of elements that define transport-level security for EJBs, see "<ejb-transport-login-config> Element". -->

    </oracle-webservices>

## Limitations

See "Packaging and Deploying Web Services".

## Additional Information

For more information on:

- assembling Web services from a WSDL, see Chapter 5, "Assembling a Web Service from a WSDL".

- assembling stateful Web services, see Chapter 6, "Assembling a Web Service with Java Classes".

- assembling Web services from EJBs, see Chapter 7, "Assembling a Web Service with EJBs".

- assembling Web services from a JMS queue or topic, see Chapter 8, "Assembling Web Services with JMS Destinations".

- assembling Web services from database resources, see Chapter 9, "Developing Database Web Services".

- assembling Web services with J2SE 5.0 Annotations, see Chapter 10, "Assembling Web Services with Annotations".

- building J2EE clients, see Chapter 13, "Assembling a J2EE Web Service Client".

- building J2SE clients, see Chapter 14, "Assembling a J2SE Web Service Client".

- using the WebServicesAssembler tool to assemble Web services, see Chapter 17, "Using WebServicesAssembler".

- using the JAX-RPC mapping file and its contents, see "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide.

- the contents of `wsmgmt.xml` management policy file, see "Understanding the Web Services Management Schema" in the Oracle Application Server Advanced Web Services Developer's Guide.

- working with DIME attachments, see "Working with Attachments" in the Oracle Application Server Advanced Web Services Developer's Guide.

- adding transport-level security to Web services based on EJBs, see "Adding Transport-level Security to a Web Service" and "Accessing Web Services Secured on the Transport Level" in the Oracle Application Server Web Services Security Guide.

- the Oracle Web Services Manager tool, see the Oracle Web Services Manager User and Administrator Guide.

- using quality of service features in Web service clients, see "Managing Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.

- adding security to a Web service, see the Oracle Application Server Web Services Security Guide.

- adding reliability to a Web service, see "Ensuring Web Service Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide.

- adding an auditing and logging configuration to a Web service, see "Auditing and Logging Messages" in the Oracle Application Server Advanced Web Services Developer's Guide.