3
Configuration

To get started with Oracle Dynamic Services, you must first configure and run the DSAdmin utility. Then you can use the DSAdmin utility to register a new service, browse through your list of registered services, and finally, execute a registered service. This chapter describes each of these topics.

3.1 Configuring and Running the DSAdmin Utility

To verify a successful installation, use the DSAdmin command-line utility (dsadmin on UNIX systems or dsadmin.bat on Windows NT).

The DSAdmin utility allows command-line interactions with the Oracle Dynamic Services engine and lets you perform common operations, such as service registration, service unregistration, and service execution testing.

3.1.1 Configuring Dynamic Services Proxy Settings

In order to connect to services located outside of a firewall for testing the sample service, you must first configure the Dynamic Services proxy settings. To do this, you must run SQL*Plus and connect as dssys user and enter your <dssys-password> and execute three procedures as follows:

sqlplus dssys/<dssys-password>
set serveroutput on
exec ds_properties.show()
exec ds_properties.setProperty('proxyHost','<www-your complete proxy name>')
exec ds_properties.setProperty('proxySet','true')

For more information about setting these Dynamic Services properties, see Section 4.6.

3.1.2 Configuring the DSAdmin Utility

Before you run the DSAdmin utility, you must configure its configuration XML file, DSAdminConfig.xml, located in the following directory:

On UNIX systems:

$<ORACLE_HOME>/ds/etc/dsadmin/ 

On Windows NT systems:

$<ORACLE_HOME>\ds\etc\dsadmin\ 

Note that this is the default path where the DSAdmin utility expects to find its configuration file.

1. Open the DSAdminConfig.xml file in an editor.

   With the basic Dynamic Services installation, only connections using the DSDirectDriver driver can be used. Therefore, the only element you need to change is DS_URL for connections that use the Direct driver.

2. Change the DS_URL element to point to your database instance that hosts Oracle Dynamic Services for the connection descriptor with the name "Direct," shown as follows:

   <DS_CONNECTION_DESCRIPTOR name="Direct">
      <annotation>
        -| For Nickname "Direct":                                  
         | These are specifications of the Direct Driver class     
        +| that will be used as well as the URL to be used with it 
      </annotation>
      <DS_DRIVER>oracle.ds.driver.DSDirectDriver</DS_DRIVER>
      <DS_URL>jdbc:oracle:thin:@<your-host-name>:<your-port-number>:<your-SID></DS_URL>
   </DS_CONNECTION_DESCRIPTOR>
   
   

You can also have your own configuration file and point to it by running the command shown in Example 3-1 (the -c option and additional options are described later in this section).

Example 3-1 Configure the DSAdmin Utility

On UNIX systems:

<ORACLE_HOME>/ds/bin/dsadmin -c <your config file>

On Windows NT systems:

<ORACLE_HOME>\ds\bin\dsadmin.bat -c <your config file>

The configuration file conforms to the specifications of an XML document containing elements and values. The specific elements that you can configure in the file are described in Table 3-1.

Table 3-1 DSAdmin Utility Configuration Elements  

