Oracle Dynamic Services User's and Administrator's Guide
Release 9.0.1

Part Number A88783-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to next page

6
Service Development Guide

In this chapter, the process of service development is described as well as how you can test a service after you build one.

A service is a component within the Internet computing model that delivers a specialized value-added function. A service is bundled into a simple service package (see Figure 3-1) and structured as a local directory containing at least:

The service descriptor file also describes in its service body section how the four types of service adaptors are to be used to do any of the following:

A compound service package invokes one or more other services and has everything a simple service package has plus it typically includes a jar file containing all Java classes and property files needed by the compound service.

The MANIFEST file is expected to be found in the root directory of the simple or compound service package and with the name MANIFEST (uppercase, case-sensitive on Solaris systems; initial capitalization, non case-sensitive on Windows NT systems). The MANIFEST file is a text file where the first non-empty line should specify a URL link to the service descriptor XML file. If a link starts with a slash (/), it indicates the link is an absolute link with respect to the root directory of the current service package. The root directory is interpreted to be the root of the directory structure for the service package.

6.1 Quick Start

You can quickly start developing your own service by following the steps described in this section. These steps are necessary to build a simple HTTP service. Later, you can enhance your service after reading about some more advanced concepts in other sections of this chapter. The service that you will build is a simple HTTP service that gets stock quotes from Yahoo.com.

The tasks to complete this quick-start service development tutorial are as follows:

  1. Create a service package (see Section 6.1.1).
  2. Edit the service provider organization and contact XML files (see Section 6.1.2).
  3. Edit the service provider classification XML file (see Section 6.1.3).
  4. Create your XML schema file for the service request definition (see Section 6.1.4).
  5. Create your XML schema file for the service response definition (see Section 6.1.5).
  6. Edit the service descriptor file, including both the service header and the service body sections (see Section 6.1.6).
  7. Test the execution of your service (see Section 6.1.7).


    Note:

    The <ORACLE_HOME>/ds/etc/xsd directory on UNIX systems or the <ORACLE_HOME>\ds\etc\xsd directory on Windows NT systems contains the XML schema files for the service descriptor and supplied adaptors. Refer to the files in this directory for more information. 


6.1.1 Creating a Service Package

Perform the following steps to create your service package:

  1. Copy the entire demo/services/SampleService directory on UNIX systems or the demo\services\SampleService directory on Windows NT systems into a new directory using your name, for example, demo/services/myService on UNIX systems or demo\services\myService on Windows NT systems.

    This step creates a default service package. You can modify the name of the subdirectories to reflect the nature of the service you want to build. In this tutorial, you will make the following changes shown in Example 6-1.

For UNIX Systems:

Example 6-1 Create a Default Service Package


cp -r demo/services/SampleService demo/services/myService
cd demo/services/myService
mv SampleProvider www.yahoo.com

cd www.yahoo.com/dServices
mv SampleService portfolio
mv SampleOrg.xml YahooOrg.xml
mv SampleContact.xml YahooContact.xml

cd portfolio
mv SampleService.xml ypfl.xml
mv SampleServiceClassification.xml ypflClass.xml

For NT Systems:
    1. Copy the entire demo\services\SampleService directory into a new directory using your name, for example, demo\services\myService.
    2. Navigate to the demo\services\myService directory and rename SampleProvider to www.yahoo.com.
    3. Navigate to the www.yahoo.com\dServices directory and rename SampleService to portfolio, SampleOrg.xml to YahooOrg.xml, and SampleContact.xml to YahooContact.xml.
    4. Navigate to the portfolio subdirectory and rename SampleService.xml to ypfl.xml and SampleServiceClassification.xml to ypflClass.xml.
  1. Update the MANIFEST file in the demo/services/myServices directory on UNIX systems or the demo\services\myServices directory on Windows NT systems to contain the line shown in Example 6-2.

Example 6-2 Update the MANIFEST File

On UNIX systems:
/www.yahoo.com/dServices/portfolio/ypfl.xml

On Windows NT systems:
\www.yahoo.com\dServices\portfolio\ypfl.xml

Step 2 lets the service package point to the correct service descriptor file that you will edit soon. Notice that all paths used in this quick-start document are relative to the demo/services/myService directory on UNIX systems or the demo\services\myService directory on Windows NT systems.

6.1.2 Service Provider -- Organization and Contacts XML Files

Recall that the YahooOrg.xml file and the YahooContact.xml file described in Section 6.1.1, reside in the directory /www.yahoo.com/dServices on UNIX systems or \www.yahoo.com\dServices on Windows NT systems. These files contain service provider information about the organization and contacts for this particular service.

Example 6-3 Edit the YahooOrg.xml File

<?xml version="1.0"?>
<!-- Fully scope information for good practice -->
<dsOrg:ORGANIZATION 
  xmlns:dsOrg="http://www.oracle.com/ds/2000/SERVICE_DESCRIPTOR/ORGANIZATION">
  <dsOrg:NAME>Yahoo!</dsOrg:NAME>
  <dsOrg:COPYRIGHT>(c) Yahoo!, 2000</dsOrg:COPYRIGHT>
  <dsOrg:URL>http://www.yahoo.com</dsOrg:URL>
  <dsOrg:LOGOURL>http://us.yimg.com/i/fi/main4.gif</dsOrg:LOGOURL>
</dsOrg:ORGANIZATION>

Example 6-4 Edit the YahooContact.xml File

<?xml version="1.0"?>
<!-- Fully scope information for good practice -->
<dsCt:CONTACT 
  xmlns:dsCt="http://www.oracle.com/ds/2000/SERVICE_DESCRIPTOR/CONTACT">
  <dsCt:NAME>bar1</dsCt:NAME>
  <dsCt:EMAIL>bar1@yahoo.com</dsCt:EMAIL>
  <dsCt:PHONE>(000)000-0000</dsCt:PHONE>
  <dsCt:FAX>(000)000-0000</dsCt:FAX>
  <dsCt:PAGER>(000)000-0000</dsCt:PAGER>
  <dsCt:MOBILE>(000)000-0000</dsCt:MOBILE>
</dsCt:CONTACT>

6.1.3 Service Classification XML File

The ypflClass.xml file described in Section 6.1.1 resides in the directory /www.yahoo.com/dServices/portfolio/ on UNIX systems or \www.yahoo.com\dServices\portfolio\ on Windows NT systems. This file should contain classification information of your service.

Edit the ypflClass.xml file to appear as shown in Example 6-5.

Example 6-5 Edit the ypflClass.xml File

<?xml version="1.0"?>
<!-- Fully scope information for good practice -->
<dsCls:CLASSIFICATION 
  xmlns:dsCls="http://www.oracle.com/ds/2000/SERVICE_DESCRIPTOR/CLASSIFICATION">
   <dsCls:CATEGORY>cn=portfolio, cn=finance, cn=business</dsCls:CATEGORY>
   <dsCls:KEYWORDS>portfolio,stocks,finance</dsCls:KEYWORDS>
</dsCls:CLASSIFICATION>


Note:

The category section follows the Lightweight Directory Access Protocol (LDAP) Distinguished Name (DN) (backwards tree) convention. The category specified must exist in the registry before you can register the service. 


6.1.4 Service Interface Specification -- Request Definition

Before editing the service descriptor, you must understand how requests are defined.

Example 6-6 Examine a Typical HTML Form

<form method=get action="/q"><nobr>
  <input type=text size=25 name=SymbolList>
  <input type=submit value="Get Quotes">&nbsp;
  ...
</form>

The form takes one input called SymbolList and an HTTP GET request is made to http://quote.yahoo.com/q when you click Submit. An HTML page returns the stock quotes of the symbols that are specified in the input called SymbolList.

Example 6-7 Generate an XML Schema File for the Service Request

<?xml version ="1.0"?>
<!-- Input schema of the currency service -->
<schema xmlns = "http://www.w3.org/1999/XMLSchema"
        targetNamespace = "http://www.portfolio.org/Portfolio/Request"
        xmlns:pflReq = "http://www.portfolio.org/Portfolio/Request">

  <element name = "PortfolioReq">
    <complexType content = "elementOnly">
      <sequence>
          <!-- Use a more user-friendly name as a symbol and an augmented 
               string type called Ticker to restrict its format. Have a
               default as well because XML Schema allows for it. Also,
               restrict it so there are 1 or more symbols at least. -->
          <element 
            name = "Symbol" type="pflReq:Ticker" 
            default="ORCL" minOccurs="1" maxOccurs="*"/>
      </sequence>
    </complexType>
  </element>

  <simpleType name = "Ticker" base = "string">
    <pattern value="[^\s]+" />
  </simpleType>
</schema>

In the use of the service, an XML request must conform to this schema to be used correctly.

6.1.5 Service Interface Specification -- Response Definition

When the HTTP GET request is made, the HTML page shown contains the actual stock quote that you want.

Example 6-8 Examine the Code and Note the Stock Symbol ORCL

