D service-ref-mapping Schema

This appendix describes the service-ref-mapping schema. This schema is defined by the service-ref-mapping-10_0.xsd file and can be found in the oc4j-schemas.jar file.

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

This schema defines elements that define OC4J-specific runtime and deployment-time generated settings for a Web service reference. You can use the elements defined by this schema to configure the following information:

• configure the client to consume stateful Web Services

• configure the client to make JMS transport calls

• configure security, logging, and auditing quality of service (QOS) features for the corresponding Web service.

The service-ref-mapping-10_0.xsd is imported into the orion-web, orion-ejb-jar, and orion-application-client XSDs.

The <service-ref-mapping> elements can appear as subelements of the <orion-web-app> element in the orion-web.xml, orion-ejb-jar.xml, or orion-application-client.xml proprietary deployment descriptor files. Currently, there is no tool support, such as Oracle JDeveloper wizards, for providing values to service-ref-mapping-10_0.xsd on adding them to the deployment descriptors. You must refer to the schema and enter the values for <service-ref-mapping> elements into the appropriate XML file by hand.

Hierarchy of service-ref-mapping Schema

Here is an overview of the element hierarchy for the service-ref-mapping schema.

<service-ref-mapping>
  <service-impl-class>
  <wsdl-file>
  <wsdl-location>
  <service-qname>
  <stub-property>
   <name>
   <value>
  <call-property>
   <name>
   <value>
  <port-info>
    <wsdl-port>
    <service-endpoint-interface>
    <stub-property>
      <name>
      <value>
    <call-property>
      <name>
      <value>
    <runtime>
      ...
Under <runtime>, you can add client-side quality of service (Web Service  Management) features. This can include a reliabilty and security configuration. 
      ...
    <operations>
      <operation>
         <runtime>
           ...
Under <runtime>, you can add client-side quality of service (Web Service Management) features. This can include an auditing, reliabilty, and security configuration.
           ... 

Elements and Attributes of service-ref-mapping Schema

This section is an alphabetical dictionary of elements of the service-ref-mapping schema. See the preceding section, "Hierarchy of service-ref-mapping Schema", if you are interested in the hierarchy.

The element descriptions in the section apply to service-ref-mapping elements that are inserted into an orion-web.xml, orion-ejb-jar.xml, or orion-application-client.xml proprietary deployment descriptor file.

<call-property>

Parent element:  <service-ref-mapping> and <port-info>

Child elements:  <name>, <value>

Required? Optional

The <call-property> element can be a subelement of both <service -ref-mapping> and <port-info>. When <call-property> is used as a subelement of <service-ref-mapping>, it defines the call property values applicable to all ports. This is a convenient way to specify a property without specifying the port name.

When <call-property> is used as a subelement of <port-info>, it defines the call property values applicable to the specific port defined by the <port-info>.

If call property values are specified for a particular port inside the <port-info> tag, then they override the <call-property> element values set under <service-ref-mapping>.

<name>

Parent element:  <call-property> and <stub-property>

Child elements:  None

Required? Required

The <name> element can appear as a subelement of either <call-property> or <stub-property>. It defines the name of any property supported by the JAX-RPC Call or Stub implementation. See the output of the Javadoc tool for the valid properties for javax.xml.rpc.Call and javax.xml.rpc.Stub.

The <value> element assigns a value to the property. For more information on this element, see "<value>".

<operation>

Parent element:  <operations>

Child elements:  <runtime>

Required? Optional

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

Table D-1 <operation> Attributes

Name	Description
inputName	Value: string Default: n/a This optional attribute contains the input name of the operation from the WSDL. It is required only if the name attribute cannot be used to uniquely identify the operation.
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.
outputName	Value: string Default: n/a This optional attribute contains the output name of the operation from the WSDL. It is required only if the name and input attributes cannot be used to uniquely identify the operation.

<operations>

Parent element:  <port-info>

Child elements:  <operation>

Required? Optional

Contains a sequence of elements, one for each operation. The <operation> subelement indicates an individual operation. Each of these subelements contain client-side quality of service configuration for a single operation provided by the referenced Web service.

<port-info>

Parent element:  <service-ref-mapping>

Child elements:  <call-property>, <operations>, <runtime>, <service-endpoint-interface>, <stub-property>, <wsdl-port>

Required? Optional

Defines a port within a service-reference. This element provides all of the information for a port within a service reference. You can specify either <service-endpoint-interface> or <wsdl-port> to indicate the port that the container will use for container-managed port selection. If you specify both, then the container will use the <wsdl-port> value. If you do not specify <wsdl-port> or <service-endpoint-interface>, then the <port-info> property values will apply to all available ports.

This element also contains subelements that let you specify quality of service features that are available for the port and its operations.

<runtime>

