Release 9.0.1
Part Number A88783-01
 Home |
 Book List |
 Contents |
 Index |  Master Index |  Feedback |
| Oracle Dynamic Services User's and Administrator's Guide Release 9.0.1 Part Number A88783-01 |
|
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:
MANIFEST file that points to the service descriptor XML file
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.
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:
Perform the following steps to create your service package:
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.
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
demo\services\SampleService directory into a new directory using your name, for example, demo\services\myService.
demo\services\myService directory and rename SampleProvider to www.yahoo.com.
www.yahoo.com\dServices directory and rename SampleService to portfolio, SampleOrg.xml to YahooOrg.xml, and SampleContact.xml to YahooContact.xml.
portfolio subdirectory and rename SampleService.xml to ypfl.xml and SampleServiceClassification.xml to ypflClass.xml.
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.
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.
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.
YahooOrg.xml file to appear as shown in Example 6-3.
<?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>
YahooContact.xml file to appear as shown in Example 6-4.
<?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>
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.
<?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>
Before editing the service descriptor, you must understand how requests are defined.
http://quote.yahoo.com.
<form method=get action="/q"><nobr> <input type=text size=25 name=SymbolList> <input type=submit value="Get Quotes"> ... </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.
The form takes one input called SymbolList. From there, you can expect the service consumer application to pass in only one argument, and generate an XML schema file for your request, such as shown in Example 6-7.
<?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.
/www.yahoo.com/dServices/portfolio/ on UNIX systems or \www.yahoo.com\dServices\portfolio\ on Windows NT systems and name it ypfl_req.xsd.
When the HTTP GET request is made, the HTML page shown contains the actual stock quote that you want.
<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>
<?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.
/www.yahoo.com/dServices/portfolio/ directory on UNIX systems or \www.yahoo.com\dServices\portfolio\ directory on Windows NT systems and name it ypfl_resp.xsd.
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.
<sd:SERVICE_DESCRIPTOR xmlns:sd="http://www.oracle.com/ds/2000/SERVICE_DESCRIPTOR" xmlns:xlink="http://www.w3.org/1999/xlink">
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.
<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>
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.
<sd:SERVICE_BODY>
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.
<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>
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.
<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.
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.
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.
<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.
</sd:SERVICE_BODY> </sd:SERVICE_DESCRIPTOR>
After constructing the service package and editing the service descriptor, do the following to test the execution of your service:
demo/services/myService directory on UNIX systems or demo\services\myService directory on Windows NT systems as described in Section 3.2.2.
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.
The service package is structured as a local directory containing a set of files with the following structures:
MANIFEST file pointing to the service descriptor
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.
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.
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.
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.
<!-- 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>
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.
<!-- 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>
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.
<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>
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.
<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.
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.
Example 6-21 shows a 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>
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-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.
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.
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.
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.
<sd:NAMESPACES> <sd:NAMESPACE> <sd:PREFIX>fb</sd:PREFIX> <sd:VALUE>http://www.foobar.com/foobar/Request</sd:VALUE> </sd:NAMESPACE> </sd:NAMESPACES>
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.
<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>
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.
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.
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.
<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>
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.
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.
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.
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.
Table 6-1 describes the complete set of supplied adaptors provided by Oracle Dynamic Services.
Section 6.4.1 through Section 6.4.4 offer a more detailed description of the adaptors supplied by Oracle Dynamic Services.
Section 6.4.1.1 describes the input adaptor supplied by Oracle Dynamic Services.
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.
<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.
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.
Section 6.4.2.1 through Section 6.4.2.4 describe the protocol adaptors supplied by Oracle Dynamic Services.
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.
<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.
<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.
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.
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.
<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.
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.
<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> <PRE>{@EvtBody}</PRE> </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.
Section 6.4.3.1 through Section 6.4.3.3 describe the execution adaptors supplied by Oracle Dynamic Services.
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.
<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>
DSCompoundServiceExecutionAdaptor controls the execution of compound services. Example 6-32 shows the XML portion of a compound service, execution adaptor 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.
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:
With this option for the properties, the module takes in a message index number as an attribute -- a request event can contain a list of requests -- and takes the ID of the service to be executed, as an element value. Only one execution is performed using the one selected request message, and the service executed is the one specified by the ID with that request. Example 6-33 shows a sample ServiceExecution module specification with the executeSingleRequest property option.
<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>
With this option for the properties, the module takes the ID of the service as an element value, and executes the service with all the request messages from the request event, generating response messages and building up a response event. Example 6-34 shows a sample ServiceExecution module specification with the executeAllRequests property option.
<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>
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.
<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>
This module splits a single message into multiple messages. It does so in one of two ways:
With this option of the properties, an XSLT stylesheet is specified in an element called XSLT and this stylesheet is able to transform the starting service message into a well-known structure described in Example 6-36. A list of service messages can then be generated from it.
<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.
<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).
With this option, a list of XSLT stylesheets is specified that correspond to a list of transformations performed on the original service message. This results in a list of resulting messages. With each XSLT stylesheet, an index is specified to order the list of service messages that result in the one-by-one application of the XSLT stylesheets. Example 6-38 shows a sample module specification of the MessageSplitter Module using the MultipleTransformations 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.
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.
<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.
<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 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.
<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).
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.
<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>
Section 6.4.4.1 describes the output adaptor supplied by Oracle Dynamic Services.
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.
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.
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.
|
 Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|