<tr align=right>
  <!-- "Symbol" -->
  <td nowrap align=left><a href="/q?s=ORCL&d=t">ORCL</a></td>
  <!-- "Time" -->
  <td nowrap align=center>12:14PM</td>
  <!-- "Price" -->
  <td nowrap><b>82 <sup>15</sup>/<sub>16</sub></b></td>
  <!-- "Change" -->
  <td nowrap>+1 <sup>3</sup>/<sub>4</sub></td>
  <td nowrap>+2.16%</td>
  <!-- "Volume" -->
  <td nowrap>6,218,900</td>
  <td nowrap align=center><small>

Example 6-9 Create an XML Schema File for the Service Response

<?xml version ="1.0"?>
<!-- Input schema of the currency service -->
<schema xmlns = "http://www.w3.org/1999/XMLSchema"
        targetNamespace = "http://www.portfolio.org/Portfolio/Response"
        xmlns:pflResp = "http://www.portfolio.org/Portfolio/Response">
  <!-- This is the input value in which the input should be specified. -->
  <element name = "PortfolioResp">
    <complexType content = "elementOnly">
      <element name = "Quote" minOccurs="1" maxOccurs="*">
        <complexType content = "elementOnly">
          <sequence>
            <element name = "Symbol" type="pflResp:Ticker" />
            <element name = "Time" type="string" />
            <element name = "Price" type="string" />
            <element name = "Change" type="string" />
            <element name = "Volume" type="string" />
          </sequence>
        </complexType>
      </element>
    </complexType>
  </element>

  <simpleType name = "Ticker" base = "string" >
    <pattern value="[^\s]+" />
  </simpleType>
</schema>

You have decided that the symbol, time, price, change of last trade, and the volume are all useful pieces of information that you can gather from the HTML page. Consequently, you model your response using the previous schema.

6.1.6 Editing the Service Descriptor

Next, the steps to modify the service descriptor ypfl.xml file in the directory /www.yahoo.com/dServices/portfolio/ on UNIX systems or \www.yahoo.com\dServices\portfolio\ on Windows NT systems are described. The beginning of the service descriptor, with namespaces sd for all service descriptor tags and xlink for all your document links that use XLink attributes, is shown in Example 6-10.

Example 6-10 Examine the Beginning of the Service Descriptor

<sd:SERVICE_DESCRIPTOR
  xmlns:sd="http://www.oracle.com/ds/2000/SERVICE_DESCRIPTOR"
  xmlns:xlink="http://www.w3.org/1999/xlink">

Note:

Oracle Corporation recommends that you fully qualify the elements in the service descriptor document using the sd prefix and referring to the following namespace:

http://www.oracle.com/ds/2000/SERVICE_DESCRIPTOR 


6.1.6.1 Service Header

Modify your service header as shown in Example 6-11, and read the comments that tell you what must be changed when you build the YahooPortfolio service.

Example 6-11 Modify the Service Header

<sd:SERVICE_HEADER>
<!-- In the NAMING section, the only thing you really need to modify is
     the ID field. It has to uniquely identify your service and must be a
     universal resource name (URN). But modify the rest as you see fit. -->
<sd:NAMING>
  <sd:ID>urn:com.yahoo:finance.portfolio03</sd:ID>
  <sd:NAME>Yahoo Portfolio service</sd:NAME>
  <sd:DESCRIPTION>Find current prices for stocks</sd:DESCRIPTION>
</sd:NAMING>

<sd:PACKAGE>
  <sd:VERSION>1.0</sd:VERSION>
  <sd:RELEASEDATE>05-MAY-2000</sd:RELEASEDATE>
  <sd:UPDATEURL>http://www.yahoo.com/dServices/pfl.zip</sd:UPDATEURL>
</sd:PACKAGE>
<sd:DEPLOYMENT>
  <!-- Point the classification file to the file that you edited previously in
       Section 6.1.3 and note that the path starts from the directory of the
       service package. -->
  <sd:CLASSIFICATION
    xlink:href="/www.yahoo.com/dServices/portfolio/ypflClass.xml"/>

  <!-- Also, change the caching parameters to set cache expiration in
       seconds, or to specify that the cache has session knowledge. -->
  <sd:CACHING>
    <!-- Expiration in seconds. -->
    <sd:MAX_AGE>60</sd:MAX_AGE>
    <!-- Will the cache be session-aware? -->
    <sd:SESSION_PRIVATE>true</sd:SESSION_PRIVATE>
    <!-- This Boolean field tells the engine to allow the expiration of
         the cache to be controlled by the underlying protocol. Specifying
         a value of true would make the engine ignore the MAX_AGE tag. -->
    <sd:USE_PROTOCOL>false</sd:USE_PROTOCOL>
  </sd:CACHING>

</sd:DEPLOYMENT>
<sd:PROVIDER>
  <!-- This is mandatory and should point to the organization file
       that you edited previously in Section 6.1.2. -->
  <sd:ORGANIZATION xlink:href="/www.yahoo.com/dServices/YahooOrg.xml"/>
      
  <!-- This is mandatory (at least one contact element in the contacts
       section), and should point to the contact file that you 
       edited previously in Section 6.1.2. -->
  <sd:CONTACTS>
    <sd:CONTACT xlink:href="/www.yahoo.com/dServices/YahooContact.xml"/>
  </sd:CONTACTS>
</sd:PROVIDER>
<sd:INTERFACE>
  <!-- Change this to your own service interface (made up of a request/
       response schema specification pair). We will not put Yahoo here
       because maybe other organizations can have the same kind of service,
       which can be used in a failover scenario. -->
  <sd:NAME>PortfolioService</sd:NAME>
  <!-- This is mandatory; point this to the XML schema file that you 
       created previously in Section 6.1.4. -->
  <sd:INPUT_SCHEMA 
    xlink:href="/www.yahoo.com/dServices/portfolio/pfl_req.xsd"/>
  <!-- This is mandatory; point this to the XML schema file that you 
       created previously in Section 6.1.5. -->
  <sd:OUTPUT_SCHEMA 
   xlink:href="/www.yahoo.com/dServices/portfolio/pfl_resp.xsd"/>
</sd:INTERFACE>
</sd:SERVICE_HEADER>

6.1.6.2 Service Body

This section describes the service body from the same YahooPortfolio service. The fields that you must change to modify your own service are described in this section, starting from the service body as shown in Example 6-12.

Example 6-12 Look for the Beginning of the Service Body

<sd:SERVICE_BODY>
6.1.6.2.1 Input Handling and Input Adaptor Specification

This section describes the input section of the service body.

Modify the input section of the service body of your descriptor to appear as shown in Example 6-13.

Example 6-13 Modify the Input Section of the Service Body

    <sd:INPUT>
  <!-- Aliases are what map the XML requests that the service consumer
       will supply when using the service, to the parameters on
       the HTML form of our Web service. -->
  <sd:ALIASES>
    <sd:ALIAS>
      <!-- This name is just a variable name; all references to it in 
           the service descriptor will access the same value. -->
      <sd:NAME>SymbolList</sd:NAME>
      <!-- No namespace prefix is needed, as the request transformed by
           inputadaptor has no namespace. -->
      <sd:VALUE>{@xpath:value=/PortfolioReq/SymbolList}</sd:VALUE>
    </sd:ALIAS>
  </sd:ALIASES>
  <sd:ADAPTOR>
    <sd:NAME>oracle.ds.engine.ioa.DSXSLTInputAdaptor</sd:NAME>
    <sd:PARAMETERS>
      <xiaParams:XSLT_IA_PARAMS 
        xmlns:xiaParams="http://www.oracle.com/ds/2000/XSLT_IA_PARAMS">
        <xiaParams:XSLT>
          <xsl:stylesheet 
               version="1.0"
               xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
               xmlns:xhtml="http://www.w3.org/1999/xhtml"
               xmlns:pflreq="http://www.portfolio.org/Portfolio/Request">
            <xsl:template match="/">
              <pflreq:PortfolioReq>
                <xsl:apply-templates select="pflreq:PortfolioReq"/>
              </pflreq:PortfolioReq>
            </xsl:template>
            <xsl:template match="pflreq:PortfolioReq">
              <pflreq:SymbolList>
                <xsl:for-each select="pflreq:Symbol">
                  <xsl:value-of select="concat(text(), ',')"/>
                </xsl:for-each>
              </pflreq:SymbolList>
            </xsl:template>
          </xsl:stylesheet>
        </xiaParams:XSLT>
      </xiaParams:XSLT_IA_PARAMS>
    </sd:PARAMETERS>
  </sd:ADAPTOR>
</sd:INPUT>
6.1.6.2.2 Protocol Adaptor Specifications

The protocol adaptor specifications contain information on how to map the aliases defined in Example 6-13 with the actual HTTP GET request.

Modify the protocol section of the service body of your service descriptor as shown in Example 6-14.

Example 6-14 Modify the Protocol Section of the Service Body

