E OracleAS Web Services Tracing Schema

This appendix describes the Oracle Application Server Web Services tracing (logging) configuration elements defined by the tracing schema oracle-webservices-logging-10_0.xsd. This file can be found in the oc4j-schemas.jar file.

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

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

Tracing is typically used as part of a larger Web services management configuration. To enable tracing, you must configure it into the Web service on the server side. The configuration is part of an XML configuration file that is passed to the Web service when it is assembled.

For the server, the configuration is stored in the oracle-webservices.xml deployment descriptor file. This file is based on the oracle-webservices-10_0.xsd schema.

Note:

Tracing cannot be configured for a Web service client.

Hierarchy of a Tracing Configuration

Tracing features can be configured at both the port and the operation level in the oracle-webservices.xml server-side deployment descriptor. The port-level configuration contains information that is referenced by the operation level. Unlike security or reliability, an operation-level tracing configuration does not override a port-level configuration.

A tracing configuration is delimited by the <logging> element. At the port level in the oracle-webservices.xml file, this tracing configuration appears in the <runtime> clause beneath the <port-component> port description. At the operation level, the tracing configuration appears in the <runtime> clause beneath an individual <operation> description. Each operation can have its own tracing configuration.

The following fragment illustrates where a tracing configuration can appear in the hierarchy of an oracle-webservices.xml file.

<oracle-webservices>
...
 <port-component>
   ...
  <runtime>
   <logging>
      <namespaces> 
        <namespace>
   ...
     <operations>
       <operation>
        <runtime>
         ...
         <logging>
           <request>  
             <attributes>    
              <attribute>
           <response>
             <attributes>
               <attribute>
           <fault>
             <attributes>
               <attribute>

Elements and Attributes for the Tracing Schema

This section is an alphabetical dictionary of elements in the tracing schema, oracle-webservices-logging-10_0.xsd. See the preceding section, "Hierarchy of a Tracing Configuration", if you are interested in the hierarchy.

<attribute>

Parent element:  <attributes>

Child element:  None

Required? Optional

Port or Operation? Operation

This element enables you to specify one or more attributes you want to log for each message type. These attributes are indicated by its name and xpath. If tracing for a message type is enabled, but no attributes are configured, then no tracing will occur. Similarly, if the xpath query returns no results, then no tracing will occur.

Table E-1 <attribute> Attributes

Name	Description
name	Value: string Default: n/a (Required) The name of the attribute.
xpath	Value: string Default: n/a (Required) The xpath query for attributes.

<attributes>

Parent element:  <fault>, <request>, <response>

Child element:  <attribute>

Required? Optional

Port or Operation? Operation

This element can occur no more than once in a configuration for a <request>, <response>, or <fault> element. It delimits a sequence of <attribute> elements.

<fault>

Parent element:  <logging>

Child element:  <attributes>

Required? Optional

Port or Operation? Operation

The presence of this element indicates that the tracing of request messages can be enabled or disabled for this operation. This element has the single attribute enabled.

If enabled="true", then use the <attribute> element to specify name-value pairs of message attributes. Each attribute is specified by an attribute name and xpath value. The default for the enabled attribute is true.

<logging>

Parent element:  Root element for a logging configuration

Child elements: 

Port level: <namespaces>

Operation level: <fault>, <request>, <response>

Required? Optional

Port or Operation? Both

Delimits a port-level or operation-level tracing configuration.

<namespace>

Parent element:  <namespaces>

Child element:  None

Required? Optional

Port or Operation? Port

Specifies a name-value pair of namespace prefixes and namespace URIs. The namespace URIs are implicitly referenced by the use of the prefixes in xpath expressions defined for tracing at the operation level.

Table E-2 <namespace> Attributes

Name	Description
prefix	Value: string Default: n/a (Required) Used by the xpath expression defined at the operation level.
uri	Value: anyURI Default: n/a (Required) Used by the xpath expression defined at the operation level.

<namespaces>

Parent element:  <logging>

Child element:  <namespace>

Required? Optional

Port or Operation? Port

This element can occur no more than once in a port-level configuration. It delimits a sequence of <namespace> elements.

<request>

Parent element:  <logging>

Child element:  <attributes>

Required? Optional

Port or Operation? Operation

The presence of this element indicates that the tracing of request messages can be enabled or disabled for this operation. This element has the single attribute enabled.

If enabled="true", then use the <attribute> element to specify name-value pairs of message attributes. Each attribute is specified by an attribute name and xpath value. The default for the enabled attribute is true.

<response>

Parent element:  <logging>

Child element:  <attributes>

Required? Optional

Port or Operation? Operation

The presence of this element indicates that the tracing of request messages can be enabled or disabled for this operation. This element has the single attribute enabled.

If enabled="true", then use the <attribute> element to specify name-value pairs of message attributes. Each attribute is specified by an attribute name and xpath value. The default for the enabled attribute is true.

Tracing Configuration Listing

You can find sample tracing configurations for a Web service and client in Chapter 6, "Auditing and Tracing Messages".