Services

Overview

This section provides detailed information about the SMC service model, and describes the core SMC service functions you can use in your service implementations.

Common Services Model

The SMC service model defines how services are used by clients and the basic components of service implementation. A service consists of three major components: interface, implementation, and descriptor, as described below.

Service Interface

From the client's point of view, service is defined only by its public interfaces. A client should be able to retrieve a service handle by providing information on the public interface it is expecting, without knowing the specific service implementation details. For example, an SMC client may want to access a logging service in an environment where there may be many different implementations of logging services available. In this case, the client simply requests a service that implements some well-known logging interface.

Sample Code

Access a Log Service

SMC predefines a set of common service interfaces, including log, authorization, message, persistence and launch. Vendors can define their own public service interfaces and share between its clients and its implementations, as long as the service interface satisfies the following rules:

• Extends base interface Service; this interface serves the similiar purpose as java.rmi.Remote. The methods defined in its subclasses are considered public business functions.

• Each method must be public.

• Each method must declare java.rmi.RemoteException in its throws statements; this is required even if this interface is only accessed locally.

Sample Code

Service Interface Definition

Service Implementation

A service implementation in SMC must satisfy the following rules:

• Implements at least one service interface

• Implements interface ServiceProvider; the SMC SDK provides a convenient base class for service implementation, VService. Services can optionally override its methods to plug in their own logic.

• Has a public default constructor that takes no parameters. SMC will use this default constructor to instantiate this service.

Sample Code

Service Implementation

SMC services can be designed to run on client-side as well as on server-side. A server-side implementation basically acts as a Java RMI server object. Clients do not have a direct handle to the service object, and can only remotely access it through an automatically generated stub. A single instance of such a server-side service can handle all requests from different client processes. This is the default running mode for service implementation objects.

In some circumstances, it may be preferable to run a service directly in the client process/VM. For example, when a client running inside a firewall tries to access a news service. If the news service can be downloaded to the client VM and poll an outside server for updates, then the client won't have to cope with firewall issues. Usually client-side services act as local agents that preprocess client requests and passes them on to the real backend on remote servers. This is very useful for third party integration. A log service proxy that represents a certain backend framework service, like WBEM, Jiro, or J2EE, can shield all the details of its backend framework dependency from its clients. Please see Third-Party Integration for more information on how a service proxy accesses different framework backends.

Besides the basic requirements of a service implementation, a client-side implementation class needs to implement the ServiceProxy interface. The SMC SDK provides a convenient base class, VServiceProxy, for vendors to extend.

Service Descriptor

Every service must have a deployment descriptor before it can be registered and maintained by SMC. A descriptor includes static information about the service component and is used by the SMC console to manage the lifecycle of its instances.

There are several attributes common to all services, such as:

• Daemon versus Non Daemon

• Service loading sequence

• Public interfaces (Required); an interface element represents a public interface class through which other components access current service. It should be the fully qualified interface class name that this service wants to publish.

• Implementation class name (Required); defines the implementation class to instantiate when a service is being loaded.

• Help file location (Optional); defines the base location and name of the JavaHelp help set for this component. See TBD for details on the policy established by SMC for packaging of JavaHelp bundles.

• SMC SDK API version (Required); defines the String version number of the SMC SDK API this component builds against. This must be in the form of : major[.minor]

• Singleton versus Multi-Instances (Required); defines if only one instance of the service should be instantiated to serve all clients, or whether a new instance of the service is needed for every client.

• Supported Management Scopes (Optional); defines the management scopes this service supports. Supported management scopes specifies which one or more of the following name services contents will be accessed and/or changed by this service:

  file | nis | nisplus | ldap | dns

  If not specified, file scope is assumed.

• Load dependency (optional); defines what other services should be running before this service can be loaded.

• Runtime parameters (optional); defines runtime attributes that effect service behavior. Unlike global registry properties, these runtime parameters can be different for each service.

An SMC service descriptor is defined as an XML-based file. Please refer to the "Deployment Descriptor DTD" at /usr/sadm/lib/smc/lib/dtds/viperbean_1_0.dtd for detailed syntax information.

Sample Code

Service Descriptor

Accessing other services

A service can access other services using getServiceByName() calls. Also important in this context are call delegation and accessing remote services, both of which are described below.

Call Delegation

Call delegation is when a service needs to call other services to fulfill a client request; for example, a service may need to pass on the client's identity to the services it calls. The service can specify its access to the other services in this mode by specifying this in the getServiceByName call, as:

Sample Code

Call Delegation

Be aware that the other service handle running in delegation mode only works in the current client's calling thread and its child threads. Services should not try to use delegation mode in any threads that are not triggered by current client call.

Accessing remote services

SMC does not currently support access to remote services running on different servers -- that is, different VMs on the same or different machines.

Bundled Common Services

The SMC environment bundles several common services in its release. Developers can find interface definitions for these services in the ServiceList class. The bundled services are briefly described below.

Logging

The SMC Log service logs messages into the default system log. When an SMC server runs on its own, the default log is syslog. When running with a WBEM server in the same VM (the SMC default), the default log is the WBEM log.

To enable localization, it is required that all messages logged are generated from resource bundles. The Log service accepts message keys and resource bundle base names as parameters, rather than directly accepting fixed strings. The real messages are later retrieved from the resource bundle by the log viewer.

Sample Code

Logging

Authorization

The Authorization service is used to decide whether an action towards some critical system resource is to be allowed or denied, based on the security policy currently in effect. Its public interface is defined as com.sun.management.viper.services.Authorization.