<sd:PROTOCOL>
  <sd:ADAPTOR>
    <sd:NAME>oracle.ds.engine.pa.http.DSHTTPProtocolAdaptor</sd:NAME>
    <sd:DRIVER>java.net.URLConnection</sd:DRIVER>
    <sd:PARAMETERS>
      <hpParams:HTTP_PA_PARAMS 
        xmlns:hpParams="http://www.oracle.com/ds/2000/HTTP_PA_PARAMS">
        <hpParams:Method>GET</hpParams:Method>
        <hpParams:URL>quote.yahoo.com/query</hpParams:URL>
        <hpParams:QueryStringParameters>
        <hpParams:QueryStringParameter
          name="SymbolList">{@SymbolList}</hpParams:QueryStringParameter>
        </hpParams:QueryStringParameters>
      </hpParams:HTTP_PA_PARAMS>
    </sd:PARAMETERS>
  </sd:ADAPTOR>
</sd:PROTOCOL>

In the QueryStringParameters and QueryStringParameter sections, the HTTP GET parameter SymbolList is mapped to your alias (which is conveniently also called SymbolList). For more detailed descriptions of the protocol adaptor section, see Section 6.3.2.

6.1.6.2.3 Execution Adaptor Specifications

There are no special execution adaptors that you will use in this service, so none is specified. For more detailed descriptions of the execution adaptor section, see Section 6.3.2.

6.1.6.2.4 Output Adaptor Specifications

The output adaptor specifications contain information on how the raw output from the Web service (HTML) is to be transformed into the structured XML format that is described with your response XML Schema file described previously.

Modify your service descriptor to contain what is shown in Example 6-15.


Note:

If the raw response is an XML document and if no stylesheet is supplied, the service will return the raw response without any processing. 


Example 6-15 Modify the Output Section of the Service Body

<sd:OUTPUT>
  <sd:ADAPTOR>
    <sd:NAME>oracle.ds.engine.ioa.DSXSLTOutputAdaptor</sd:NAME>
    <sd:PARAMETERS>
      <xoParams:XSLT_OA_PARAMS 
        xmlns:xoParams="http://www.oracle.com/ds/2000/XSLT_OA_PARAMS">
        <xoParams:XSLT>
          <xsl:stylesheet version="1.0"
               xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
               xmlns:pflResp="http://www.portfolio.org/Portfolio/Response"
               xmlns:xhtml="http://www.w3.org/1999/xhtml">

            <xsl:template match="/">
              <pflResp:PortfolioResp>
                <xsl:apply-templates
                  xmlns="http://www.w3.org/1999/xhtml"
                  select="html/body/center/table[5]/tr[1]/td/table"/>
              </pflResp:PortfolioResp>
            </xsl:template>
            <xsl:template match="xhtml:table">
              <xsl:for-each select="xhtml:tr">
                <xsl:if test="position()!=1">
                  <!-- Fully scope quote with the response XML schema file -->
                  <pflResp:Quote>
                  <!-- Fully scope symbol also -->
                    <pflResp:Symbol>
                      <xsl:value-of select="xhtml:td[1]/xhtml:a"/>
                    </pflResp:Symbol>
                    <pflResp:Time>
                      <xsl:value-of select="xhtml:td[2]"/>
                    </pflResp:Time>
                    <pflResp:Price>
                      <xsl:value-of select="xhtml:td[3]/xhtml:b"/>
                    </pflResp:Price>
                    <pflResp:Change>
                      <xsl:value-of select="xhtml:td[5]"/>
                    </pflResp:Change>
                    <pflResp:Volume>
                      <xsl:value-of select="xhtml:td[6]"/>
                    </pflResp:Volume>
                  </pflResp:Quote>
                </xsl:if>
              </xsl:for-each>
            </xsl:template>
          </xsl:stylesheet>
        </xoParams:XSLT>
      </xoParams:XSLT_OA_PARAMS>
    </sd:PARAMETERS>    
  </sd:ADAPTOR>
</sd:OUTPUT>

The DSXSLTOutputAdaptor specified first, converts the returned HTML into a more XML-compliant XHTML format. It then applies the supplied XSL stylesheet to that XHTML document to form an XML document that conforms to the response XML schema file that you previously defined in Section 6.1.5.

Close the service body and the service descriptor elements as shown in Example 6-16.

Example 6-16 Close the Service Body and Service Descriptor Elements

  </sd:SERVICE_BODY>
</sd:SERVICE_DESCRIPTOR>

6.1.7 Testing the Execution of Your Service

After constructing the service package and editing the service descriptor, do the following to test the execution of your service:

  1. Run the DSAdmin utility. Use the DSAdmin utility to:
    1. Add the categories by following the instructions in Section 3.2.1.
    2. Register the service by pointing to the demo/services/myService directory on UNIX systems or demo\services\myService directory on Windows NT systems as described in Section 3.2.2.


      Note:

      Anytime you make a change to any service related file, you must reregister that service package using the DSAdmin utility Reregister command. 


  2. Build a sample service request definition and a sample service response definition following the examples described in Example 6-7 and Example 6-9.
  3. Use the DSAdmin utility to execute the service. See Section 3.4 for more information.

You can turn the execution output level to trace by selecting Prop (P) at the top-level menu, and then selecting Change (C) to change the debug output levels. Finally, select TRACE (3) to turn it to the trace level, so you can see every step of the execution flow.

This completes the description of the steps needed to create, register, and test a simple HTTP service.

To create more advanced services, see Section 6.2 through Section 6.5.

6.2 Creating Advanced Services -- Service Package

The service package is structured as a local directory containing a set of files with the following structures:

The MANIFEST file is expected to be found in the root directory of the package, and with the name MANIFEST (uppercase, case-sensitive on Solaris systems; initial uppercase, non case-sensitive on Windows NT systems). The MANIFEST file is a text file where the first non-empty line should specify a URL link to the service descriptor. If a link starts with a slash (/), it indicates the link is an absolute link with respect to the root of the current service package. The root is interpreted to be the root of the directory structure of the service package. The MANIFEST file must end with a new line.


Note:

The <ORACLE_HOME>/ds/etc/xsd directory on UNIX systems or the <ORACLE_HOME>\ds\etc\xsd directory on Windows NT systems contains the XML schema for the service descriptor and supplied adaptors. See the files in this directory for more information. 


6.3 Creating Advanced Services -- Service Descriptor

A service package is modeled through an XML document called a service descriptor that provides a centralized source of description for the service. A service is defined by a multitude of logical components, all of which are specified in the service descriptor or in other documents to which the descriptor refers. There are two sections of the service descriptor:

These descriptor sections, described in Section 6.3.1 and Section 6.3.2 correspond to XML elements with the same names in the service descriptor. For service descriptor examples, refer to the supplied sample services under the <ORACLE_HOME>/ds/demo/services directory on UNIX systems or the <ORACLE_HOME>\ds\demo\services directory on Windows NT systems.

6.3.1 Service Header Section

The service header section contains high-level behavior descriptions of the service. For the most part, information specified in the service header section is descriptive and non-interpretive and primarily for browsing and documentation purposes. The exceptions are the service identifier specification described in Section 6.3.1.1 and the service interface specification described in Section 6.3.1.5.

6.3.1.1 Naming Specification

The service header section has naming information that contains a globally unique identifier for the services, as well as short and long descriptions of what the service does. Each service has a unique name specified using the universal resource name (URN) conventions. Example 6-17 shows a sample naming specification.

Example 6-17 Sample Naming Specification

<!-- Naming specification provides identification information about the
     service. Among the elements, ID is the important one, which
     serves as unique identification. It must be a URN. -->
<sd:NAMING>
  <sd:ID>urn:com.foobar:service_name</sd:ID>
  <sd:NAME>Put a human-readable name here.</sd:NAME>
  <sd:DESCRIPTION>Some description about the service.</sd:DESCRIPTION>
</sd:NAMING>

6.3.1.2 Package Specification

The service header section includes package information with version specifications and pointers to how and where the service update is to be performed. Coupled with support contacts from the service provider information section (see Section 6.3.1.3), this information is critical for service maintenance. Example 6-18 shows a sample package specification.

Example 6-18 Sample Package Specification

<!-- Package provides version information, update locations, and
     binary resource specifications. -->
<sd:PACKAGE>
  <sd:VERSION>1.0</sd:VERSION>
  <sd:RELEASEDATE>25-MAR-2000</sd:RELEASEDATE>
  <sd:UPDATEURL>http://www.foobar.com/dServices/svc.zip</sd:UPDATEURL>
  <sd:BINARY_RESOURCES>
    <!-- JAR_POINTER is used only in the special case that you
         have custom Java classes. Skip the whole JAR_POINTER
         section if no custom Java classes are needed. -->
    <sd:JAR_POINTER
      xlink:href="/www.foobar.com/dServices/dummy.jar" />
    <!-- EXCEPTIONS is the section where the resource bundle for
         custom exceptions can be specified. If the exceptions 
         do not rely on custom resource bundles, the whole EXCEPTIONS
         section can be skipped. -->
    <sd:EXCEPTIONS>
      <sd:EXCEPTION_MSG_BUNDLE>com.foobar.Bundle</sd:EXCEPTION_MSG_BUNDLE>
    </sd:EXCEPTIONS>
  </sd:BINARY_RESOURCES>
