Discover a service based upon its service capabilities and optionally service attributes. The Discovery Service provides a mechanism to locate discoverable platform services.

Discovery Service

Overview

The Discovery service's purpose is to enable one to find a service implementation based upon desired service capabilities and optionally service attributes. A previously discovered service may also be re-discovered using its discovery service ID.

Service capabilities are specified in terms of the Java interface(s) implemented by a service. One may also specify the service instance's class or a superclass, but its recommended that one discovers a service using just its interfaces. Discovery occurs without requiring the client to have any knowledge of the underlying lookup mechanism(s) that are being used. Abstracting the lookup mechanism(s) enables us to minimize client code changes should we later decide to use an alternative service implementation.

• Discovering a Service
  • based only upon its service type(s)
  • based upon its service type(s) and attribute(s)
  • using its service discovery ID
• Model
• How to Implement a Discoverable Service
• Examples

Discovering a Service

Services are discovered based upon their service capabilities which represent the Java classes the service is, extends, or interfaces it implements. Typically one will discover a service based upon its service interface, for example a com.sas.services.logging.LoggingServiceInterface. Code snippets are provided below to illustrate the three ways one may discover a service.

• Based upon its service capabilites
  • Based only upon service type(s)
  • Based upon service type(s) and attribute(s)
• A previously discovered service can be re-discovered using its service's discovery ID

Find a Service Based Upon Service Type(s)

This example illustrates how one finds a service based solely upon its service capabilities. In this example, we wish to locate a service that implements the LoggingServiceInterface.

// get default discovery service
DiscoveryServiceInterface discoveryService = DiscoveryService.defaultInstance();

// locate a logging service using the discovery service
LoggingServiceInterface loggingServiceIf = (LoggingServiceInterface)
   discoveryService.findService(
      new ServiceTemplate(new Class[] {
         com.sas.services.logging.LoggingServiceInterface.class}));

Find a Service Using its Discovery Service ID

This example illustrates how one initially discovers a service based upon its service capabilities and then later reacquires the same service using its service discovery ID.

// get default discovery service
DiscoveryServiceInterface discoveryService = DiscoveryService.defaultInstance();

// lookup a logging service using the discovery service
LoggingServiceInterface loggingService1 = (LoggingServiceInterface)
   discoveryService.findService(
      new ServiceTemplate(new Class[]
         {com.sas.services.logging.LoggingServiceInterface.class}));

// determine the service discovery ID which is part of an ancillary service
// discovery configuration available from the service's configuration.
//
// NOTE: ServiceConfigurationInterface.CONFIGURATION_SERVICE_DISCOVERY is
// the reserved lookup key used to obtain the service discovery configuration.

String serviceDiscoveryId = null;
final ServiceConfigurationInterface serviceConfig =
   loggingService1.getServiceConfiguration();
if (serviceConfig != null) {
   final ServiceConfigurationInterface serviceDiscoveryConfig =
      serviceConfig.getServiceConfiguration(
         ServiceConfigurationInterface.CONFIGURATION_SERVICE_DISCOVERY);
   if ((serviceDiscoveryConfig != null) &&
       (serviceDiscoveryConfig instanceof ServiceDiscoveryConfigurationInterface)) {
       serviceDiscoveryId = ((ServiceDiscoveryConfigurationInterface)
         serviceDiscoveryConfig).getDiscoveryId();
   }
}

// now if we wish to reacquire the same service at some later point,
// ask the discovery service to find it using its serviceDiscoveryId.

LoggingServiceInterface loggingService2 = (LoggingServiceInterface)
   discoveryService.findServiceUsingId(serviceDiscoveryId);

Find a Service Based Upon Service Capabilities and Attributes

An application may desire to find a service that not only satisfies a particular business interface, but also attributes which may be used to differentiate a service from other services satisfying the same interface. When a service is deployed, attributes are added to its service discovery configuration that enable one to locate it based upon the following considerations:

• accessibility to remote clients
• host on which a service was deployed
• JVM in which a service was deployed
• application's service deployment
• service's component
• name/value attributes which a user may have assocated to a service deployment, service deployment group, or service