Different implementations use different security policies and different policy datastores. The implementation bundled with SMC is using the Role Based Access Control (rbac(5)) which was introduced since Solaris 8. See RBAC for details on how to install rights into its data store. Administrators can use one of the SMC tools, Users Tool, to manage the data store and grant rights to Solaris users.

In SMC, each action authorization is represented with a VPermission object. VPermission is defined by a properly scoped action name string, for example: solaris.admin.usermgr.read defines the read action in Solaris's User Manager tool.

Sample Code

Checking Authorizations

Messaging

SMC provides a facility to exchange messages between clients (Tools or Services). There are two types of messaging interfaces, one is MessagePullAgent and the second is MessagePushAgent. Once a user gets a handle to the Core Message service, he needs to get a handle to one of the message services (push or pull), initialize that service with either ToolInfraStructure or ServiceInfrastructure, create the named channel, subscribe to that channel and post messages to that channel. Clients need to implement the MessageListener interface to get notification from other subscribed users to receive messages.

The user has to make a decision to use either the push or pull message mechanism. Pull message is preferred if the client is running inside a firewall and needs to use a message service outside of firewall. The MessagePullAgent interface will contact the message service for updated list of messages.

Push message service will be notified by the message service through a callback mechanism so client will get the message immediately after message has been posted.

Sample Code

Messaging

Persistence

SMC provides a facility to store persistent data to SMC server. Tools and services can store/restore/delete persistent data by the PersistanceAgent utility class. To use the Persistance service:

1. Create the PersistenceAgent object with either ToolInfrastructure or ServiceInfrastructure

2. Store the serialized object with key (String) and version number (String); key is used for indexing to retrieve the object later, and version another piece of information associated with key for tools or services

3. Restore the data by key

Sample Code

Persistence

Launching

There are many non-SMC aware applications that provide management functionality administrators want to use. They can be run on the server and displayed on the client machine SMC is running on through the Launching Service. This service only supports X protocol, so appropriate permissions for the X display server are required to launch any application. You can grant display permission on the X display to the remote machine on which the application is running via the following command:

% xhost +<server>

Applications that are launched from this service fall into 3 different types:

Application Type	Description
CLI (TTY-based application)	The Launch service runs these type of applications inside a dtterm.
XAPP (X application)	Applications of this type are executed with the DISPLAY environment variable set to the same X server as the tool in which the given application is running.
HTML (URLs)	The first browser that can be found in the PATH environment set by the client tool will be launched to load the URL specified. See sdtwebclient(1) for the detail rules of which browser will be used.

To use the Launch service to run a command on the server and displayed back on the client:

1. Get a handle to launching service from infrastructure 'inf'

2. Create a LaunchInfo object with information about this request.

   If the application needs some environment variables been set, we can specify them in the environments parameter in the format of <key>=<value>, for example:

   String[] envs = {"PATH=/usr/bin:/sbin:/usr/ucb/bin", "EDITOR=/usr/local/bin/vim" };

   Environment variables PATH, DISPLAY, HOME, USER are always set by the service. But caller can override their values by explicitly specifying the environment parameter.

3. Launch the command; Launch service uses Authorization service to determine whether current user has enough rights to execute the command.

Sample Code

Launching

Packaging

Shared interfaces and classes

A service publishes its functionality through one or more public interfaces. The caller of this service needs those interface classes as well. So we encourage developers bundle all the public interfaces and classes they directly reference into an individual jar and registered as a shared library jar across tools and services. The real implemetation of those interfaces can be bundled and registered as a service jar.

Platform Dependent Libraries

Many service implementations need some native library support. You can bundle those native libraries (.so) in the service jar and identify them in the manifest file so they can be included in the library path.

Sample Code

Manifest for Native Library

Resource bundles

It is required that all services provide a resource bundle that contains the certain information under predefined message keys:

• BEANNAME -- Localized tool name
• DESCRIPTION -- Localized description of the tool
• VENDOR -- Localized vendor name
• VERSION -- Localized version number

Registration

If a service uses classes or resources from some other library jars, you need to register them first, for example:

# smcconf repository add library ALL <path>/mylibrary.jar

Here we are using the pseudo bean name ALL to represent all tools and services.

Next, you register a service jar to the server repository:

# smcconf repository add bean <path>/myservice.jar

You can check the repository to see the service is successfully imported by doing repository listing:

# smcconf repository list

See the Registration section for more details regarding the smcconf command.

Multiple Implementations of A Common Service

SMC repository supports multiple implementations of one service interface. You can register a syslog service and a WBEM log service that both implement interface com.sun.management.viper.services.Log.

Get Service By Name

When a service handle is requested through getServiceByName() call to the infrastructure, the repository scans the registered service list, starting from the most recent registered. The first one that implements the given interface and successfully loads itself (init() and start() methods are successfully called) is returned to the caller.

Configure services with Properties

A service can have several properties set to different values to customize the behavior of itself. The properties are kept in the repository with the service and can be set at registrar time or later on through smcconf.

Sample Code

Configure Service with Properties

Debugging

The SMC SDK has a debug utility class, com.sun.management.viper.util.Debug. This class acts like a delegate to the real implementation of the output manager interface, VDebug. All service containers will provide an implementation that plug into the class Debug. Services can always call the trace() method with proper severity without worrying about what level of detail should be really displayed or how they should be displayed.

Sample Code

Debugging

The default implementation of Debug in the SMC server can be configured with the environment variable SMC_DEBUG set to 0-2 to print out INFORMATION+, to ERROR+ level messages.

Third-Party Integration

Support for use of other services from third-party frameworks is not currently provided, and may be provided in a future release