</sd:PACKAGE>

6.3.1.3 Service Provider Specification -- Organization and Contacts

This service header section includes high-level information about the service provider, including the service provider's company name, copyright information, and company URL. Detailed information includes contacts for support and URLs for logos. This information is provided in the form of an X-Link that points to another XML document in the service package. Example 6-19 shows a sample service provider specification.

Example 6-19 Sample Service Provider Specification

<sd:PROVIDER>
  <!-- The ORGANIZATION section is a mandatory document that gives information
       about the service provider. For a quick start, it can be filled
       with dummy data. -->
  <sd:ORGANIZATION 
    xlink:href="/www.foobar.com/dServices/foobar_org.xml"/>
  <!-- Each ORGANIZATION section can be associated with zero or more
       contact documents.-->
  <sd:CONTACTS>
    <sd:CONTACT xlink:href="/www.foobar.com/dServices/contact.xml"/>
  </sd:CONTACTS>
</sd:PROVIDER>

6.3.1.4 Deployment Specification -- Classification and Caching

This service header section includes a set of deployment properties that includes suggestions from the service provider to aid the service administrator during registration time. These suggestions include classification guidelines with hierarchical categories, as well as flat keywords and recommendations of caching parameters. This information is also provided in the form of an X-Link that points to another XML document specifying the classification schemes. The values specified here are only suggestions to a service administrator during service registration. The values stored in the service registry could be different from the values specified in the service descriptor. Example 6-20 shows a sample deployment specification.

Example 6-20 Sample Deployment Specification

<sd:DEPLOYMENT>
  <!-- Follow the convention in path name within the zip file. -->
  <sd:CLASSIFICATION
    xlink:href="/www.oanda.com/dServices/currency/class.xml"/>
  <sd:CACHING>
    <sd:MAX_AGE>300</MAX_AGE>
    <sd:SESSION_PRIVATE>false</sd:SESSION_PRIVATE>   
    <sd:USE_PROTOCOL>false</sd:USE_PROTOCOL>
  </sd:CACHING>
</sd:DEPLOYMENT>

See Section 7.3 for more information about service response caching.

6.3.1.5 Service Interface Specification -- Request and Response Definitions

The service header allows for the definition of an interface characterized by the schema specifications of its input, output, and exceptions. The specifications are dispersed in external XML schema documents. The location of the XML schema document file is specified by URLs, when a relative URL is used, that is, relative to the service package submitted by the service providers. By specifying these schemas, the service provider enforces the syntax in which service consumer applications send requests to it, as well as the way in which it provides the responses. The validation will be done in the Dynamic Services engine when a service consumer application sends a request, before the service provider is contacted.

The service provider can also suggest a name for the interface, which is a deployment option and can be overwritten by the service administrator. Any new service that conforms to the same service interface must provide the same input/output (not necessarily the exception) definition. The Dynamic Services engine also exposes to service consumer applications the capability to search for services by interface. Two services that conform to the same interface are considered compatible services, a concept useful for failover.


Note:

To facilitate the development of code that works with Dynamic Services, class generators can be used to create Java classes that correspond to the request/response XML schema files. 


Example 6-21 shows a sample service interface specification.

Example 6-21 Sample Service Interface Specification

<sd:INTERFACE>
  <sd:NAME>FoobarTemplate</sd:NAME>
  <sd:INPUT_SCHEMA xlink:href="/www.foobar.com/dServices/fb_req.xsd"/>
  <sd:OUTPUT_SCHEMA xlink:href="/www.foobar.com/dServices/fb_resp.xsd"/>
</sd:INTERFACE>

6.3.2 Service Body Section

The service body section contains more detailed descriptions and information used by the Dynamic Services engine at service execution time. Specifically, its sections are specifications (including adaptors) on the input, protocol, execution, and output, where:

Figure 6-1 shows a sample service execution and the roles of the input, protocol, and output adaptors, and the flow of information.

Figure 6-1 Sample Service Execution Showing the Role of the Input, Protocol, and Output Specifications as Specified Adaptors


Text description of smpsrvex.gif follows.
Text description of the illustration smpsrvex.gif

Figure 6-2 shows a sample execution adaptor and the role the execution adaptor plays in identifying the way in which one or more sample services is to be executed. In this case, an execution adaptor would specify in its execution flow logic how and why a set of one or more sample services is to be executed. For example, a failover execution adaptor would specify the preferred order of execution of the sample services from its list of compatible services in the event that one or more services failed to execute. In this figure, sample service 1 fails to execute, thus sample service 2 is executed; meanwhile sample service 3 is ready for execution in the event that sample service 2 fails to execute.

Figure 6-2 Sample Execution Adaptor


Text description of rlexadap.gif follows.
Text description of the illustration rlexadap.gif

The service provider can specify the needed adaptor for each of these layers. A set of pre-built, customizable adaptors is supplied by Oracle Dynamic Services. See Section 6.4 for a description of these adaptors.

6.3.2.1 Input Handling and Adaptor Specifications

The service body section has input specifications that provide a list of necessary as well as optional processing steps for the request that is submitted by the service consumer application. This includes the following input specifications:

Section 6.3.2.1.1 through Section 6.3.2.1.4 describe each of these input specifications.

6.3.2.1.1 Input: Namespaces

A list of namespaces with their prefixes can be specified before specifying the aliases. The prefixes can be used in the aliases specification to build the XPaths pointing to where the data is. If no namespaces are needed, this item can be skipped. Example 6-22 shows a sample namespaces specification.

Example 6-22 Sample Namespaces Specification

<sd:NAMESPACES>
  <sd:NAMESPACE>
    <sd:PREFIX>fb</sd:PREFIX>
    <sd:VALUE>http://www.foobar.com/foobar/Request</sd:VALUE>
  </sd:NAMESPACE>
</sd:NAMESPACES>
6.3.2.1.2 Input: Aliases Directives

Service providers may specify alias directives. Aliases are used to create a map that can translate the parameters embedded in the XML service request document to actual parameters needed by the communication protocol of the service. For example, for HTTP, a service provider can specify an XPath for the request XML document addressing an element that represents one of the HTTP request parameters to be sent to the HTTP server. There are currently two possible ways of specifying an alias:

Example 6-23 shows a sample aliases specification, the first using the XPath approach for a value, using the namespace described previously; the second using the XPath approach for a document fragment; and the last using the profile property approach.

This sample uses the fb prefix and the namespace, http://www.foobar.com/foobar/Request described in Section 6.3.2.1.1.

Example 6-23 Sample Aliases Specification

<sd:ALIASES>
  <sd:ALIAS>
    <sd:NAME>AccountNumber</sd:NAME>
    <!-- Indicates that the value is obtained dynamically from the user
         request following the namespace specifed by fb -->
    <sd:VALUE>{@xpath:value=/fb:foobarReq/fb:param1}</sd:VALUE>
  </sd:ALIAS>
    <sd:ALIAS>
    <sd:NAME>SomeFragment</sd:NAME>
    <!-- Indicates that the value is obtained dynamically from the user
         request following the namespace specifed by fb -->
    <sd:VALUE>{@xpath:fragment=/fb:foobarReq/fb:frag1}</sd:VALUE>
  </sd:ALIAS>
  <sd:ALIAS>
    <sd:NAME>Password</sd:NAME>
    <!-- Indicates that the value of the alias should be retrieved as a
         property from the service consumer application profile registry 
         and that the property name is foobarProp1. -->
    <sd:VALUE>{@dscr:property=foobarProp1}</sd:VALUE>
  </sd:ALIAS>
</sd:ALIASES>
6.3.2.1.3 Input: Adaptor Specification

The input adaptor specification can optionally specify an adaptor that further processes the service request before sending it to the service provider. Examples of such processing include semantic or higher-level validation of the request. This input adaptor specification is a fully qualified name of the class implementing the oracle.ds.engine.InputAdaptor Java interface that handles the processing. For the specified adaptor, the service provider has the option of specifying some adaptor-specific parameters in the PARAMETERS element under the adaptor specification that are validated at service registration time, and interpreted at runtime by the adaptor. The parameters are opaque to the service descriptor parser and service registry, and must be in XML syntax.

6.3.2.1.4 Input: Rendering Directives

Under normal execution flow, the request XML that the service consumer application submits or sends to the Dynamic Services engine is validated with the input XML schema file that is specified previously in the header. However, a service provider can optionally supply some form of schema mapping specifications (for example, through an XSL transformation) that could map this input XML schema file to a presentation form such as HTML or Wireless Markup Language (WML). As a result, the service consumer application can easily provide to its clients a way to submit service requests, for applications that have an HTML or WML interface.

