C oracle-webservices.xml Deployment Descriptor Schema

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. The values of some elements in the file can be changed by WebServicesAssembler command line arguments and Ant tasks.

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.

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.

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 schema is defined by the oracle-webservices-10_0.xsd file and can be found in the oc4j-schemas.jar file.

OC4J_HOME\j2ee\home\lib\oc4j-schemas.jar

Here, OC4J_HOME represents the directory where you installed Oracle Containers for J2EE (OC4J).

Hierarchy of XML Elements in oracle-webservices.xml

Here is an overview of the element hierarchy for the oracle-webservices.xml file.

<oracle-webservices>
   <web-site>
   <context-root>
   <webservice-description>
      <expose-wsdl>
      <expose-testpage>
      <resolve-relative-imports>
      <download-external-imports>
      <port-component>
         <endpoint-address-uri>
         <ejb-transport-security-constraint>
            <wsdl-url>
            <soap-port>
            <role-name>
            <transport-guarantee>
<!-- For a description of transport-level security constraints for EJBs, see  "Securing EJB-Based Web Services at the Transport Level". -->
         <implementor>
            <param>
         <runtime>
            <owsm> 
<!-- For a description of the Oracle Web Services Manager (<owsm>) element, see the  Oracle Web Services Manager Administrator's Guide -->
            <security>
<!-- For a description and listing of security elements, see the  Oracle Application Server Web Services Security Guide. -->
            <reliability>
               <repository>
 <!-- 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. -->
            <logging>
         <operations>
            <operation>
               <runtime>
                  <security>
<!-- For a description and listing of security elements, see the  Oracle Application Server Web Services Security Guide. -->
                   <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. -->
                  <auditing> 
<!-- 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.  -->
   <provider-description>
      <provider-description-name>
      <wsdl-file>
      <wsdl-service-name>
      <property>
      <provider-port>
         <provider-name>
         <wsdl-port>
         <expose-testpage>
         <expose-wsdl>
         <implementation-class>
         <servlet-link>
         <max-request-size>
         <property>
         <policy>
            <runtime>
            <operations>
               <operation>
<!-- Here you can enter a management configuration for a particular operation -->
   <ejb-transport-login-config>
      <auth-method>
      <realm-name>
<!-- For a listing and description of elements that define transport-level  security for EJBs, see  "Securing EJB-Based Web Services at the Transport Level". -->

Elements and Attributes of oracle-webservices.xml

This section is an alphabetical dictionary of elements in the oracle-webservices.xml file. See the preceding section, "Hierarchy of XML Elements in oracle-webservices.xml", if you are interested in the hierarchy. See "oracle-webservices.xml File Listing" if you are interested in seeing a sample file.

<auth-method>

Parent element: <ejb-transport-login-config>

Child element: None

Required? Optional

This subelement 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 subelement are BASIC, DIGEST, CLIENT-CERT, or a vendor-specific single sign-on authentication scheme. See "Securing EJB-Based Web Services at the Transport Level".

<context-root>

Parent element: <oracle-webservices>

Child element: None

Required? Only for version 2.1 EJB Web services

The value of this element is type string. Default: the EJB archive file name without the.jar extension.

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

<download-external-imports>

Parent element: <webservice-description>

Child element: None

Required? Optional

This boolean element specifies whether the relative imports should be downloaded and resolved to absolute URLs. Default is false.

Note:

If download-external-imports is set to true, then resolve-relative-imports is automatically set to true.

<ejb-transport-login-config>

Parent element: <oracle-webservices>

Child elements: <auth-method>, <realm-name>

Required? Optional

This 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. For more information, see "Securing EJB-Based Web Services at the Transport Level".

<ejb-transport-security-constraint>

Parent element: <port-component>

Child elements: <role-name>, <soap-port>, <transport-guarantee>, <wsdl-url>

Required? Optional

Defines transport-level security for a Web service based on EJBs. See "Securing EJB-Based Web Services at the Transport Level" for more information on how to use this element.

<endpoint-address-uri>

Parent element: <port-component>

Child element: None

