7
Service Administration

In the previous chapters, some service administrator tasks included how to use the DSAdmin utility to perform basic tasks such as registering a service, creating a new service consumer application identity, and how to test a service execution. Other basic tasks such as unregistering a service, adding service consumer application properties, and so forth can also be performed using the DSAdmin utility. In this chapter, a brief overview of other topics relevant to administrators is provided.

7.1 Managing Consumer Applications

Using the DSAdmin utility, you can manage service consumer applications with respect to the application profile registry. Managing service consumer applications includes these tasks:

• Add A: adds the named service consumer application to the application profile registry. This operation assumes that this service consumer application name is a database user, who has been granted the connect privilege to this schema, and has been granted the DSUSER_ROLE privilege. See Section 5.1.2 for more information.
• Remove R: removes the named service consumer application from the application profile registry. Removing a service consumer application from the application profile registry does not remove the database user associated with it; it removes only the named service consumer application from the application profile registry.
• Grant G: grants the named service consumer application the privilege to execute the named service. Only a user with administrative privilege can perform this operation.
• Revoke K: revokes the named service consumer application the privilege to execute the named service. All properties owned by the named service consumer application for the named service are removed. Only a user with administrative privilege can perform this operation.
• AddProp AP: adds a property name and property value for the named service to the named service consumer application profile. Only a user with administrative privilege can perform this operation.
• RemoveProp RP: removes the named property name and property value for the named service from the named service consumer application profile. Only a user with administrative privilege can perform this operation.
• GetProp GP: gets the named property and named property value of the named service belonging to the named service consumer application from the service consumer application profile registry.
• ListConsumers LC: lists all the currently registered consumer applications, the service IDs for which each service consumer application has execute privilege, and the properties of each service. Only a user with administrative privilege can perform this operation.
• ListServices LS: lists all service IDs for the named service consumer application to which it has been explicitly granted the privilege to access. Only a user with administrative privilege can perform this operation.
• ListProperties LP: lists all properties of the named service consumer application for the named service. Only a user with administrative privilege can perform this operation.

7.2 Managing Services

Using the DSAdmin utility, you can manage services with respect to the service registry. Managing services includes these tasks:

• Register R: registers a service in the service registry. See Section 3.2.2 for more information.
• Deregister D: unregisters a service from the service registry. Registered services can be unregistered using this command.
• Reregister RR: reregisters a service in the service registry. Previously registered services that have been unregistered, can be reregistered using this command.
• Lookup L: looks up a registered service in the service registry by service ID.
• Search S: searches the registered services in the service registry by category or keywords. See Section 3.3 for more information.
• AddCat AC: adds a service category to the service registry. See Section 3.2.1 for more information.
• RemoveCat RC: removes a service category from the service registry.

7.3 Service Response Caching

The Dynamic Services engine uses the Oracle database for caching the service responses. The caching policy for a given service is controlled through deployment parameters in the service descriptors. Before registering a service, the service administrator can review these parameters and modify them as needed. The caching parameters are defined in the SERVICE_HEADER, DEPLOYMENT, and CACHING elements in the service descriptor.

In this release, to change the caching parameters of a given service, you must unregister the service and register it again with the new parameter settings. The following information describes the caching parameters that are available:

• MAX_AGE: specifies the number of seconds the service response remains valid in the cache. After the specified amount of time elapses, the cached response is discarded. When the MAX_AGE value is specified to be zero or less, the service response is never cached.
• SESSION_PRIVATE: takes a Boolean value (TRUE or FALSE) to indicate whether cached responses for this service should be visible only within the current session, or if they should be visible to all executions. Table 7-1 shows an overview of the behavior of four possible service response cases.

  Table 7-1 Possible Service Response Cases When Using a SESSION_PRIVATE Parameter Setting

  Where the Service Is Executed	How the Service Response Cache Is Specified, Where the Response Is Stored, and to Whom It Is Accessible
  	The service response cache is specified as session private.	The service response cache is not specified as session private.
  Service is executed within a session	The response is stored in the cache and it is accessible only to service execution within that session.	The response is stored in the cache and it is accessible to all service executions.
  Service is not executed within a session	The response is not stored in the cache.	The response is stored in the cache and it is accessible to all service executions.