The Dynamic Services engine is not responsible for the rendering: all that the engine is responsible for is the capabilities to store and retrieve the mapping. The Dynamic Services engine provides only the mapping(s) of the transformation. The actual transformation is done on the service consumer application side by the client toolkit. If you map the schema to an HTML form, the service consumer applications can use the mapping to render the input schema to an HTML form for their Web application. The service consumer application can then transform the HTTP requests back to an XML document that conforms to the request XML schema file specified by the service provider. Finally, the request XML schema file is sent to the Dynamic Services engine formulating the service request.

6.3.2.2 Protocol Adaptor Specification

The protocol adaptor specification identifies the way that the Dynamic Services engine accesses the underlying service. For example, a service may be accessed through the HTTP protocol, while another service may be accessed through the JDBC protocol. This protocol adaptor specification is a fully qualified name of the class implementing the oracle.ds.engine.ProtocolAdaptor interface. The interface handles the communication to the underlying service. This class name is found either in the service package given by the service provider during registration, or in the set of libraries that the Dynamic Services engine provides.

A driver specification can make sure that a certain class is in the classpath for the adaptor to function properly.

Finally, for the identified adaptor, the service provider has the option of specifying some adaptor-specific parameters in the PARAMETERS element in the adaptor specification, which are validated at service registration time and interpreted at runtime by the adaptor. For example, for HTTP, the adaptor may specify the HTTP method used and the URL that does the actual servicing. These parameters are opaque to the service descriptor parser and service registry, and must be in XML syntax.

Example 6-24 shows a sample protocol adaptor specification using the HTTPS protocol adaptor.

Example 6-24 Sample HTTPS Protocol Adaptor Specification

<sd:PROTOCOL>
  <sd:ADAPTOR>
    <sd:NAME>oracle.ds.engine.pa.http.DSHTTPSProtocolAdaptor</sd:NAME>
    <sd:DRIVER>com.sun.net.ssl.HttpsURLConnection</sd:DRIVER>
    <sd:PARAMETERS>
      <!-- Adaptor-specific parameters -->
    </sd:PARAMETERS>
  </sd:ADAPTOR>
</sd:PROTOCOL>

6.3.2.3 Execution Adaptor Specification

The execution adaptor specification identifies the way in which the service has to be executed. Its responsibility is to receive the request XML schema file and return the response from the underlying service provider.

The default execution adaptor is a standard simple adaptor that follows the path described previously. There can also be complex or compound execution adaptors that aggregate several services, such as in the International Portfolio example.

This execution adaptor specification is a fully qualified class name of a class implementing the oracle.ds.engine.ExecutionAdaptor interface, which performs the execution. For the identified adaptor, the service provider has the option of specifying some adaptor-specific parameters in the PARAMETERS element in the adaptor specification, which are validated at service registration time and interpreted at runtime by the adaptor.

The result of the execution adaptor is the response from the service. If the service is a simple service, the response will be in the native format of the service provider. For example, for a Web-based service, the response may be in HTML format. If the service is a compound service, the response will be a structured service response.

Usually, if the service is a simple service, a service provider will use the default prepackaged simple adaptor. For complex and compound service execution, the service provider can use the supplied compound execution adaptor or DSFailOverExecutionAdaptor or DSConditionalExecutionAdaptor to greater advantage.

6.3.2.4 Output Handling and Adaptor Specification

The output specification specifies the list of necessary as well as optional processing to produce the service response to the service consumer application. This includes the following output specifications:

Section 6.3.2.4.1 and Section 6.3.2.4.2 describe each of these output sections.

6.3.2.4.1 Output: Adaptor Specification

The output adaptor specification can specify an output adaptor to be used to transform the output returned by the execution adaptor. That output is transformed into an XML document compliant with the output XML schema file specified in the service interface. This output adaptor specification is a fully qualified name of the class implementing the oracle.ds.engine.OutputAdaptor interface, which handles the transformation. For the identified output adaptor, the service provider has the option of specifying some adaptor-specific parameters in the PARAMETERS element in the adaptor specification, which are validated at service registration time and interpreted at runtime by the adaptor. These parameters are opaque to the service descriptor parser and service registry, and must be in XML syntax.

Usually, for simple services, service providers will use either of the prepackaged adaptors, such as the XSLT adaptor. For compound services, service providers can use no adaptor because the response from the execution adaptor is often in the proper format prescribed by the output XML schema file.

6.3.2.4.2 Output: Rendering Directives

As far as the service execution flow is concerned, the output specification is the final step. However, Dynamic Services also provides additional mechanisms for the service provider to optionally specify mappings (for example, in the form of XSL transforms) that map this response XML file to other forms, such as HTML or WML. Service consumer applications, rather than the Dynamic Services engine, are responsible for making use of the transformation to produce the desired output. Dynamic Services merely provides a means to store it and make it accessible from the service consumer application.

6.4 Creating Advanced Services -- Description of Supplied Adaptors

Table 6-1 describes the complete set of supplied adaptors provided by Oracle Dynamic Services.

Table 6-1 Adaptors Supplied by Oracle Dynamic Services
Adaptor name  Type 

oracle.ds.engine.ioa.DSXSLTInputAdaptor 

Input 

oracle.ds.engine.pa.http.DSHTTPProtocolAdaptor 

Protocol 

oracle.ds.engine.pa.http.DSHTTPSProtocolAdaptor 

Protocol 

oracle.ds.engine.pa.jdbc.DSJDBCProtocolAdaptor 

Protocol 

oracle.ds.engine.pa.smtp.DSSMTPProtocolAdaptor 

Protocol 

oracle.ds.engine.ea.DSFailOverExecutionAdaptor 

Execution 

oracle.ds.engine.ea.compound.DSCompoundServiceExecutionAdaptor 

Execution 

oracle.ds.engine.ea.DSConditionalExecutionAdaptor 

Execution 

oracle.ds.engine.ioa.DSXSLTOutputAdaptor 

Output 

Section 6.4.1 through Section 6.4.4 offer a more detailed description of the adaptors supplied by Oracle Dynamic Services.

6.4.1 Input Adaptor

Section 6.4.1.1 describes the input adaptor supplied by Oracle Dynamic Services.

6.4.1.1 oracle.ds.engine.ioa.DSXSLTInputAdaptor

DSXSLTInputAdaptor applies an XSLT transformation to the incoming requests and returns the transformed request as a result. In order to use this adaptor, the INPUT/ADAPTOR/NAME must be: oracle.ds.engine.ioa.DSXSLTInputAdaptor

The INPUT/ADAPTOR/PARAMETERS element in the service descriptor must contain what is shown in Example 6-25.

Example 6-25 Sample XSL Stylesheet Information

<xiParams:XSLT_IA_PARAMS 
  xmlns:xiParams="http://www.oracle.com/ds/2000/XSLT_IA_PARAMS">
  <xiParams:XSLT>
    <!-- The XSL Stylesheet -->
  </xiParams:XSLT>
</xiParams:XSLT_IA_PARAMS>

The specified XSL stylesheet can use the aliases defined as xsl variables in the two ways shown in Example 6-26.

Example 6-26 Sample Aliases Defined as XSL Variables

When the value of the alias is used as an XPath expression:

<xsl:variable name="myvar"select = "{@aliasName}"/> 

Or, when the value of the alias is used as a string literal:

<xsl:variable name="myvar">{@aliasName}</xsl:variable>

In the DSXSLTInputAdaptor, there is an option of bringing in other service descriptors before applying the stylesheet. This can be done using an attribute of the xiParams:XSLT element called applyWithServiceDescriptor. Refer to the notifier event monitor service that comes with the Oracle Dynamic Services installation. For more examples of the input adaptor specification for DSXSLTInputAdaptor, refer to the YahooPortfolio service.

6.4.2 Protocol Adaptors

Section 6.4.2.1 through Section 6.4.2.4 describe the protocol adaptors supplied by Oracle Dynamic Services.

6.4.2.1 oracle.ds.engine.pa.http.DSHTTPProtocolAdaptor

DSHTTPProtocolAdaptor processes the HTTP/1.0 specification, sets up the HTTP/1.0 connection, and returns a handler to process the raw output from the service provider.

The parameters and other details needed to execute DSHTTPProtocolAdaptor are defined in the service description, in the section SERVICE_BODY/PROTOCOL/ADAPTOR as shown in Example 6-27.

Example 6-27 Sample HTTP Protocol Adaptor Specification

<sd:SERVICE_BODY>
...
  <sd:PROTOCOL>
    <sd:ADAPTOR>
      <sd:NAME>oracle.ds.engine.pa.http.DSHTTPProtocolAdaptor</sd:NAME>
      <sd:DRIVER>java.net.URLConnection</sd:DRIVER>
      <sd:PARAMETERS>
        <!-- Each protocol adaptor has a namespace where all the
             following elements and/or attributes are defined: -->
        <hpParams:HTTP_PA_PARAMS 
          xmlns:hpParams="http://www.oracle.com/ds/2000/HTTP_PA_PARAMS">
          <hpParams:Method>GET</hpParams:Method>
          <hpParams:URL>www.oanda.com/converter/classic</hpParams:URL>
          <hpParams:QueryStringParameters>
            <hpParams:QueryStringParameter 
              name= "pname1">{@pvalue1}</hpParams:QueryStringParameter>
            <hpParams:QueryStringParameter 
              name= "pname2">{@pvalue2}</hpParams:QueryStringParameter>
          </hpParams:QueryStringParameters>
          <hpParams:RequestHeaders>
            <hpParams:RequestHeader name="hdr1">{@val1}</hpParams:RequestHeader>
            <hpParams:RequestHeader name="hdr2">{@val2}</hpParams:RequestHeader>
          </hpParams:RequestHeaders>
        </hpParams:HTTP_PA_PARAMS>
      </sd:PARAMETERS>  
    </sd:ADAPTOR>
  </sd:PROTOCOL>