Parent element:  <port-info> and <operation>

Child elements:  None

Required? Optional

The <runtime> element can be used as a subelement of the <port-info> and <operation> elements. When the <runtime> element is used as a subelement to <port-info>, it contains client-side quality of service runtime information (security and/or reliability) applicable to all the operations provided by the referenced Web service. Each child element contains configuration for a specific feature.

When the <runtime> element is used as a subelement to <operation>, it contains client-side quality of service configuration for individual operations within the port. Each child element contains configuration for one of the quality of services features (security, reliability, and/or auditing).

<service-endpoint-interface>

Parent element:  <port-info>

Child elements:  None

Required? Optional

Specifies the fully-qualified path to the service endpoint interface of a WSDL port. The container uses this port for container-managed port selection. The value of this element is a string.

<service-impl-class>

Parent element:  <service-ref-mapping>

Child elements:  None

Required? Optional

Defines a deployment-time generated name of a Service implementation.

<service-qname>

Parent element:  <service-ref-mapping>

Child elements:  None

Required? Optional

Derived at deployment-time, this element contains the QName of the Web service.

<service-ref-mapping>

Parent element:  root element

Child elements:  <call-property>, <port-info>, <service-impl-class>, <stub-property>, <service-qname>, <wsdl-file>, <wsdl-location>

Required? Optional

The <service-ref-mapping> element is used in conjunction with the <service-ref> element that appears in the standard deployment descriptors web.xml, ejb-jar.xml, and application-client.xml. The <service-ref> element contains the information that lets you employ an EJB, JSP, or servlet as a Web service client that can invoke a remote Web service.

Note that whenever a <service-ref> element can appear in a web.xml, ejb-jar.xml, or application-client.xml file, a corresponding <service-ref-mapping> element can appear in an orion-web.xml, orion-ejb-jar.xml, or orion-application-client.xml file.

In its simplest case, the <service-ref-mapping> element contains only deployment information. Do not add run-time or quality of service elements if you do not want your client to be managed. A managed client is more expensive in terms of performance.

<stub-property>

Parent element:  <service-ref-mapping> and <port-info>

Child elements:  <name>, <value>

Required? Optional

The <stub-property> element can be a subelement of both <service -ref-mapping> and <port-info>. When <stub-property> is used as a subelement of <service-ref-mapping>, it defines the stub property values applicable to all ports. This is a convenient way to specify a property without specifying the port name.

When <stub-property> is used as a subelement of <port-info>, it defines the stub property values applicable to the specific port defined by the <port-info>.

If stub property values are specified for a particular port inside the <port-info> tag, then they override the <stub-property> element values set under <service-ref-mapping>.

<value>

Parent element:  <call-property> and <stub-property>

Child elements:  None

Required? Required

The <value> element can appear as a subelement of either <call-property> or <stub-property>. It defines a JAX-RPC property value that should be set on a Call object or a Stub object before it is returned to the Web service client.

The <name> element assigns the name of the JAX-RPC property. For more information on this element, see "<name>".

<wsdl-file>

Parent element:  <service-ref-mapping>

Child elements:  None

Required? Optional

Defines a deployment-time generated name for the WSDL file.

Table D-2 <wsdl-file> Attributes

Name	Description
final-location	Value: anyURI Default: n/a (Required) Points to the copy of the WSDL document associated with the service-ref in the standard deployment descriptor.

<wsdl-location>

Parent element:  <service-ref-mapping>

Child elements:  None

Required? Optional

Contains a valid URL pointing to a WSDL document. If a URL is specified, then the WSDL document at this URL will be used during deployment instead of the WSDL document associated with the service-ref in the standard deployment descriptor. Sample values for <wsdl-location> include: http://hostname:port/myservice/myport?WSDL and file:/home/user1/myfinalwsdl.wsdl.

Table D-3 <wsdl-location> Attributes

Name	Description
wsdl-override-last-modified	Value: string Default: n/a This optional string value is generated at deployment time and lists the time when the WSDL file was last modified.

<wsdl-port>

Parent element:  <port-info>

Child elements:  None

Required? Optional

Specifies the name of a port in the WSDL that the container will use for container-managed port selection. In container-managed port selection, the container manages calls to the instance directly, and the client requests a generic port that might be used to access multiple different instances.

Table D-4 <wsdl-port> Attributes

Name	Description
localpart	Value: string Default: n/a (Required) The local part of a WSDL name. For example, authenticateHeader.
namespaceURI	Value: anyURI Default: n/a (Required) The namespace URI of a WSDL. For example, http://oracle.j2ee.ws/Header

service-ref-mapping File Listing

For a sample service-ref-mapping fragment that can be used in a proprietary deployment descriptor, see "How to Add OC4J-Specific Platform Information for Deployment and Runtime".