Required? Only for Web services based on version 2.1 EJBs

This subelement, 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>" and "<ejb-transport-login-config>". See also, "Securing EJB-Based Web Services at the Transport Level".

For a Web module, (Web services derived from Java classes), this information is already present in the web.xml file and is not required.

<expose-testpage>

Parent element: <webservice-description>

Child element: None

Required? Optional

This boolean element specifies whether the test-page should be exposed. Default is true.

Parent element: <provider-port>

Child elements: None

Required? Optional

This boolean element specifies whether the test-page should be exposed. Default is true.

<expose-wsdl>

Parent element: <webservice-description>

Child element: None

Required? Optional

This boolean element specifies whether the WSDL should be exposed. Default is true.

Parent element: <provider-port>

Child elements: None

Required? Optional

This boolean element specifies whether the WSDL should be exposed. Default is true.

<implementation-class>

Parent element: <provider-port>

Child elements: None

Required? Required

Specifies the name of the class implementing the oracle.webservices.provider.Provider interface.

<implementor>

Parent element: <port-component>

Child element: <param>

Required? Optional

This subelement captures information that is generated at deployment time about OC4J's proprietary Web services. This subelement has a param subelement.

Table C-1 <implementor> Attributes

Name	Description
type	Value: implementorTypeAttr Default: n/a (Required) For example, database.

<jms-address>

Parent element: <port-component>

Child element: None

Required? Optional

The address element used for providing JMS destination information. This is used when JMS transport is specified to send SOAP messages over JMS.

Table C-2 <jms-address> Attributes

Name Description

Name	Description
jndiConnectionFactoryName	Value: string Default: n/a (Required) The JNDI name of the connection factory that will be used. If you are generating the Web service bottom up, then this attribute is set by the `sendConnectionFactoryLocation` argument.
jndiDestinationName	Value: string Default: n/a (Required) The JNDI name of the JMS queue that messages will be sent to. If you are generating the Web service bottom up, then this attribute will be set by the `sendQueueLocation` argument.

jndiConnectionFactoryName

Value: string

Default: n/a (Required)

The JNDI name of the connection factory that will be used. If you are generating the Web service bottom up, then this attribute is set by the sendConnectionFactoryLocation argument.

jndiDestinationName

Value: string

Default: n/a (Required)

The JNDI name of the JMS queue that messages will be sent to. If you are generating the Web service bottom up, then this attribute will be set by the sendQueueLocation argument.

<max-request-size>

Parent element: <port-component>

Child element: None

Required? Optional

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

The value of the element is a long integer. 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.

Parent element: <provider-port>

Child elements: None

Required? Optional

When a positive value is specified, the service will limit the size of requests to that value (in bytes). Any request that exceeds the maximum length will generate an error. Default is -1, which indicates no limit.

<operation>

Parent element: <operations>

Child elements: <runtime>

Required? Optional

Specifies a quality of service configuration for a particular operation provided by the referenced Web service. The configuration appears within this element's <runtime> subelement.

Table C-3 <operation> Attributes

Name	Description
input	Value: string Default: n/a Contains the input name of the operation from the WSDL.
name	Value: string Default: n/a (Required) associates the contained quality of service configuration to a specific operation. The value of the attribute must match the operation name from the WSDL.
output	Value: string Default: n/a Contains the output name of the operation from the WSDL.

Name

Description

input

Value: string

Default: n/a

Contains the input name of the operation from the WSDL.

name

Value: string

Default: n/a (Required)

associates the contained quality of service configuration to a specific operation. The value of the attribute must match the operation name from the WSDL.

output

Value: string

Default: n/a

Contains the output name of the operation from the WSDL.

<operations>

Parent element: <policy>

Child elements: <operation>

Required? Optional

Contains a sequence of elements, one for each operation. The <operation> subelement describes the management policies applied to an individual operation.

<oracle-webservices>

Parent element: n/a (root)

Child elements: <context-root>, <ejb-transport-login-config>, <web-site>, <webservice-description>

Required? Required