This specification consists of two parts. One is a generic part, the other is specific for the given adaptor. The first part includes <NAME> and <DRIVER> elements, which indicate the class names of the specific HTTP adaptor and the handler to process the response from the HTTP resource. The second part, bounded by <PARAMETERS>, is for the specific adaptor; in this case, it must fit the requirements of DSHTTPProtocolAdaptor.

The DSHTTPProtocolAdaptor parameters consist of mandatory and optional elements. The mandatory elements include <Method> and <URL>. <Method> must be one of the three options: GET, POST, or HEAD. The optional elements are <QueryString> and <Authorization>.

In some cases, there may be one or more parameters for the HTTP query string. Each <QueryStringParameter> element within <QueryStringParameters> element defines one parameter. The parameter name is specified as the "name" attribute of the <QueryStringParameter> element, while the parameter value is the element value of <QueryStringParameter>. The element value <QueryStringParameter> may be an alias, which is resolved according to what has been defined in the section SERVICE_BODY/INPUT /ALIASES.

The <RequestHeaders> element is optional in the specification; it is useful for manually setting HTTP request headers in the request. In the example, the two request headers that are set will be used every time an HTTP request is made. The request header name is specified with the "name" attribute of <RequestHeader>, while the request header value is the element value of <RequestHeader>.

Another optional element is <Authorization>, which is useful for some secured Web sites that require the user's login name and password. According to the HTTP/1.0 specification, the content of <Authorization> can be defined in one of two possible structures. The first one puts the login name and password as a single string, while the second one separates them. In both cases, the login name and password are encrypted in Base64. The login name and password can be aliases that refer to other sources as shown in Example 6-28. For more information, refer to the HTTP 1.0 specification Web site listed in Appendix A.

Example 6-28 Sample Login and Password Aliases in the Authorization Specification

<hpParams:Authorization> 
     <hpParams:EncodedString>encodedloginpasswd</hpParams:EncodedString>
</hpParams:Authorization> 

<hpParams:Authorization> 
  <hpParams:Credential>
    <hpParams:Username>encodedusername</hpParams:Username>
    <hpParams:Password>encodedpassword</hpParams:Password>
  </hpParams:Credential>
</hpParams:Authorization>

DSHTTPProtocolAdaptor also supports cookies (see Section 5.1.6). The lifetime of cookies lasts only as long as a service consumer application session.

6.4.2.2 oracle.ds.engine.pa.http.DSHTTPSProtocolAdaptor

This release also provides an HTTPS protocol adaptor. Syntactically it is identical to DSHTTPProtocolAdaptor.

The implementation is based on Sun Microsystems JSSE 1.0.2 global reference implementation.

6.4.2.3 oracle.ds.engine.pa.jdbc.DSJDBCProtocolAdaptor

DSJDBCProtocolAdaptor allows services to interface with an Oracle database by creating a row response from the execution of a SQL statement or a PL/SQL stored procedure. The DSJDBCProtocolAdaptor uses the Oracle XSQL pages technology to express SQL or PL/SQL operations in XML. The parameters supplied in the adaptor are used to define the database connections to be used as well as the XSQL page to be executed. For more information about XSQL pages, see the Oracle XSQL Servlet documentation available on Oracle Technology Network.

Example 6-29 shows the parameters and other details to execute DSJDBCProtocolAdaptor as defined in the service descriptor, in the section SERVICE_BODY/PROTOCOL/ADAPTOR.

Example 6-29 Sample JDBC Protocol Adaptor Specification

<sd:SERVICE_BODY>
...
  <sd:PROTOCOL>
    <sd:ADAPTOR>
      <sd:NAME>oracle.ds.engine.pa.jdbc.DSJDBCProtocolAdaptor</sd:NAME>
      <sd:DRIVER>oracle.jdbc.driver.OracleDriver</sd:DRIVER>
      <sd:PARAMETERS>
        <!-- Each protocol adaptor has a namespace where all the
              following elements and/or attributes are defined: -->
        <jpParams:JDBC_PA_PARAMS
          xmlns:jpParams="http://www.oracle.com/ds/2000/JDBC_PA_PARAMS"
          xmlns:xsql= "urn:oracle-xsql">

        <jpParams:connectiondefs>
          <jpParams:connection name="demo">
          <jpParams:username>{@username}</jpParams:username>
          <jpParams:password>{@password}</jpParams:password>
          <jpParams:dburl>jdbc:oracle:thin:@hostname:port:sid</jpParams:dburl> 
          <jpParams:driver>oracle.jdbc.driver.OracleDriver</jpParams:driver>
          <jpParams:autocommit>true</jpParams:autocommit>
        </jpParams:connection>
        </jpParams:connectiondefs>

        <jpParams:page connection="demo">
        <xsql:query> select ename from emp </xsql:query>
        </jpParams:page>


          </jpParams:JDBC_PA_PARAMS>
        </sd:PARAMETERS>
      </sd:ADAPTOR>
   </sd:PROTOCOL>

These DSJDBCProtocolAdaptor parameters consist of two parts: the first one defines the JDBC connections necessary for processing the XSQL page, while the second one defines the XSQL page to be processed. Because the implementation of DSJDBCProtocolAdaptor uses the Oracle XSQL package, the xsql namespace must be declared in the JDBC_PA_PARAMS elements to correctly scope the XSQL page elements. The use of <username>, <password>,<dburl>, <driver>, and <autocommit> are consistent with those defined in Oracle JDBC Driver 2.0.

As defined by the XSQL syntax, any query statement is quoted within the pair of <xsql:query>, while other DML statements are bounded by <xsql:dml> pairs. The statements may contain some aliases, which are resolved according to what has been defined in the SERVICE_BODY/INPUT/ALIASES section.

In general, all the ALIASES defined for the service are supplied as XSQL parameters to the XSQL page processor. DBService is a sample service to illustrate how to execute any actions to a database.

If additional resources need to be accessed by the XSQL page (for example another XSQL page, an XSL stylesheet, or an XML document), they can be bundled in a jar file packaged as a binary resource for the service. The location of the jar file containing the resource has to be specified as a service binary resource using the BINARY_RESOURCE/JAR_POINTER element in the package section of the service header. The path specified to access those resources will be used to load them from the supplied jar file.

When a service using DSJDBCProtocolAdaptor is executed within a service consumer (application) session, the JDBC connection (identified by its name) is reused within the session. Also, if within a session, two connections are defined with the same name but their connection strings (identified as user name, password, and dburl) do not match, an exception will be raised.

At session closing time, the JDBC connection is rolled back. To commit any updates, a service must explicitly make a commit() call, or set autocommit to be true. The behavior is analogous to discarding cookies for an HTTP connection. It is the responsibility of the service consumer (application) to close any session that it created so that the associated resource will be released.

See the DBService sample service package for more information.

6.4.2.4 oracle.ds.engine.pa.smtp.DSSMTPProtocolAdaptor

DSSMTPProtocolAdaptor is the protocol adaptor used for service providers that use SMTP as an underlying service access mechanism. Such services can include simple mail sending services that get invoked upon the occurrence of an error.

The parameters and other details needed to execute DSSMTPProtocolAdaptor are defined in the service descriptor, in the section SERVICE_BODY/PROTOCOL/ADAPTOR, as shown in Example 6-30. They include information such as the host name, port number of the SMTP server, the from, to, cc, bcc, and subject fields of an e-mail message, additional message headers, and finally a message body. This is an example that is taken from the notifier service that comes with the installation package.

Example 6-30 Sample SMTP Protocol Adaptor Specification