Refer to the documentation for the ServiceTemplate class for code examples.

Using JMX to View Registered Services

One may inspect the services that are registered with the Discovery Service as well as their configured service templates using a JMX console if one has enabled JMX for SAS Foundation Services.

The following snapshot shows the services that are registered with the Discovery Service when viewed with the jManage JMX console.

The following snapshot shows a service template configuration for an Information Service when viewed with the jManage JMX console. One may discover this service using the service interface(s) and optionally attribute(s) defined in this template.

Model

The Discovery service employs a "Chain of Command" design pattern to find a service based upon a requested service template. This design pattern is explained in the table below.

How to Implement a Discoverable Service

Service implementations may be exposed via the Discovery Service if the following considerations are observed:

• Implement a Service
  1. Your service must implement one of the following two interfaces:
     • com.sas.services.ServiceInterface
     • com.sas.services.RemoteServiceInterface
     RemoteServiceInterface is the base service interface. Its methods declare that they throw RemoteException which is a requirement for remote interfaces. This interface must be used for a service implementation that is intended for use in a distributed environment. ServiceInterface extends RemoteServiceInterface. This interface is identical to its superinterface except that its methods do not throw RemoteExceptions. Use this interface if your service will only be used in a local JVM (i.e. no remote interfaces). The best way to satisfy this interface requirement is to have your service implementation extend either com.sas.services.AbstractService or com.sas.services.AbstractRemoteService (local and distributed versions respectively).
  2. Implement one or more Java interfaces that specify the methods that your service will support (i.e. the the "LoggingService" implements "LoggingServiceInterface"). These interfaces will define the capabilities of your service that you wish to expose to your consumer.
  3. If your service is to be used in a distributed deployment, it must serializable. Explicitly specify a serialVersionUID, so that you will have control over whether or not your service is backward compatible with previous versions.

     Note: Each serializable class should have an attribute that specifies its serial version UID. For example, use long serialVersionUID = 2153634929598531287L; for an interface or public static final long serialVersionUID = -1428994704601244397L; for a class.

     To generate a serial version UID, compile your .java file and then use the serialver.exe located in the JRE\bin directory to generate an ID.

     For example,
     

     C:\classes>set classpath=%classpath%anyJarFilesYourStuffUses.jar;
     C:\classes>serialver -show
     A "Serial Version Inspector" dialog will appear.
     Enter a qualified class name in the
     "Full Class Name" text field and then activate the "Show" button.
     Cut/paste the "Serial Version" into your code.
     

• Implement a Service Factory
  1. The com.sas.services.deployment.ServiceLoader will be used to instantiate and initialize your service. The ServiceLoader will invoke the the default constructor of the service factory specified in your service's deployment configuration. Your service factory must implement the com.sas.services.ServiceFactoryInterface which specifies one method:

     RemoteServiceInterface getService(
        final ServiceConfigurationInterface serviceConfiguration)
        throws ServiceException;
     

     A typical implementation will overload the getService() method to accept other types of initialization objects. Note that RemoteServiceInterface is the base service interface, so the service returned by this method may be either a local or distributable service. We have adopted a Java class naming convention of "XxxServiceFactory.java" where "Xxx" is the name of your service. For example, the service factory for "LoggingServiceInterface.java" would be "LoggingServiceFactory.java"
  2. The ServiceConfigurationInterface will provide your service with an initialization object derived from the service deployment configuration. The initialization object that the ServiceLoader will provide will be of type com.sas.services.ServiceInitializationObject whose getInitializationObject() method will return an object of type String representing the XML fragment containing your service's initialization data.
  3. Most of the current service implementations translate this XML initialization configuration into an initialization object that is ultimately used to initialize their service. This has the advantage of being able to use the same initialization code whether your service is being instantiated by the ServiceLoader which provides XML data or directly using your service initialization object (i.e. "com.sas.services.logging.LoggingServiceInitObject");

Examples

This section presents an example illustrating use of the Discovery Service.

Example: Service Lookup Using Local Discovery Service

This section first presents an example showing how to find a service using a local discovery service previously bootstrapped using the ServiceLoader. Service deployment using the ServiceLoader utility is discussed in the com.sas.services.deployment package's documentation.