The <oracle-webservices> element captures information local to the Oracle container for Web services.

Table C-4 <oracle-webservices> Attributes

Name	Description
noNamespaceSchemaLocation	Value: URI Default: n/a This attribute is the "standard" way of telling the parser which schema the XML document should adhere to.

Name

Description

noNamespaceSchemaLocation

Value: URI

Default: n/a

This attribute is the "standard" way of telling the parser which schema the XML document should adhere to.

<param>

Parent element: <port-component>

Child element: None

Required? Optional

Specifies the JNDI location of the data source at runtime.

<policy>

Parent element: <provider-port>

Child elements: None

Required? Optional

Defines the Web service management policies for the Provider.

<port-component>

Parent element: <webservice-description>

Child elements: <ejb-transport-security-constraint>, <endpoint-address-uri>, <implementor>, <jms-address>, <max-request-size>, <rest-support>, <runtime>, <use-dime-encoding>

Required? Optional

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

Table C-5 <port-component> Attributes

Name	Description
name	Value: string Default: n/a (Required) Maps to the `name` element in `webservices.xml`.

<property>

Parent element: <provider-description>

Child elements: None

Required? Optional

Specifies globally-defined properties; that is, properties that are available to all of the defined Provider ports. This element has a required string name attribute.

Parent element: <provider-port>

Child elements: None

Required? Optional

A locally defined property. If a property with a particular name is defined both locally and globally, then the property defined locally overrides the one defined globally

<provider-description>

Parent element: <oracle-webservices>

Child elements: <property>, <provider-description-name>, <provider-port>, <wsdl-file>, <wsdl-service-name>

Required? Optional

This element serves to make the Web service Provider-aware, and identifies a collection of Provider ports. For more information on Web service Providers, see "Using Web Service Providers" in the Oracle Application Server Advanced Web Services Developer's Guide

<provider-description-name>

Parent element: <provider-description>

Child elements: None

Required? Required

This string element specifies a name for the Provider description.

<provider-name>

Parent element: <provider-port>

Child elements: None

Required? Required

The name of the Provider. The string <provider-name> within the <provider-port> must be unique within the deployment descriptor.

<provider-port>

Parent element: <provider-description>

Child elements: <expose-testpage>, <expose-wsdl>, <implementation-class>, <max-request-size>, <policy>, <property>, <provider-name>, <servlet-link>, <wsdl-port>

Required? Required

Associates a WSDL port with a Web service interface and implementation. It defines the name of the port as a component. It also associates the port with a servlet endpoint. If a wsdl-file is not present, the provider-port defines a pass-through gateway.

<realm-name>

Parent element: <ejb-transport-login-config>

Child element: None

Required? Optional

This subelement specifies the realm name to use in HTTP Basic authorization for an EJB exposed as Web services. For more information, see "Securing EJB-Based Web Services at the Transport Level".

<resolve-relative-imports>

Parent element: <webservice-description>

Child element: None

Required? Optional

This boolean element specifies whether you want to resolve from relative imports to absolute URLs. Default is false.

<rest-support>

Parent element: <port-component>

Child elements: None

Required? Optional

The boolean rest element indicates whether this port supports REST-style GET and POST requests and responses. Default is false.

<role-name>

Parent element: <ejb-transport-security-constraint>

Child element: None

Required? Optional

This string element identifies the name of a security role. The name must conform to the lexical rules for a token. A default value is not defined.

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

See "Securing EJB-Based Web Services at the Transport Level" for more information on how to use this element.

<runtime>

Parent element: <port-component>

Child element: None

Required? Optional

Denotes the start of the Web services management information that will be read at runtime. For more information, see "Understanding the Web Services Management Schema" in the Oracle Application Server Advanced Web Services Developer's Guide.

Parent element: <policy>

Child elements: None

Required? Optional

Contains server-side quality of service runtime information (security, reliability, auditing, and logging) applicable to all the operations provided by the referenced Web service. Each child element contains configuration for a specific feature.

<servlet-link>

Parent element: <provider-port>

Child elements: None

Required? Required