<sd:SERVICE_BODY>
...
  <sd:PROTOCOL>
      <sd:ADAPTOR>
        <sd:NAME>oracle.ds.engine.pa.smtp.DSSMTPProtocolAdaptor</sd:NAME>
        <sd:DRIVER>java.net.Socket</sd:DRIVER>
        <sd:PARAMETERS>
          <!-- Predefined XML schema of the SMTP protocol adaptor parameters -->
          <spParams:SMTP_PA_PARAMS 
            xmlns:spParams="http://www.xyz.com/ds/2000/SMTP_PA_PARAMS">
            <spParams:Host>server1.xyzcorp.com</spParams:Host>
            <spParams:Port>25</spParams:Port>
            <spParams:From>group@server2.xyz.com</spParams:From>
            <!-- Notice how aliases can be used in each of these fields. -->
            <spParams:To>{@To}</spParams:To>
            <spParams:cc>{@cc}</spParams:cc>
            <spParams:Subject>
              Notification for svc: {@EvtSvc} Op: {@EvtType} Stat: {@EvtStat}
            </spParams:Subject>

            <spParams:MsgHeaders>
              <spParams:MsgHeader name="Mime-Version">1.0</spParams:MsgHeader>
              <spParams:MsgHeader
                name="Content-Type">text/html;charset="us-ascii"
              </spParams:MsgHeader>
            </spParams:MsgHeaders>

            <spParams:MsgBody>
              <html>
                <title>Notification for service {@EvtService}.
                       Operation: {@EvtType} Status: {@EvtStatus}</title>
                <body>
                  <H3>Service:     <B>{@EvtService}</B></H3>
                  <H3>Consumer:    <B>{@EvtConsumer}</B></H3>
                  <H3>TimeStamp:   <B>{@EvtTimeStamp}</B></H3>
                  <H3>Operation:   <B>{@EvtType}</B></H3>
                  <H3>Status:      <B>
                    <font color="red">{@EvtStatus}</font></B>
                  </H3>
                  <H3>Description: <B>{@EvtDescription}</B></H3>
                  <P></P>
                  <H3>Message</H3>
                  {@EvtBody}
                </body>
              </html>
            </spParams:MsgBody>
          </spParams:SMTP_PA_PARAMS>
        </sd:PARAMETERS>
      </sd:ADAPTOR>
  </sd:PROTOCOL>

In Example 6-30, the message body actually is an HTML document that displays the status of a certain operation.

6.4.3 Execution Adaptors

Section 6.4.3.1 through Section 6.4.3.3 describe the execution adaptors supplied by Oracle Dynamic Services.

6.4.3.1 oracle.ds.engine.ea.DSFailOverExecutionAdaptor

DSFailOverExecutionAdaptor takes as parameters an ordered list of compatible services, which means the services respond to the same service interface. At execution time, the failover execution adaptor tries to execute the first one in the list; if it fails, it moves to the second list item, and so on, until it finds a service that executes with no exception. If none succeeds, an exception is raised. Example 6-31 shows a sample adaptor specification for a failover service taken from the FailOverPortfolio service.

Example 6-31 Sample Failover Adaptor Specification

<sd:EXECUTION>
  <sd:ADAPTOR> 
    <sd:NAME>oracle.ds.engine.ea.DSFailOverExecutionAdaptor</NAME>
    <sd:PARAMETERS>
      <feParams:FAILOVER_EA_PARAMS 
        xmlns:feParams="http://www.oracle.com/ds/2000/FAILOVER_EA_PARAMS">
        <feParams:execute priority="0">
          urn:com.yahoo:finance.portfolio_fails
        </feParams:execute>
        <feParams:execute priority="1">
          urn:com.cnnfn:finance.portfolio03
        </feParams:execute>
      </feParams:FAILOVER_EA_PARAMS>
    </sd:PARAMETERS>
  </sd:ADAPTOR>
</sd:EXECUTION>

6.4.3.2 oracle.ds.engine.ea.compound.DSCompoundServiceExecutionAdaptor

DSCompoundServiceExecutionAdaptor controls the execution of compound services. Example 6-32 shows the XML portion of a compound service, execution adaptor specification.

Example 6-32 Sample Compound Service Specification

<sd:EXECUTION>
  <sd:ADAPTOR> 
    
<sd:NAME>oracle.ds.engine.ea.compound.DSCompoundServiceExecutionAdaptor</NAME>
    <sd:PARAMETERS>
      <ceParams:COMPOUND_EA_PARAMS
        xmlns:ceParams="http://www.oracle.com/ds/2000/COMPOUND_EA_PARAMS">

Compound services let you encapsulate the execution of a multitude of services by combining them into a directed graph of service executions. Each node of the graph is identified as a CompoundEAModule. There are four possible types of modules that can be used in the graph. Each of the modules is designed as a JavaBean with exposed properties. Those properties are set at compound service design time (probably through service provider design tools), and persist through runtime, when they are used to control the execution.

DSCompoundServiceExecutionAdaptor coordinates the execution of the modules according to the graph specifications, triggering the module executions through JavaBeans events. The following subsections describe the four available modules and their properties.

oracle.ds.engine.ea.compound.ServiceExecution

This module executes one service. It accepts an array of messages, interpreting them as requests, and produces another array of messages composed of responses returned by the service execution(s). There are two possible syntax forms for its properties:

Example 6-33 Sample Service Execution Module with the executeSingleRequest Property

<ceParams:Module name="ID2">
  <ceParams:Class>
    oracle.ds.engine.ea.compound.ServiceExecution
  </ceParams:Class>
  <ceParams:Properties>
    <ceParams:executeSingleRequest index="0">
      ServiceID1
    </ceParams:executeSingleRequest>
  </ceParams:Properties>
</ceParams:Module>

Example 6-34 Sample Service Execution Module with the executeAllRequests Property

<ceParams:Module name="ID3">
  <ceParams:Class>
    oracle.ds.engine.ea.compound.ServiceExecution
  </ceParams:Class>
  <ceParams:Properties>
    <ceParams:executeAllRequests>
      serviceID1
    </ceParams:executeAllRequests>
  </ceParams:Properties>
</ceParams:Module>

oracle.ds.engine.ea.compound.MessageTransformer

This module transforms service messages to either requests or responses. It takes an XSLT stylesheet as a property in its properties element, and applies that XSLT stylesheet to all the incoming service messages to produce a list of outgoing services messages. Note that the MessageTransformer module can take an optional attribute index to select one message from an array of messages of a MessageSplitter module. Example 6-35 shows a sample module specification of the MessageTransformer Module. The stylesheet specified for this adaptor can use the aliases in the same way they are used by the DSXSLTInputAdaptor (see Section 6.4.1.1 for more information). If the <XSLT> element is not supplied, the MessageTransformer module behaves as if an identity transformation was applied.

The XSLTs to be applied by the MessageTransformer module must be packaged into a jar file. The location of the jar file containing the XSLTs must be specified as a service binary resource using the BINARY_RESOURCE/JAR_POINTER element in the package section of the service header. The XSLT path specified in the module properties is used to load the XSLT as a resource from that jar file.

Example 6-35 Sample MessageTransformer Module

<ceParams:Module name="ID4">
  <ceParams:Class>
    oracle.ds.engine.ea.compound.MessageTransformer
  </ceParams:Class>
  <ceParams:Properties>
    <ceParams:XSLT index="0">SomeXSLTURL.xsl</ceParams:XSLT>
  </ceParams:Properties>
</ceParams:Module>

oracle.ds.engine.ea.compound.MessageSplitter

This module splits a single message into multiple messages. It does so in one of two ways:

Example 6-36 Sample Message Section of the MessageSplitter Module

<MESSAGES>
  <MESSAGE index="0">...</MESSAGE>
  <MESSAGE index="1">...</MESSAGE>
</MESSAGES>

Each message must have a valid index, and indexes must be sequential and starting from 0. If this syntax is not matched after applying the transformation to the incoming message, an exception is raised. Example 6-37 shows a sample module specification of the MessageSplitter Module using the SingleTransformation option.

Example 6-37 Sample MessageSplitter Module Using the SingleTransformation Option

<ceParams:Module name="ID5">
  <ceParams:Class>
    oracle.ds.engine.ea.compound.MessageSplitter
  </ceParams:Class>
  <ceParams:Properties>
    <ceParams:SingleTransformation>
      <ceParams:XSLT>SomeXSLT.xsl</ceParams:XSLT>
    </ceParams:SingleTransformation>
  </ceParams:Properties>
</ceParams:Module>

The stylesheet specified for this adaptor can use the aliases in the same way they are used by the DSXSLTInputAdaptor (see Section 6.4.1.1 for more information).

Example 6-38 Sample MessageSplitter Module Using the Multiple Transformation Option

<ceParams:Module name="ID6">
  <ceParams:Class>
     oracle.ds.engine.ea.compound.MessageSplitter
  </ceParams:Class>
  <ceParams:Properties>
    <ceParams:MultipleTransformations>
      <ceParams:XSLT index="0">req2req_curr.xsl</ceParams:XSLT>
      <ceParams:XSLT index="1">req2req_pfl.xsl</ceParams:XSLT>
    </ceParams:MultipleTransformations>
  </ceParams:Properties>
</ceParams:Module>

The XSLTs to be applied by the MessageSplitter module must be packaged into a jar file. The location of the jar file containing the XSLTs must be specified as a service binary resource using the BINARY_RESOURCE/JAR_POINTER element in the package section of the service header. The XSLT path specified in the module properties is used to load the XSLT as a resource from that jar file. The stylesheet specified for this module can use the aliases in the same way they are used by the DSXSLTInputAdaptor (see Section 6.4.1.1 for more information). If the <XSLT> element is not supplied, the MessageSplitter module behaves as if an identity transformation was applied.

oracle.ds.engine.ea.compound.MessageMerger

