]> Service Starter ServiceDescriptor Starting a nonactivatable service Starting a nonactivatable server Reggie A service is created by a server and registered with lookup services. The server has a fairly standard format, usually varying only in small details: the actual service, its entry attributes, number of services, etc. The ServiceStarter class can help with some of this, and is used by Sun for its tools such as reggie In the chapter on configuration we looked at how a "meta-server" might be written that would get information from a configuration file describing a service and use that to build the service. In order to make a service available for use, a number of parameters must be set up. These include The service class and how to construct it The transport protocol (Jeri/JRMP) The proxy for the service The codebase for the proxy files The classpath for the local files A security policy to run the server for this service Entry/attribute information Unicast locators of lookup services Group to join on lookup services Service item ID Some of these belong to the service, some to its proxy, some to the containing server, while others are advertisement parameters for joining lookup services. Jini has an interface ServiceDescriptor to give a standard way of handling some of these. This class is in the com.sun.jini.start package. This package is not specified by Jini, and may change or even disappear in later versions of Jini. interface ServiceDescriptor { Object create(Configuration config); } This has a number of implementations NonActivatableServiceDescriptor SharedActivatableServiceDescriptor SharedActivationGroupDescriptor The first is useful for the most common situation described in this book, of a non-activatable service. The meat of the NonActivatableServiceDescriptor class is in its constructors: class NonActivatableServiceDescriptor { NonActivatableServiceDescriptor(String codebase, String policy, String classpath, String implClassName, String[] serverConfigArgs); NonActivatableServiceDescriptor(String codebase, String policy, String classpath, String implClassName, String[] serverConfigArgs, LifeCycle lifeCycle); } The codebase is a url(s) of a directory or jar file of the proxy classes on an HTTP server; policy is the filename of the policy for this service within the context of the policy existing for the server; classpath is the classpath for the service run by the server; serverConfigArgs is an array of configuration parameters (typically just a single file name); it is not yet clear what lifeCycle is, or how it is used. It is notable what the constructor does, and does not, describe. It describes the service's class and its classpath, that is, how to run it. It describes the environment for the proxy, but not how to create it. The constructor does not describe the entry information, the service id or the groups to which this service belongs. The parameters in the constructor for NonActivatableServiceDescriptor describe the service's runtime/deployment environment. They do not describe the service's advertisement environment. The NonActivatableServiceDescriptor class provides an implementation of the create() method. This is defined in the interface to return an Object but the class actually returns a com.sun.jini.start.NonActivatableServiceDescriptor.Created. This has no methods, just two public fields public class Created { public Object impl; public Object proxy; } From this one can extract the implementation and its proxy. There are further wrinkles in using NonActivatableServiceDescriptor. The implementation object must be constructed from its class. The constructor has two parameters: the string array serverConfigArgs, and a lifecycle object. At present it is not clear what role this object is expected to play, and it is sufficient to use a default value NoOpLifeCycle. In addition to creating the implementation object, the create() method must create a proxy object for the implementation in order to return a Created object. This is done by requiring the implementation to support one of the two interfaces ServiceProxyAccessor or ProxyAccessor and calling getServiceProxy() or getProxy() respectively on the implementation. That is, the service must include the method getServiceProxy() (or getProxy()) and within this method it will probably create the proxy (possibly using the configuration information). object and return it. Pseudo-code using this is codebase = ... policy = ... classpath = ... implClass = ... configArgs = ... create a NonActivatableServiceDescriptor call create() on this, returning "created" object impl = created.impl proxy = created.proxy while the service will have a constructor Service(String[] config, Lifecyle lc) { proxy = ... } and method getServiceProxy() { return proxy } The implementation must be Remote and must be able to create a proxy. In its constructor it is handed a configuration array, so this may as well be used to find an exporter to get the proxy. The class starter.FileClassifierStarterImpl inherits from rmi.FileClassifierImpl and adds ServiceProxyAccessor to the basic file classifier: A configuration file suitable for using Jeri with the above FileClassifierStarterImpl is resources/starter/file_classifier.config: The server to start this service needs to set various parameters for the ServiceDescriptor. The pseudocode above set these explicitly. However, since they describe the runtime and deployment environment, they are better set in another configuration file such as resources/starter/serviceDesc.config: This configuration file contains two sets of configurations: one for the ServiceDescription component and one for the AdvertDescription component (discussed shortly). The resources/starter/serviceDesc.config configuration file uses two jar files, starter.ServiceDescription-dl.jarfor the service codebase and starter.ServiceDescription-start.jar for the server's classpath. The contents of these files are The starter.ServiceDescription-dl.jar contains all the files that need to be downloaded to a client: common/MIMEType.class common/FileClassifier.class rmi/RemoteFileClassifier.class The starter.ServiceDescription-start.jar contains all the files that are needed for the server to create the service: common/FileClassifier.class common/MIMEType.class rmi/FileClassifierImpl.class rmi/RemoteFileClassifier.class starter/FileClassifierStarterImpl.class A server which picks up the values from this configuration file and creates the service and its proxy follows. The program essentially uses two parts: one to build the service using a ServiceDescriptor and its configuration entries, the other to advertise the service using JoinManager and its associated AdvertDescription configuration entries. (Although JoinManager has a constructor which will take a configuration, this does not support any of the entries we specified above.) This server may be run from a command line such as java starter.ServiceDescription resources/starter/serviceDesc.config using a classpath that includes starter.ServiceDescription To summarise what is going on here The service is started by running a service.ServiceDescription The classpath for service.ServiceDescription must include (for example) a jar file starter.ServiceDescription.jar that contains starter.ServiceDescription.class as well as the standard Jini classes service.ServiceDescription uses a configuration file such as serviceDesc.config which includes a description of the codebase, etc, which are suitable parameters for the constructor of a ServiceDescriptor The serviceDesc.config configuration also contains an advertisement description to register the service with lookup services When the service is started by ServiceDescriptor.create() it uses its own configuration file file_classifier.config which specifies the exporter The classpath used to start the service includes the files in the jar file starter.ServiceDescription-start.jar The codebase used by clients to download the service includes the jar file starter.ServiceDescription-dl.jar The ant file to build and run this is antBuildFiles/starter.ServiceDescription.xml The standard tools supplied by Sun such as reggie all use the ServiceDescription class. But instead of starting a service, they start a server. So in this case an application is needed to start the server, which in turn will start the service. Sun supply a class ServiceStarter in the com.sun.jini.start package. This package is not specified by Jini, and may change or even disappear in later versions of Jini. It has a public main() method, which will take command line arguments. A configuration can be given as a command line argument and will be searched for an array of ServiceDescriptor's. The search is in component com.sun.jini.start and the descriptors are labelled as serviceDescriptors. The create() method will be called on each descriptor to create a server. To use the ServiceStarter, you need to write a server and also a configuration file containing a ServiceDescriptor for that server. The server does not need to have a main() method, since the server is started by ServiceStarter, not the server itself. For example, we could use the FileClasifierServerConfig from the chapter on "Configuration". The configuration file for this server remains unaltered as The server itself need not be altered - its main() method is just not called. If it were being written from scratch, there would be no need to include this method. Repeating this from the "Configuration" chapter, What is new is a configuration file for ServiceStarter. This could be in resources/starter/start-transient-fileclassifier.config: The server is set running by java -jar start.jar ServiceStarter resources/start-transient-fileclassifier.config A typical descriptor for the reggie service might be String codebase = "http://192.168.1.13:8080/reggie-dl.jar"; String policy = "/usr/local/reggie/reggie.policy"; String classpath = "/usr/local/jini2_0/lib/reggie.jar"; String config = "/usr/local/reggie/transient-reggie.config"; ServiceDescriptor desc = new NonActivatableServiceDescriptor( codebase, policy, classpath, "com.sun.jini.reggie.TransientRegistrarImpl", new String[] {config}) We can now see what is going in when a standard Sun service such as reggie is started. A typical command line is java -Djava.security.policy=reggie/start.policy -jar \ start.jar start-transient-reggie.config The configuration file contains information required to start the reggie server, such as This particular configuration starts a TransientRegistrarImpl When the TransientRegistrarImpl begins, it uses a configuration file too. This was specified to be /usr/local/reggie/transient-reggie.config and contains A ServiceDescriptor allows a service to be created with given parameters. It can be used directly, or by using the Sun-supplied ServiceStarter. Sun use this to startup their own services such as reggie. These classes are in the com.sun.jini.start package, and as such are not guaranteed to be stable or even to exist in future versions of Jini. Alternatively, like JoinManager, they might migrate to the core Jini package in future. We have seen that using ServiceStarter for a server essentially involves no changes to the server or its service. What is the point of it, then? Typically, starting a service involves a combination of factors from a number of sources Some values may come from the environment, such as CLASSPATH Some values may be defined in Java properties, such as security policy Some values may be given as command line arguments The ServiceStarter allows all of these to be placed in a configuration, so that a single mechanism can be used. ©right;