Associates a provider-port value with a servlet endpoint defined in the /WEB-INF/web.xml file.

<soap-port>

Parent element: <ejb-transport-security-constraint>

Child element: None

Required? Optional

If present, this element specifies that the security constraints must apply only to the SOAP port. A default is not defined. See "Securing EJB-Based Web Services at the Transport Level" for more information on how to use this element.

<transport-guarantee>

Parent element: <ejb-transport-security-constraint>

Child element: None

Required? Optional

This element specifies constraints on the access to data transmitted between the client and server. This subelement 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.

See "Securing EJB-Based Web Services at the Transport Level" for more information on how to use this element.

<use-dime-encoding>

Parent element: <port-component>

Child element: None

Required? Optional

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.

<web-site>

Parent element: <oracle-webservices>

Child elements: None

Required: Optional

Default: the location where the service endpoint interface is installed

This optional 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 subelement 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.

If this element is not used, the host and port values of the HTTP request used to get the WSDL will be substituted.

Table C-6 <web-site> Attributes

Name	Description
host	Value: string Default: n/a (required) The name for the host which will be substituted inside the updated WSDL port location.
port	Value: string Default: n/a (required) The name for the port which will be substituted inside the updated WSDL port location

Name

Description

host

Value: string

Default: n/a (required)

The name for the host which will be substituted inside the updated WSDL port location.

port

Value: string

Default: n/a (required)

The name for the port which will be substituted inside the updated WSDL port location

<webservice-description>

Parent element: <oracle-webservices>

Child elements: <download-external-imports>, <expose-testpage>, <expose-wsdl>, <port-component>, <resolve-relative-imports>, <wsdl-file>, <wsdl-publish-location>

Required? Optional

This element extends the <webservice-description> element in the standard deployment descriptor, webservices.xml.

Table C-7 <webservice-description> Attributes

Name	Description
name	Value: string Default: n/a (required) Maps to the `name` element in `webservices.xml`.

<wsdl-file>

Parent element: <provider-description>

Child elements: None

Required? Optional

This string element specifies the location of an associated WSDL for the Provider.

Parent element: <webservice-description>

Child element: None

Required? Optional

This element of type wsdl-file is generated at deployment time and cannot be specified by an end-user. It specifies the location of the final updated WSDL.

Table C-8 <wsdl-file> Attributes

Name	Description
final-location	Value: anyUri Default: n/a (Required) Specifies the location of the final updated WSDL.

Name

Description

final-location

Value: anyUri

Default: n/a (Required)

Specifies the location of the final updated WSDL.

<wsdl-port>

Parent element: <provider-port>

Child elements: None

Required? Optional

Associates the Provider with a particular port of the WSDL defined by the wsdl-file element. This element is not required if no WSDL file is defined.

<wsdl-publish-location>

Parent element: <webservice-description>

Child element: None

Required? Optional

This element is used to specify the location where the final WSDL and its dependent files (imports) can be placed. It is of type anyUri and the value should be of the form file:/location/. A default is not defined.

<wsdl-service-name>

Parent element: <provider-description>

Child elements: None

Required? Optional

Associates the WSDL's service name with the name of a Provider. This element should be provided if a WSDL has more than one service. This element is not required if the WSDL has only one service

<wsdl-url>

Parent element: <ejb-transport-security-constraint>

Child elements: None

Required? Optional

If present, this element specifies that the security constraints must apply only to the WSDL URL. A default value is not defined. See "Securing EJB-Based Web Services at the Transport Level" for more information on how to use this element.

Securing EJB-Based Web Services at the Transport Level

The oracle-webservices.xml deployment descriptor provides two elements, <ejb-transport-security-constraint> and <ejb-transport-login-config> that allow you to define transport-level security for Web services that are based on EJBs.

oracle-webservices.xml File Listing

Example C-1 provides a listing of a template for a oracle-webservices.xml deployment descriptor. Note that this template file also includes the Web services management elements. These elements are described in the sections indicated in the file.

Example C-1 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>

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

<security>

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

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

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

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

<logging>

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

</oracle-webservices>