This module merges multiple service messages into one single message in the form shown in Example 6-39, and then applies an XSLT stylesheet to transform that message.

The XSLT to be applied by the MessageMerger module must be packaged into a jar file. The location of the jar file containing the XSLTs must be specified as a service binary resource using the BINARY_RESOURCE/JAR_POINTER element in the package section of the service header. The XSLT path specified in the module properties is used to load the XSLT as a resource from that jar file. The stylesheet specified for this module can use the aliases in the same way they are used by the DSXSLTInputAdaptor (see Section 6.4.1.1 for more information). If the <XSLT> element is not supplied, the MessageMerger module behaves as if an identity transformation was applied.

Example 6-39 Sample Messages Section of the MessageMerger Module

<MESSAGES>
  <MODULE name="ID1">
  ... msg ...
  </MODULE>
  <MODULE name="ID2">
  ... msg ...
  </MODULE>
</MESSAGES>

Each of the incoming messages is included in a new XML element called Module. Each of the module elements has an attribute reporting the name of the module that generated the message. Example 6-40 shows a sample module specification for the MessageMerger module.

Example 6-40 Sample MessageMerger Module

<ceParams:Module name="ID4">
  <ceParams:Class>
    oracle.ds.engine.ea.compound.MessageMerger
  </ceParams:Class>
  <ceParams:Properties>
    <ceParams:XSLT>resp2resp_ipfl.xsl</ceParams:XSLT>
  </ceParams:Properties>
</ceParams:Module>

DSCompoundServiceExecutionAdaptor acts as a coordinator to control the execution flow among the CompoundEAModules. To define the modules that participate in the execution flow, DSCompoundServiceExecutionAdaptor requires a dependency matrix parameter that is used to evaluate the execution flow. Figure 6-3 shows an example of a network of two service execution adaptors running in parallel.

Figure 6-3 Parallel Execution of Services


Text description of pllexsrv.gif follows.
Text description of the illustration pllexsrv.gif

Figure 6-3 shows a possible use of the modules described previously. In this case, you can achieve the parallel execution of a couple of services by first splitting the service consumer application-supplied request, and then, joining the two services responses into one single response. The dependency matrix supplied in the DSCompoundServiceExecutionAdaptor parameters appears as shown in Example 6-41.

Example 6-41 Sample Dependency Matrix

<ceParams:Graph>
  <ceParams:row name="M1"> 
    <ceParams:column>0</ceParams:column>
    <ceParams:column>0</ceParams:column>
    <ceParams:column>0</ceParams:column>
    <ceParams:column>0</ceParams:column>
  </ceParams:row>
  <ceParams:row name="M2"> 
    <ceParams:column>1</ceParams:column>
    <ceParams:column>0</ceParams:column>
    <ceParams:column>0</ceParams:column>
    <ceParams:column>0</ceParams:column>
  </row>
  <ceParams:row name="M3"> 
    <ceParams:column>1</ceParams:column>
    <ceParams:column>0</ceParams:column>
    <ceParams:column>0</ceParams:column>
    <ceParams:column>0</ceParams:column>
  </ceParams:row>
  <ceParams:row name="M4"> 
    <ceParams:column>0</ceParams:column>
    <ceParams:column>1</ceParams:column>
    <ceParams:column>1</ceParams:column>
    <ceParams:column>0</ceParams:column>
  </ceParams:row>
</ceParams:Graph>

The matrix shows the dependencies on the input of each of the modules. DSCompoundServiceExecutionAdaptor uses this information to coordinate the execution flow, and creates the necessary threads to allow for parallel execution, if necessary. For a complete example showing how to define compound services, refer to the supplied International Portfolio (IPFL) sample service in the sample service packages directory (see Appendix D for more information).

6.4.3.3 oracle.ds.engine.ea.DSConditionalExecutionAdaptor

DSConditionalExecutionAdaptor controls the flow of execution because it executes a specified service based on the value of a certain defined alias. Service providers can configure the adaptor with switch statements that can be nested, to specify something like a decision tree, where the leaf elements are the IDs of the services to execute.

For each switch element, there is an attribute called on that you must specify to tell the adaptor which alias to switch on. In this case, only the alias is referenced, thus the value of this attribute should be just the alias name rather than {@alias}. The {@alias} value means preprocessing the value, and using the value of the alias.

For each case element under a switch element, there is an attribute called value that you must specify to tell the adaptor which match of the alias brings you to the inside of the case element. Inside the case element, there can be either an execute element, which means that you have reached a leaf and that its element value is the ID of the service to be executed, or you have reached another nested switch statement.

Example 6-42 shows a sample execution adaptor specification for a DSConditionalExecutionAdaptor taken from the smartlog service that comes with the installation package.

Example 6-42 Sample DSConditionalExecutionAdaptor Execution Adaptor

<sd:EXECUTION>
  <sd:ADAPTOR>
  <sd:NAME>oracle.ds.engine.ea.DSConditionalExecutionAdaptor</sd:NAME>
    <sd:PARAMETERS>
      <deParams:CONDITIONAL_EA_PARAMS 
        xmlns:deParams="http://www.oracle.com/ds/2000/CONDITIONAL_EA_PARAMS">
        <!-- eventType has been defined previously as an alias; note, here
             we are referencing it only so the syntax used is just the alias
             name and not {@alias}. -->
        <deParams:switch on="eventType">
          <deParams:case value="CONNECT">
            <!-- Here is an example of the nesting of switch statements. -->
            <deParams:switch on="eventStatus">
              <!-- We traverse here if the eventType alias == "FAILED" -->
              <deParams:case value="FAILED">
                <!-- This is where you specify what service to execute. -->
                <deParams:execute>urn:com.oracle:ds.logger</deParams:execute>
              </deParams:case>
              <deParams:case value="CLOSE">
                <deParams:execute>urn:com.oracle:ds.logger</deParams:execute>
              </deParams:case>
              <deParams:default>urn:com.oracle:ds.logger</deParams:default>
            </deParams:switch>
          </deParams:case>

          <deParams:case value="LOOKUP">
            <deParams:switch on="eventStatus">
              <deParams:case value="OPEN">
                <deParams:execute>urn:com.oracle:ds.logger</deParams:execute>
              </deParams:case>
              <deParams:case value="FAILED">
                <deParams:execute>urn:com.oracle:ds.logger</deParams:execute>
              </deParams:case>
              <deParams:default>urn:com.oracle:ds.logger</deParams:default>
            </deParams:switch>
          </deParams:case>

        </deParams:switch>
      </deParams:CONDITIONAL_EA_PARAMS>
    </sd:PARAMETERS>
  </sd:ADAPTOR>
</sd:EXECUTION>

6.4.4 Output Adaptor

Section 6.4.4.1 describes the output adaptor supplied by Oracle Dynamic Services.

6.4.4.1 oracle.ds.engine.ioa.DSXSLTOutputAdaptor

DSXSLTOutputAdaptor applies an XSLT stylesheet to transform either a java.net.URLConnection or an oracle.xml.parser.v2.XMLDocument raw response. In the case of a URLConnection, this adaptor first checks if the content-type is text/html, text/xml, or application/xml. In the HTML case, it first applies a stylesheet to transform the HTML representation into XHTML, compliant with W3C XHTML 1.0 specifications. Finally, an XSLT stylesheet is applied to the XML response. The adaptor parameters in the service descriptor define the stylesheet to apply. The stylesheet specified for this adaptor can use the aliases in the same way they are used by the DSXSLTInputAdaptor (see Section 6.4.1.1 for more information). Refer to the YahooPortfolio sample service for an example. If no <XSLT> argument is passed to the DSXSLTOutputAdaptor, the DSXSLTOutputAdaptor behaves as if an identity XSLT transformation is applied.

In the DSXSLTOutputAdaptor, there is an option of bringing in other service descriptors before applying the stylesheet. This can be done using an attribute of the xiParams:XSLT element called applyWithServiceDescriptor. Refer to the notifier event monitor service that comes with the Oracle Dynamic Services installation. This option can be used, for example, to bring in the logo of the service provider.

6.5 Creating Advanced Services -- Building Your Own Adaptors

Service providers can supply their own adaptors. As described previously, according to the layer or role that the adaptor addresses during the service execution, each adaptor must implement the corresponding Java interface. For example, input adaptors must implement the oracle.ds.engine.InputAdaptor interface and so on.

For more information about the responsibilities of each adaptor and the interfaces, see the description in the JavaDoc documentation.

For an example of building your own adaptors, refer to the YahooPortfolioCustomAdaptor demo service provided in the ds/demo/services/YahooPortfolioCustomAdaptor directory on Solaris or ds\demo\services\YahooPortfolioCustomAdaptor directory on Windows NT.

6.5.1 Packaging Your Adaptor

Once you have built your classes, grouped them into a jar file, and bundled the file into your service package, ensure the jar pointer element in the binary resource section of the service descriptor refers to the correct jar file. See Section 6.3.1.2 for more information.


Go to previous page Go to next page
Oracle
Copyright © 1996-2001, Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback