Table Of Content(cid:226)
Oracle Dynamic Services
User’s and Administrator’s Guide
Release 9.0.1
June 2001
Part No. A88783-01
Oracle Dynamic Services is a Java-based programmatic framework for
incorporating, managing, and deploying Internet services. Oracle Dynamic
Services makes it easy for application developers to rapidly incorporate existing
services residing in Web sites, local databases, or proprietary systems into their
own applications.
Oracle Dynamic Services User’s and Administrator’s Guide, Release 9.0.1
Part No. A88783-01
Copyright © 2000, 2001, Oracle Corporation. All rights reserved.
Primary Authors: Alok Srivastava, Marco Carrer, Paul Lin, Wei Qian, Sam Lee, Kan Deng, Cheng Han,
Alan Wu, Rod Ward
Contributing Authors: Timothy Chien, Michael Sekurski, Christine Chan, Joseph Meeks, Bill
Beauregard, Katherine Oakey, Larry Guros, Yoko Mizuno, Susan Shepard
The Programs (which include both the software and documentation) contain proprietary information of
Oracle Corporation; they are provided under a license agreement containing restrictions on use and
disclosure and are also protected by copyright, patent, and other intellectual and industrial property
laws. Reverse engineering, disassembly, or decompilation of the Programs is prohibited.
The information contained in this document is subject to change without notice. If you find any problems
in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this
document is error free. Except as may be expressly permitted in your license agreement for these
Programs, no part of these Programs may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation.
If the Programs are delivered to the U.S. Government or anyone licensing or using the programs on
behalf of the U.S. Government, the following notice is applicable:
Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial
computer software" and use, duplication, and disclosure of the Programs, including documentation,
shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement.
Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer
software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR
52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500
Oracle Parkway, Redwood City, CA 94065.
The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently
dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup,
redundancy, and other measures to ensure the safe use of such applications if the Programs are used for
such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the
Programs.
Oracle and SQL*Plus are registered trademarks, and Oracle9i is a trademark of Oracle Corporation.
Other names may be trademarks of their respective owners.
Contents
LLLiiisssttt ooofff TEFaxigbaumlerespsles
Send Us Your Comments.................................................................................................................. xiii
Preface........................................................................................................................................................... xv
Audience................................................................................................................................................ xv
Organization.......................................................................................................................................... xv
Related Documents.............................................................................................................................. xvi
Conventions......................................................................................................................................... xvii
Documentation Accessibility............................................................................................................ xvii
1 Introduction
1.1 Application Scenarios........................................................................................................... 1-2
1.1.1 Business Problems or Technical Challenges.............................................................. 1-2
1.1.2 Oracle Dynamic Services Solutions............................................................................. 1-3
1.1.2.1 Wireless Service Developers................................................................................. 1-4
1.1.2.2 Portal Service Developers...................................................................................... 1-5
1.1.2.3 e-Business Service Application Developers........................................................ 1-5
1.2 Overview of Concepts.......................................................................................................... 1-5
1.2.1 Service Provider............................................................................................................. 1-9
1.2.2 Service Registry............................................................................................................ 1-10
1.2.3 Application Profile Registry....................................................................................... 1-10
1.2.4 Service Administrator.................................................................................................. 1-10
1.2.5 Service Consumer Application.................................................................................. 1-10
1.2.6 Dynamic Services Engine............................................................................................ 1-11
iii
1.2.7 Services as Application Components........................................................................ 1-11
1.2.8 Communication Between the Service Consumer Application and the Dynamic
Services Engine ..................................................................................................1-12
1.2.9 Communication Between the Service Administrator and the Dynamic Services
Engine ................................................................................................................1-12
1.3 Dynamic Services Implementation Overview................................................................. 1-12
1.3.1 Java Deployment View................................................................................................ 1-14
1.3.2 PL/SQL Deployment View......................................................................................... 1-16
1.3.3 Java (HTTP/Java Messaging Services (JMS)) Deployment View......................... 1-17
1.4 Using Multiple Dynamic Services Engines...................................................................... 1-19
1.5 How to Get Started with Oracle Dynamic Services........................................................ 1-20
2 Installation
2.1 System Requirements............................................................................................................ 2-1
2.2 Dynamic Services Distribution............................................................................................ 2-2
2.3 Installing the DSSYS Schema............................................................................................... 2-3
2.4 Dynamic Services Configuration......................................................................................... 2-5
3 Configuration
3.1 Configuring and Running the DSAdmin Utility.............................................................. 3-1
3.1.1 Configuring Dynamic Services Proxy Settings.......................................................... 3-2
3.1.2 Configuring the DSAdmin Utility............................................................................... 3-2
3.1.3 Running the DSAdmin Utility...................................................................................... 3-4
3.2 Registering a New Service.................................................................................................... 3-5
3.2.1 Creating a New Service Package Category................................................................ 3-7
3.2.2 Registering a Service Package...................................................................................... 3-9
3.3 Browsing Registered Services.............................................................................................. 3-9
3.4 Executing a Registered Service.......................................................................................... 3-11
4 Advanced Installation Options
4.1 Enabling PL/SQL Interfaces................................................................................................ 4-1
4.2 Enabling Persistent Auditing or Event Monitor Services................................................ 4-3
4.2.1 Configuring Oracle Advanced Queuing..................................................................... 4-3
4.2.2 Installing Monitor Services........................................................................................... 4-3
iv
4.2.3 Using the Event Monitor Utility.................................................................................. 4-4
4.2.4 Enabling Persistent Auditing....................................................................................... 4-5
4.2.5 Starting and Stopping the Event Monitor.................................................................. 4-5
4.2.6 Using the Logger Monitor Service (Case Study)....................................................... 4-6
4.3 Enabling HTTP Communications....................................................................................... 4-8
4.3.1 Configuring the Apache/Jserv Servlet Engine.......................................................... 4-8
4.3.2 Configuring the DSAdmin Utility to Use the HTTP Driver.................................. 4-11
4.4 Enabling Java Messaging Services (JMS) Communications.......................................... 4-11
4.4.1 Configuring and Running the JMS Daemon............................................................ 4-12
4.4.2 Configuring the DSAdmin Utility to Enable JMS Communications.................... 4-13
4.5 Using Lightweight Directory Access Protocol (LDAP) as a Central Master Registry.........
....................................................................................................................................4-14
4.5.1 Setting Up LDAP with Oracle Internet Directory................................................... 4-14
4.5.1.1 Oracle Internet Directory..................................................................................... 4-14
4.5.1.2 Dynamic Services LDAP Schema....................................................................... 4-15
4.5.2 Configuring Dynamic Services Registry to Use LDAP.......................................... 4-16
4.6 Manual Fine-Tuning of Dynamic Services Properties................................................... 4-17
5 Service Consumer Interfaces
5.1 Java Interface for Service Consumers................................................................................. 5-1
5.1.1 Setting the Classpath..................................................................................................... 5-2
5.1.2 Registering a Service Consumer Application in the Application Profile Registry 5-2
5.1.3 Opening a Connection to the Dynamic Services Engine.......................................... 5-4
5.1.3.1 Available Connection Drivers............................................................................... 5-4
5.1.4 Example: Executing the YahooPortfolio Service....................................................... 5-5
5.1.5 Displaying Service Response........................................................................................ 5-6
5.1.6 Service Consumer Application Sessions..................................................................... 5-7
5.2 PL/SQL Interface for Service Consumers......................................................................... 5-7
6 Service Development Guide
6.1 Quick Start.............................................................................................................................. 6-2
6.1.1 Creating a Service Package........................................................................................... 6-3
6.1.2 Service Provider -- Organization and Contacts XML Files...................................... 6-4
6.1.3 Service Classification XML File.................................................................................... 6-5
6.1.4 Service Interface Specification -- Request Definition................................................ 6-6
v
6.1.5 Service Interface Specification -- Response Definition.............................................. 6-7
6.1.6 Editing the Service Descriptor...................................................................................... 6-9
6.1.6.1 Service Header......................................................................................................... 6-9
6.1.6.2 Service Body........................................................................................................... 6-11
6.1.7 Testing the Execution of Your Service....................................................................... 6-15
6.2 Creating Advanced Services -- Service Package............................................................. 6-15
6.3 Creating Advanced Services -- Service Descriptor......................................................... 6-16
6.3.1 Service Header Section................................................................................................ 6-16
6.3.1.1 Naming Specification........................................................................................... 6-17
6.3.1.2 Package Specification............................................................................................ 6-17
6.3.1.3 Service Provider Specification -- Organization and Contacts......................... 6-18
6.3.1.4 Deployment Specification -- Classification and Caching................................ 6-18
6.3.1.5 Service Interface Specification -- Request and Response Definitions............ 6-19
6.3.2 Service Body Section.................................................................................................... 6-20
6.3.2.1 Input Handling and Adaptor Specifications..................................................... 6-22
6.3.2.2 Protocol Adaptor Specification........................................................................... 6-25
6.3.2.3 Execution Adaptor Specification........................................................................ 6-26
6.3.2.4 Output Handling and Adaptor Specification................................................... 6-26
6.4 Creating Advanced Services -- Description of Supplied Adaptors.............................. 6-27
6.4.1 Input Adaptor............................................................................................................... 6-28
6.4.1.1 oracle.ds.engine.ioa.DSXSLTInputAdaptor...................................................... 6-28
6.4.2 Protocol Adaptors........................................................................................................ 6-29
6.4.2.1 oracle.ds.engine.pa.http.DSHTTPProtocolAdaptor......................................... 6-29
6.4.2.2 oracle.ds.engine.pa.http.DSHTTPSProtocolAdaptor....................................... 6-31
6.4.2.3 oracle.ds.engine.pa.jdbc.DSJDBCProtocolAdaptor.......................................... 6-31
6.4.2.4 oracle.ds.engine.pa.smtp.DSSMTPProtocolAdaptor....................................... 6-33
6.4.3 Execution Adaptors...................................................................................................... 6-34
6.4.3.1 oracle.ds.engine.ea.DSFailOverExecutionAdaptor.......................................... 6-35
6.4.3.2 oracle.ds.engine.ea.compound.DSCompoundServiceExecutionAdaptor.... 6-35
6.4.3.3 oracle.ds.engine.ea.DSConditionalExecutionAdaptor.................................... 6-42
6.4.4 Output Adaptor............................................................................................................ 6-43
6.4.4.1 oracle.ds.engine.ioa.DSXSLTOutputAdaptor................................................... 6-43
6.5 Creating Advanced Services -- Building Your Own Adaptors..................................... 6-44
6.5.1 Packaging Your Adaptor............................................................................................. 6-44
vi
7 Service Administration
7.1 Managing Consumer Applications..................................................................................... 7-1
7.2 Managing Services................................................................................................................ 7-2
7.3 Service Response Caching.................................................................................................... 7-3
7.4 Cache Cleanup....................................................................................................................... 7-4
7.5 Connecting Multiple Dynamic Services Engine Instances.............................................. 7-4
7.6 Additional Operations of the DSAdmin Utility................................................................ 7-5
7.6.1 Using Script Files with the DSAdmin Utility............................................................. 7-5
8 Known Issues and Problems
8.1 Communications................................................................................................................... 8-1
8.2 Service Execution................................................................................................................... 8-1
8.3 Service Definitions and Creation........................................................................................ 8-1
8.4 Other Problems and Issues.................................................................................................. 8-1
A Links
B Frequently Asked Questions
C Descriptive Matrix
C.1 Syntax of the Service Descriptor Schema........................................................................... C-1
C.2 Syntax of the Parameters Section for the Packaged Adaptors........................................ C-9
C.2.1 oracle.ds.engine.ioa.DSXSLTInputAdaptor............................................................. C-10
C.2.2 oracle.ds.engine.ioa.DSXSLTOutputAdaptor.......................................................... C-10
C.2.3 oracle.ds.engine.pa.DSHTTPProtocolAdaptor........................................................ C-11
C.2.4 oracle.ds.engine.pa.DSJDBCProtocolAdaptor......................................................... C-12
C.2.5 oracle.ds.engine.pa.DSSMTPProtocolAdaptor........................................................ C-13
C.2.6 oracle.ds.engine.ea.compound.DSCompoundServiceExecutionAdaptor........... C-14
C.2.7 oracle.ds.engine.ea.DSConditionalExecutionAdaptor........................................... C-17
C.2.8 oracle.ds.engine.ea.DSFailOverExecutionAdaptor................................................. C-18
vii
D Sample Service Packages
E Error Messages
E.1 Execution Engine Errors....................................................................................................... E-1
E.2 Communication Errors......................................................................................................... E-2
E.3 DS Registry Errors................................................................................................................. E-5
E.4 DS Engine Errors................................................................................................................. E-10
E.5 DS Driver Errors.................................................................................................................. E-18
E.6 DS Compound Execution Adaptor Module Errors........................................................ E-18
Glossary
Index
viii
List of Examples
3–1 Configure the DSAdmin Utility.......................................................................................... 3-3
3–2 Run the DSAdmin Utility..................................................................................................... 3-5
3–3 Create a Set of Categories Required by the Yahoo Service Package.............................. 3-8
3–4 Register a Service Package................................................................................................... 3-9
3–5 Search a List of Registered Services by Category........................................................... 3-10
3–6 Returning a List of Services Using the Wildcard "*" Search.......................................... 3-10
3–7 Search a List of Registered Services by Interface............................................................ 3-11
3–8 Execute a Registered Service............................................................................................. 3-12
4–1 Set the aq_tm_process init.ora Parameter.......................................................................... 4-3
4–2 Configure the MonitorInstall.dss File................................................................................. 4-4
4–3 Usage Syntax for Running the Event Monitor Utility...................................................... 4-5
4–4 Connect to the DSSYS Schema as DSSYS User................................................................. 4-5
4–5 Start the Event Monitor........................................................................................................ 4-6
4–6 Stop the Event Monitor......................................................................................................... 4-6
4–7 Define the Raw Log Object Table........................................................................................ 4-6
4–8 Definition of the Raw Event Object Table.......................................................................... 4-6
4–9 Make a SQL Query of the Logging Events........................................................................ 4-7
4–10 Run the ldapmodify Command to Create Default Entries for Dynamic Services..... 4-16
4–11 Configure the Dynamic Services Registry to Use the Master LDAP Server............... 4-17
5–1 Include These Dynamic Services Libraries in Your Classpath....................................... 5-2
5–2 Create a New Database User Using These SQL Statements........................................... 5-2
5–3 Register the Application as a New Dynamic Services Consumer.................................. 5-3
5–4 Connect to the Oracle Dynamic Services Engine as User serviceconsumer1............... 5-3
5–5 Specify a Driver and Open a Connection for a Service Consumer Application.......... 5-4
5–6 Request a Service and the Service Execution Call............................................................ 5-5
5–7 Request the YahooPortfolio Service.................................................................................... 5-6
5–8 Display a Service Response.................................................................................................. 5-6
5–9 Use These Grant Statements to Access the PL/SQL DynamicServices Package......... 5-7
5–10 PL/SQL Interface for Dynamic Services............................................................................ 5-8
5–11 Sample Code to Use the Dynamic Services PL/SQL Interface Package....................... 5-9
6–1 Create a Default Service Package........................................................................................ 6-3
6–2 Update the MANIFEST File................................................................................................. 6-4
6–3 Edit the YahooOrg.xml File................................................................................................. 6-4
6–4 Edit the YahooContact.xml File........................................................................................... 6-5
6–5 Edit the ypflClass.xml File................................................................................................... 6-5
6–6 Examine a Typical HTML Form.......................................................................................... 6-6
6–7 Generate an XML Schema File for the Service Request................................................... 6-6
6–8 Examine the Code and Note the Stock Symbol ORCL.................................................... 6-7
6–9 Create an XML Schema File for the Service Response..................................................... 6-8
ix
6–10 Examine the Beginning of the Service Descriptor............................................................ 6-9
6–11 Modify the Service Header................................................................................................... 6-9
6–12 Look for the Beginning of the Service Body.................................................................... 6-11
6–13 Modify the Input Section of the Service Body................................................................. 6-11
6–14 Modify the Protocol Section of the Service Body............................................................ 6-12
6–15 Modify the Output Section of the Service Body.............................................................. 6-13
6–16 Close the Service Body and Service Descriptor Elements............................................. 6-15
6–17 Sample Naming Specification............................................................................................ 6-17
6–18 Sample Package Specification............................................................................................ 6-17
6–19 Sample Service Provider Specification............................................................................. 6-18
6–20 Sample Deployment Specification.................................................................................... 6-19
6–21 Sample Service Interface Specification............................................................................. 6-20
6–22 Sample Namespaces Specification.................................................................................... 6-23
6–23 Sample Aliases Specification.............................................................................................. 6-23
6–24 Sample HTTPS Protocol Adaptor Specification.............................................................. 6-25
6–25 Sample XSL Stylesheet Information.................................................................................. 6-28
6–26 Sample Aliases Defined as XSL Variables....................................................................... 6-28
6–27 Sample HTTP Protocol Adaptor Specification................................................................ 6-29
6–28 Sample Login and Password Aliases in the Authorization Specification................... 6-30
6–29 Sample JDBC Protocol Adaptor Specification................................................................. 6-31
6–30 Sample SMTP Protocol Adaptor Specification................................................................ 6-33
6–31 Sample Failover Adaptor Specification............................................................................ 6-35
6–32 Sample Compound Service Specification........................................................................ 6-35
6–33 Sample Service Execution Module with the executeSingleRequest Property............ 6-36
6–34 Sample Service Execution Module with the executeAllRequests Property................ 6-37
6–35 Sample MessageTransformer Module.............................................................................. 6-37
6–36 Sample Message Section of the MessageSplitter Module.............................................. 6-38
6–37 Sample MessageSplitter Module Using the SingleTransformation Option................ 6-38
6–38 Sample MessageSplitter Module Using the Multiple Transformation Option.......... 6-39
6–39 Sample Messages Section of the MessageMerger Module............................................ 6-40
6–40 Sample MessageMerger Module....................................................................................... 6-40
6–41 Sample Dependency Matrix............................................................................................... 6-41
6–42 Sample DSConditionalExecutionAdaptor Execution Adaptor.................................... 6-42
7–1 Run the DSAdmin Utility Using the -i Option.................................................................. 7-6
x