• USE_PROTOCOL: takes a Boolean value (TRUE or FALSE) to indicate if the expiration date of a service response should be set by what is specified through the communication protocol between the Dynamic Services engine and the remote service provider. If this parameter is true, the value of the MAX_AGE parameter described previously is ignored.

If the USE_PROTOCOL caching parameter is true, the supplied HTTP/HTTPS protocol adaptors check the Expired HTTP header to determine the expiration date of the response. The supplied JDBC protocol adaptor does not support caching.

7.4 Cache Cleanup

The cache can grow to be rather large. If caching is enabled, you may want to manually run the DS_CacheManager package procedure, deleteExpiredResponses, or start a DBMS_JOB package to periodically clean up the cache. A procedure is supplied within the DS_CacheManager package to start the DBMS_JOB package that performs the cache cleanup. This procedure is called startCleanupJob, and it takes a VARCHAR2 argument that specifies the interval between cleanup jobs.

7.5 Connecting Multiple Dynamic Services Engine Instances

A logical service engine can be deployed with multiple physical service engine instances running, all sharing the same central master registry. The system can then be tuned by adding additional service execution engines. The central registry will not become a bottleneck because of the heavy use of caches at the service execution engine.

No load-balancing or failover feature is available in the current release. Administrators should partition the requests based on workload pattern. For example, an administrator can direct all applications in a subnet to a service engine in the same subnet.

There is no automatic synchronizing between multiple service engines in this current release. Administrators should synchronize all engines with the central master registry after an update. Therefore, Oracle Corporation recommends that you schedule the updates in batch mode, during low-load hours.

By default, installing a Dynamic Services engine includes:

• A registry mirror in an Oracle database
• A central master registry in a Lightweight Directory Access Protocol (LDAP) directory, for example, Oracle Internet Directory (OID)

To install an additional Dynamic Services engine:

1. Install a Dynamic Services engine as usual, but do not install the LDAP directory again.
2. Configure the LDAP connection system properties.
3. Invoke the resync command to resynchronize the registry. Using the DSAdmin utility, you can navigate to this command by selecting Reg or R for registry operations, and then select Engine or E to manage engine instances.

The registry should be running. Administrators should direct some users to the new Dynamic Services engines.

To perform any updates:

1. Connect to a Dynamic Services engine and perform the update (or a set of updates).
2. Connect to all other Dynamic Services engines, and invoke the resync command as described previously in step 3 using the DSAdmin utility.

Again, Oracle Corporation recommends that you schedule the updates in batch mode, during low-load hours.

7.6 Additional Operations of the DSAdmin Utility

You can browse through the DSAdmin utility to find additional administrative tasks that may be useful to perform.

7.6.1 Using Script Files with the DSAdmin Utility

Script files can be used with the DSAdmin utility to facilitate the process of regression testing and batch processing. Example 7-1 shows the command line and option to use is as described in Section 3.1.

Example 7-1 Run the DSAdmin Utility Using the -i Option

On UNIX systems:
<ORACLE_HOME>/ds/bin/dsadmin -u dssys/<dssys-password> -i <script file name>

On Windows NT systems:
<ORACLE_HOME>\ds\bin\dsadmin -u dssys/<dssys-password> -i <script file name>

Comments are allowed in the script in the form of lines that begin with the two slash (//) characters. Every string token supplied in the script file is treated as a separate command, or as user input. Commands are usually single string tokens, whereas user input need not be. For example, a category string can contain spaces within it. To use a parameter with spaces, you must enclose the entire parameter between quotation marks. This is true whether the DSAdmin utility is being used interactively or with a script.