import com.sas.services.discovery.DiscoveryService;
import com.sas.services.discovery.ServiceNotAvailableException;

...

   try {
      //
      // Discover a service implementation through its service
      // types, for example an LoggingServiceInterface...
      //
      final Class[] desiredServiceTypes = new Class[] {
         com.sas.services.logging.LoggingServiceInterface.class
      };

      //
      // DiscoveryService.defaultInstance() returns a local implementation
      // of the DiscoveryServiceInterface. The local discovery service may then
      // be used to find an object based upon its desired service capabilities.
      //
      // A ServiceNotAvailableException is thrown if the Discovery Service
      // can't find a service that satisfies the requested service capabilities.
      //
      final LoggingServiceInterface loggingService = (LoggingServiceInterface)
         DiscoveryService.defaultInstance().findService(
            new ServiceTemplate(desiredServiceTypes));

      //
      // Use the discovered Logging Service...
      //
      loggingService.debug("My debug message");
   }
   catch (ServiceNotAvailableException e) {
      // This exception will be thrown if you attempt to discover a
      // service that is not accessible by the Discovery Service
      System.out.println(e.getMessage());
   }

Example: Distributed Deployment and Service Lookup From Another Process

A sample application has been created to demonstrate use of the Discovery Service.

1. Start a process responsible for deploying a distributable implementation of Foundation Services
2. Start a process that will attempt to locate a remotely accessible Discovery Service, locate a service based upon desired service capabilities, and then use the remotely discovered service.

This sample employs the com.sas.services.deployment.ServiceLoader class. Refer to its main method for specifics.

//
// Startup a process that will deploy services belonging to the service
// deployment "ID Portal - distributed core services":
//
// This process may be exited by keying the Enter key in the console window.
//
// NOTE:
// -Dcom.sas.services.logging.configurationURL=<alternate log configuration>
// Omit this item to accept the log default. Refer to the Logging Service
// API for additional details.
//

C:\sample>java
-Djava.security.policy=C:/sample/policy
-Djava.rmi.server.codebase="
   file:///c:/jars/sas.svc.core.jar
   file:///c:/jars/sas.oma.joma.jar
   file:///c:/jars/sas.oma.joma.rmt.jar
   file:///c:/jars/sas.core.jar
   file:///c:/jars/sas.text.jar"
-Dlog4j.configuration=file:///C:/sample/log4j.config
-Djava.security.auth.policy=C:/sample/auth.policy
-Djava.security.auth.login.config=C:/sample/login.config
-Dcache.auth.policy=true
-Dcom.sas.services.logging.configurationURL=file:C:\sample\LoggingConfig.xml

com.sas.services.deployment.ServiceLoader

0
"ID Portal - distributed core services"
"file:///C:/sample/sas_service_deployment_export_idportal_2.xml"

//
// Startup a process that will bootstrap the local discovery service with
// remote discovery service(s) that have been previously deployed and
// available via an RMI naming lookup.
//
// Look for services that are in the "BIP Software Components" SoftwareComponent
// hierarchy that are associated with a deployment group named
// "Core Platform Services":
//
// This sample application will first initialize its local discovery service
// with remotely available discovery services. Upon completion of this bootstrap
// it will then attempt to discover a Logging Service which should be
// accessible via the remote discovery service.
//
// NOTE:
// -Dcom.sas.services.logging.configurationURL=<alternate log configuration>
// Omit this item to accept the log default. Refer to the Logging Service
// API for additional details.
//

C:\sample>java
-Djava.security.policy=C:/sample/policy
-Dlog4j.configuration=file:///C:/sample/log4j.config
-Djava.security.auth.policy=C:/sample/auth.policy
-Djava.security.auth.login.config=C:/sample/login.config
-Dcache.auth.policy=true
-Dcom.sas.services.logging.configurationURL=file:C:\sample\LoggingConfig.xml

com.sas.services.deployment.ServiceLoader

1
"ID Portal - distributed core services"
"file:///C:/sample/sas_service_deployment_export_idportal_2.xml"