Element	Description
DS_ADMIN_CONFIG	The root element of the DSAdmin utility configuration document.
DS_CONNECTION_DESCRIPTORS	The connection descriptor section. Contains descriptions of the connection nickname, driver class specification, and associated URL.
DS_CONNECTION_DESCRIPTOR	The connection descriptor. Contains the name attribute describing the nickname for the connection that is used to open Dynamic Services connections to be used throughout the lifetime of the DSAdmin utility.
DS_DRIVER	The driver class name. This driver class will be loaded to set up a Dynamic Services connection to be used throughout the lifetime of the DSAdmin utility. The name depends on the nickname specified in DS_CONNECTION_DESCRIPTOR.
DS_URL	The name of the URL. This URL is used by the specified driver class to open a Dynamic Services connection. The value depends on the nickname specified in DS_CONNECTION_DESCRIPTOR. For each driver class name, there must be a corresponding URL, (for example, jdbc:oracle:oci8:@db for a Direct driver class name; http://host-name:8888/ds/DSServlet for a Servlet driver class name).
DEFAULT_SERVICE_REQUESTS	The default service requests section. Contains descriptions of the service ID and the default path to the XML request file used for a service in the DSAdmin utility.
DEFAULT_SERVICE_REQUEST	The default service request. Contains the service ID attribute describing the service ID.
DEF_XML	The default path to the XML request file that is used for a specific service corresponding to the given service ID.

In order to use the other drivers, such as HTTP, HTTPS, and JMS, you must complete the advanced installation options (see Chapter 4 for more information). When the Servlet driver is used, requests are sent using HTTP to a Java servlet that directly interacts with a Dynamic Services engine in the same way the Direct driver does. This means that the two drivers may not necessarily share the same execution engine. See Section 1.3.1 through Section 1.3.3 for more information.

3.1.3 Running the DSAdmin Utility

Run the DSAdmin utility by executing the command shown in Example 3-2.

Example 3-2 Run the DSAdmin Utility

On UNIX systems:
<ORACLE_HOME>/ds/bin/dsadmin

On Windows NT systems:
<ORACLE_HOME>\ds\bin\dsadmin

Following each prompt, enter the user name DSSYS, <DSSYS-password> (default is DSSYS), and 1 to select the DSConnection nickname named Direct.

The command-line options for running the DSAdmin utility are described in Table 3-2.

Table 3-2 DSAdmin Utility Command-Line Options  

Option	Description
-c <config file>	Allows the DSAdmin utility to load configuration files from any location.
-d	Checks whether all required jars (and appropriate version) are in the CLASSPATH.
-h	Displays help. Lists the DSAdmin utility command-line options.
-i <script file>	Allows actions to be scripted through this option. The DSAdmin utility interprets each command separately and displays the result in standard output.
-s	Executes the DSAdmin utility in silent mode. This option is used only in conjunction with a script file.
-u <username>/<password>@<nickname>	Allows a user name, password, and DSConnection nickname to be specified upon invoking the DSAdmin utility.

3.2 Registering a New Service

A Dynamic Services simple service package consists of the group of files shown in Figure 3-1, and is located in a local directory structure on your system.

Figure 3-1 Contents of a Simple Service Package

Text description of the illustration simpsvpk.gif

The MANIFEST file contains a pointer to the service descriptor file. The service descriptor file contains pointers within the appropriate XML tag definitions pointing to the following:

• Classification descriptor file
• Organization descriptor file
• One or more contact descriptor files
• Service request definition file
• Service response definition file

In addition, the service descriptor file specifies the service adaptors to be used (see Chapter 6 for more information about each of these files).

A compound service package invokes one or more other services and typically includes one additional file, a jar file, which contains all Java classes and property files needed by the compound service at execution time.

Simple and compound service packages to be used by Dynamic Services must be registered in the registry.

Registration is a two-step process:

1. Classify a service under the LDAP category specified in its descriptor.
2. Register the new service package.

The location of this information is in the service. Categories are organized into a Lightweight Directory Access Protocol (LDAP) hierarchical tree, and are therefore defined by a Distinguished Name (DN). Before registering a service package, you must be sure the category that it belongs to exists. If the category does not exist, it must be created.

The entire process of registering the sample service package, YahooPortfolio, is described, starting from category creation (see Section 3.2.1), to registering the service (see Section 3.2.2). You must complete instructions described in these two sections, then browse registered services described in Section 3.3, and finally execute a registered service Section 3.4. Successfully completing these sections is the test that your Dynamic Services installation and DSAdmin utility configuration is working properly.

See Section 3.2.1 and Section 3.2.2 for more detailed information on what these scripts do in creating a service package category and registering a service package.

3.2.1 Creating a New Service Package Category

Using a regular text editor, open the service descriptor file of the YahooPortfolio sample service package. The service package is stored in the following directory:

On UNIX systems:
<ORACLE_HOME>/ds/demo/services/YahooPortfolio 

On Windows NT systems:
<ORACLE_HOME>\ds/demo\services\YahooPortfolio 

As specified in the MANIFEST file, the location of the service descriptor file is relative to the service package in the following file:

On UNIX systems:
/www.yahoo.com/dServices/sd/portfolio/yahoo_pfl.xml
On Windows NT systems:
\www.yahoo.com\dServices\sd\portfolio\yahoo_pfl.xml

In the service descriptor file header, it is specified that the service category (classification) information is available in an additional XML file stored in the same directory under the file name of yahoo_pfl_classification.xml. When viewing this file, note that the following category information is specified for the YahooPortfolio service package:

cn=portfolio, cn=finance, cn=business 

Defined as a DN, this category information must be read in the following way: business is the parent category of finance, which is the parent category of portfolio. To create the needed category in the Dynamic Services engine, start the DSAdmin utility and navigate with the following steps:

1. Start the DSAdmin utility using the following command on UNIX:

   bin/dsadmin -u dssys/<dssys-password>@Direct
   
   

   Use the following command on Windows NT:

   bin\dsadmin -u dssys/<dssys-password>@Direct
   
   

   (The Direct driver is the only driver that allows registry manipulation.)

2. Enter Reg or R to enter the registry subshell (where registry-related operations are performed).
3. Enter Service or S to enter the service management subshell.

To create the set of categories required by the YahooPortfolio service package, issue the commands shown in Example 3-3.

Example 3-3 Create a Set of Categories Required by the Yahoo Service Package

AddCat cn=business
AddCat "cn=finance,cn=business"
AddCat "cn=portfolio, cn=finance, cn=business"

3.2.2 Registering a Service Package

Once the service package categories have been created, you can register a new service package from the same DSAdmin utility menu by issuing the command in the same subshell, as shown in Example 3-4.

Example 3-4 Register a Service Package

On UNIX systems:
Register <ORACLE_HOME>/ds/demo/services/YahooPortfolio

On Windows NT systems:
Register <ORACLE_HOME>\ds\demo\services\YahooPortfolio

The service package directory is specified as a parameter.

The service package can also be presented in a zip archive file and you would then enter the path to that file instead.

3.3 Browsing Registered Services

Once a service has been registered, you can browse the list of service IDs in the same registry subshell by entering Search (S) under the Registry Service menu using the DSAdmin utility. You then need to specify the way in which you want to search the services, by category, by keywords, or by interface. Then, you must specify the matching search pattern. Category-based searches require exact pattern matches because the supplied matching pattern must exist; otherwise, nothing is returned. Example 3-5 shows how to search a list of registered services by category where the matching pattern includes the service ID of the YahooPortfolio service package.

Example 3-5 Search a List of Registered Services by Category

Search CATEGORY "cn=portfolio, cn=finance, cn=business"

If a category that contains subcategories is specified, a list of the subcategories is also listed. For example, if the category on which to search is "cn=finance, cn=business", then a subcategory of "cn=portfolio, cn=finance, cn=business" is included in the result list. For example:

cn=business
      |
  cn=finance
        |
    cn=portfolio
          |
      urn:com.yahoo:

Keyword searches are based on keywords that are supplied in the service descriptor file. Wildcards are allowed. Thus, a keyword search with the pattern "*" returns a list of all the service IDs registered in the Dynamic Services engine as the following steps show.

1. Start the DSAdmin utility using the following command on UNIX:

   bin/dsadmin -u dssys/<dssys-password>@Direct
   
   

   Use the following command on Windows NT:

   bin\dsadmin -u dssys/<dssys-password>@Direct
   
   

2. Enter S to enter the Search subshell (where search-related operations are performed).
3. Enter 2 to select the keyword classification scheme.
4. Enter the wildcard character * (the asterisk) and press Return to begin the search, as Example 3-6 shows.

Example 3-6 Returning a List of Services Using the Wildcard "*" Search

        Search for services where KEYWORD="*"...DSREG.search: 2 - *...
DSREG.search: 2 - *... Done

        Search Result:

        Service IDs:
        ------------
        urn:com.cnnfn:finance.portfolio03
        urn:com.dsFailOver:finance.portfolio03
        urn:com.oanda:conversion.currency03
        urn:com.ual:travel.mileage
        urn:com.yahoo:finance.ipfl04
        urn:com.yahoo:finance.portfolio03

        SubCategories:
        --------------
Done

Finally, searches based on the service interface finds matches with services using the same named request and response schema as those delineated by the interface. The interface name is case-sensitive. For example, if you are searching among all registered services only for those that use the "PortfolioService" interface name, you would enter that search string as shown in Example 3-7.

Example 3-7 Search a List of Registered Services by Interface

        Search for services where INTERFACE="PortfolioService"...DSREG.search: 3
 - PortfolioService...
DSREG.search: 3 - PortfolioService... Done

        Search Result:

        Service IDs:
        ------------
        urn:com.cnnfn:finance.portfolio03
        urn:com.dsFailOver:finance.portfolio03
        urn:com.yahoo:finance.portfolio03

        SubCategories:
        --------------
Done

3.4 Executing a Registered Service

Once the service has been registered, you can execute it with the following commands:

• Enter Exit or X twice to return to the top-level shell. If you are starting the shell from the beginning, you can skip this step.
• Enter Exec or E to enter the Execution shell.
• Enter Synch or S to perform synchronous execution of a service.

The shell prompts you to choose a service ID from a list that was generated with a keyword search using "*" as the matching pattern. For synchronous execution, the final step is to choose the XML file that contains the request for that service as shown in Example 3-8. The shell waits until the service execution is complete and then, produces the response message.

Example 3-8 Execute a Registered Service

On UNIX systems:
Exec Synch urn:com.yahoo:finance.portfolio03 <ORACLE_
HOME>/ds/demo/services/YahooPortfolio/pfl_req_ex.xml

On Windows NT systems:
Exec Synch urn:com.yahoo:finance.portfolio03 <ORACLE_
HOME>\ds\demo\services\YahooPortfolio\pfl_req_ex.xml

- Sample Output -
.
.
.
EM.execute service: urn:com.yahoo:finance.portfolio03... Done.
Writing synchronous Response
<PortfolioResp xmlns="http://www.portfolio.org/Portfolio/Response" xmlns:xhtml="
http://www.w3.org/1999/xhtml">
   <Quote>
      <Symbol>ORCL</Symbol>
      <Time>1:53PM</Time>
      <Price>13.61</Price>
      <Change>-11.16%</Change>
      <Volume>48,135,000</Volume>
   </Quote>
   <Quote>
      <Symbol>AAPL</Symbol>
      <Time>1:53PM</Time>
      <Price>20.82</Price>
      <Change>-3.57%</Change>
      <Volume>4,500,100</Volume>
   </Quote>
</PortfolioResp>

DSAdminShell.Execution>

After successfully executing the YahooPortfolio service, you can begin developing your own services. See Chapter 6 for information about how to build a service.

To configure and use other deployment views of Dynamic Services, such as HTTP/HTTPS, PL/SQL, or HTTP/Java Messaging Services (JMS), or to set up LDAP as a central master registry, see the appropriate sections in Chapter 4. Chapter 4 also describes other advanced features, such as enabling persistent auditing, manually fine-tuning Dynamic Services properties, and installing the management console.