13 M-Let, Bootstrap and Launcher Services

The m-let, bootstrap and launcher services enable a Java Dynamic Management agent to instantiate an m-bean from a remote .jar file.

M-Let Service

The management applet or m-let service enables an agent to obtain m-beans from a remote .jar file. The agent does this by loading an m-let text file, which specifies information on the m-beans to be obtained. The information on each m-bean is specified in a single instance of a tag, called the MLET tag. The location of the m-let text file is specified by a URL. When an m-let text file is loaded, an instance of each m-bean specified in the file is created. The operation of the m-let service is illustrated in FIGURE 13-1.

Using the m-let services involves:

Writing an m-let text file containing MLET tags that specify the m-beans you want the agent to obtain
Creating .jar files that contain the code of the m-beans and any other resources that the m-beans require (for example, other Java classes, or native libraries)
Creating an instance of the m-let service in the agent
Loading the m-let text file

FIGURE 13-1 Operation of the M-Let Service

The `MLET` Tag

The MLET tag specifies an m-bean to be obtained. The syntax of the MLET tag is similar to the syntax of the APPLET HTML tag.



`<MLET`
`CODE=class \| OBJECT=serfile`
`ARCHIVE="archivelist"`
`[CODEBASE=codebaseURL]`
`[NAME=mbeanname]`
`[PERSISTENT=true\|false]`
`[VERSION=version]`
`>`
`[paramlist]`
`</MLET>`

CODE=class

This attribute specifies the full Java class name, including package name, of the m-bean to be obtained. The compiled .class file of the m-bean must be contained in one of the .jar files specified by the ARCHIVE attribute. Either CODE or OBJECT must be present.

OBJECT=serfile

This attribute specifies the.ser file that contains a serialized representation of the m-bean to be obtained. This file must be contained in one of the .jar files specified by the ARCHIVE attribute. If the .jar file contains a directory hierarchy, specify the path of the file within this hierarchy. Otherwise a match will not be found. Either CODE or OBJECT must be present.

ARCHIVE="archivelist"

This mandatory attribute specifies one or more .jar files containing m-beans or other resources used by the m-bean to be obtained. One of the .jar files must contain the file specified by the CODE or OBJECT attribute. If archivelist contains more than one file:

Each file must be separated from the one that follows it by a comma (,).
archivelist must be enclosed in double quote marks ("").

All .jar files in archivelist must be stored in the directory specified by the code base URL.

CODEBASE=codebaseURL

This optional attribute specifies the code base URL of the m-bean to be obtained. It identifies the directory that contains the .jar files specified by the ARCHIVE attribute. Specify this attribute only if the .jar files are not in the same directory as the m-let text file. If this attribute is not specified, the base URL of the m-let text file is used.

Note - Multiple MLET tags with the same code base URL share the same instance of the MLetClassLoader class.

NAME=mbeanname

This optional attribute specifies the object name to be assigned to the m-bean instance when the m-let service registers it. If mbeanname starts with the colon character (:), the domain part of the object name is the domain of the agent. The m-let service invokes the getDomain() method of the Framework class to obtain this information.

PERSISTENT=true | false

This optional attribute specifies whether the m-bean instance will be persistent. If the attribute is true, the m-bean will be persistent. If the attribute is false the m-bean will not be persistent. If this attribute is omitted, the m-bean will not be persistent.

VERSION=version

This optional attribute specifies the version number of the m-bean and associated .jar files to be obtained. This version number can be used to specify that the .jar files are loaded from the server to update those stored locally in the cache the next time the m-let text file is loaded. The version parameter must be a one or more non-negative decimal integers each separated by a dot from the one that precedes it. For information on how to use version control with the m-let service, see "Caching and Version Control" on page 171.

paramlist

This optional attribute specifies a list of one or more parameters for the m-bean to be instantiated. This list is passed as a modification list to the initCmf method of the m-bean to be instantiated. Each parameter in paramlist corresponds to a modification in the modification list. Use the following syntax to specify each item in paramlist:


`<PARAM NAME=propertyName VALUE=value>`

where:

propertyName is the name of the property in the modification
value is the value in the modification

The m-let service passes all the values in the modification list as String objects. Make sure that the initCmf method of the m-bean includes the code required to cast each String object into an instance of the appropriate type. For example, if the property is an integer, you have to cast the String object passed by the m-let service into an int.

Example

CODE EXAMPLE 13-1 shows an example of an MLET tag in an m-let text file. In this example, the m-bean Example.class is present in the file example1.jar. The file example2.jar contains other resources required by the m-bean Example.class. The .jar files are stored in the directory specified by the URL http://www.foo.com/jars. The domain part of the object name to be assigned to the m-bean instance is the domain of the agent. The m-let service invokes the getDomain() method of the Framework class to obtain this information. The text example.instance=1 makes up the remainder of the object name. Version 1.0 of the m-bean Example.class is to be obtained.

<MLET

CODE=Example.class

ARCHIVE="example1.jar, example2.jar"

CODEBASE=http://www.foo.com/jars

NAME=:example.instance=1

PERSISTENT=true

VERSION=1.0

>

</MLET>

Adding the M-Let Service

Before using the m-let service, you must add it to an agent. To add the m-let service, create an instance of one of these classes:

com.sun.jaw.impl.agent.services.mlet.MLetSrv if you do not want to apply version control
com.sun.jaw.impl.agent.services.mlet.MLetCacheVersionSrv if you want to apply version control (see "Caching and Version Control" on page 171 for more information)

Only one instance of the m-let service is allowed in a Java Dynamic Management agent. If there is already an instance of one of the above classes in an agent, it is not permitted to create an instance of the other class in the same agent.

CODE EXAMPLE 13-2 shows how to add the m-let service without version control to an agent. For an example of how to add the m-let service with version control, refer to CODE EXAMPLE 13-8.

// Add the simple m-let service

//

String mletName = "com.sun.jaw.impl.agent.services.mlet.MLetSrv";

MLetSrv mletSrv = (MLetSrv) cmf.newObject(mletName, domain + ":" +

"com.sun.jaw.impl.agent.services.mlet.MLetSrvMO", null);

The m-let security mode is specified in the object name. The default setting is false, this allows the agent to download .jar files from any source. The object name of an m-let service that does not require .jar files to be signed is:


`domain:com.sun.jaw.impl.agent.services.mlet.MletSrvMO.secure=false`

To instantiate an m-let service that will only download .jar files from trusted sources, the secure setting must be true. The object name of an m-let service that will only download .jar files from trusted sources is:


`domain:com.sun.jaw.impl.agent.services.mlet.MletSrvMO.secure=true`

Loading an M-Let Text File

To load an m-let text file, an agent or manager application must invoke a load URL method of an instance of the m-let service. When the m-let text file is loaded, an instance of the m-bean specified in each MLET tag is created. By repeatedly invoking the load URL method, it is possible to populate a Java Dynamic Management agent while it is running. The m-let service provides methods for loading an m-let text file with or without error checking.

Loading and Error Checking an M-Let Text File

The m-let service provides different methods for loading a URL, depending on whether the method is to be invoked by an agent or a manager. Each of these methods has a different return value. To load an m-let text file with error checking, invoke one of these methods, depending on the type of application you are writing:


Application	Method	Returns
Agent	`performLocalLoadURL`	A vector of object references to the m-beans instantiated.
Manager	`performRemoteLoadURL`	A vector of m-let tags that define the m-beans instantiated.

By parsing the vector returned, it is possible to perform error checking when an m-let text file is loaded.

CODE EXAMPLE 13-3 shows code required to enable an agent to load an m-let text file.

Vector beans = mlet.performLocalLoadURL("http:/www.foo.com/jars/test.htm");


`defaultDomain:JavaClass.codebase=baseURL`

where:

defaultDomain is the domain associated with the framework.
JavaClass is the full Java class name, including the package prefix, of the class loader used to create the m-bean. This is defined as the Java variable ServiceName.MLETLOADER.
baseURL specifies the location of the code of the m-bean. It is either the base URL of the m-let text file specified in the call to one of the load URL methods of the m-let service, or is the value of the CODEBASE attribute specified in the MLET tag.

Specifying the Object Name of the M-Bean

When an m-bean specified in an MLET tag is instantiated, you can register it with the repository yourself or you can let the m-let service register the m-bean. The Java Dynamic Management Kit enables you to specify the object name of the m-bean in either of the following ways:

Using the NAME attribute of the MLET tag
Omitting the NAME attribute of the MLET tag

Use the NAME attribute of the MLET tag if an initCmf method is defined for the m-bean and you want the NAME attribute to be passed as the object name parameter. You can also use the NAME attribute of the MLET tag for an m-bean that does not have an initCmf method if you want the m-bean instance to be registered with the repository by the m-let service.

You can omit the NAME attribute of the MLET tag if an object name is specified in the initCmf method. If an object name is specified in the initCmf method, the m-bean will register with the repository using that object name. You can also omit the NAME attribute of the MLET tag for an m-bean that does not have an initCmf method if you do not want the m-bean instance to register with the repository.

Using the `NAME` Attribute of the `MLET` Tag

If you use the NAME attribute of the MLET tag to specify the object name of the m-bean instance, the instance is registered with this name. The method invoked to register the instance depends on how the m-bean is implemented:

If an initCmf method is defined for the m-bean, it is invoked to register the instance.
If an initCmf method is not defined for the m-bean, the addObject or addDBObject method of the Framework class is invoked to register the instance. The persistency of the m-bean is determined by the PERSISTENT attribute in the MLET tag.

Omitting the `NAME` Attribute of the `MLET` Tag

If you omit the NAME attribute of the MLET tag, the method invoked to register the instance and the supplier of the object name depends on the implementation of the m-bean:

If an initCmf method is defined for the m-bean, it is invoked to register the instance. The object name must be supplied by the initCmf method.
If an initCmf method is not defined for the m-bean, the instance will only be registered with the repository if the performLocalLoadURL method is invoked by the agent. After the performLocalLoadURL method is invoked, the agent must then invoke the addObject or addDBObject method of the Framework class to register the instance.

Instantiating an M-Bean From Another M-Bean

The m-let service enables you to use the initCmf method of an m-bean that it loads to instantiate other m-beans. To do this, add code to the initCmf method for:

Adding a named m-bean to the framework
Instantiating and registering an instance of the m-bean
Obtaining the object name of the m-let service class loader

This is shown in CODE EXAMPLE 13-7.

public void initCmf(Framework cmf, ObjectName name) throws

IllegalAccessException, ServiceNotFoundException,

InstanceAlreadyExistException {

// Add this m-bean under the control of the framework.

//

cmf.addObject(this, name);

// Instantiate and register an instance of the m-bean MyBean.

// NOTE:

// By adding the m-bean in this way to the framework,

// the initCmf method IS NOT called.

//

ObjectName mbNameA = new ObjectName(cmf.getDomain()+":MyBean.id=A");

MyBean mbA = new MyBean();

cmf.addObject(mbA, mbNameA);

// Retrieve the codebase of the MLetClassLoader that loaded this class,

// and compose the MLetClassLoader object name.

String codebase =

((MLetClassLoader)this.getClass().getClassLoader())

.getCodeBase().toString();

ObjectName mletloader = new

ObjectName(cmf.getDomain()+":"+ServiceName.MLETLOADER+"

.codebase="+codebase);

// Instantiate and register a new m-bean in the agent.

ObjectName mbNameB = new ObjectName(cmf.getDomain()+":MyBean.id=B");

MyBean mbB = (MyBean) cmf.newObject("MyBean", mbNameB, mletloader, null);

}

Instantiating and Running an M-Bean

If you want an m-bean which has been instantiated using the m-let service, to start automatically as soon as it is instantiated, ensure that the m-bean implements the java.lang.Runnable interface. When the m-let service instantiates the m-bean, it creates a new thread and invokes the run method of the m-bean.

Caching and Version Control

Applying version control to an m-bean enables the m-let service to reduce network traffic by not loading .jar files from a server unless it is necessary. When you apply version control, .jar files are stored locally in the cache. Unless the m-let text file specifies that new versions must be loaded from the server, .jar files are loaded from the cache. For more information, see "Version Control Mechanism" on page 173. If you do not apply version control to an m-bean, the .jar files are always loaded from the server when an m-let text file is loaded.

Applying Version Control

Applying version control to an m-bean loaded by the m-let service involves:

Specifying the VERSION attribute of the MLET tag
Creating an instance of the com.sun.jaw.impl.agent.services.mlet.MLetCacheVersionSrv class
Invoking a load URL method of the instance to load the m-let text file

Cache Directories

The directory in which cache files are stored by default depends on the environment:


Operating Environment	Directory
Solaris	`/var/opt/SUNWconn/jaw/mletcache`
Windows NT	`C:\Program Files\SUNWconn\jaw\var\mletcache`

To change the default cache directory, invoke the setCacheDirectory method of the m-let service instance. The setCacheDirectory method does not create the directory that you specify, the directory must already exist. CODE EXAMPLE 13-8 shows how to add the m-let service with version control and change the cache directory.

// Add the MLetCacheVersionSrv

//

String mletName = "com.sun.jaw.impl.agent.services.mlet.MLetCacheVersionSrv";

MLetCacheVersionSrv mletSrv = (MLetCacheVersionSrv)

cmf.newObject(mletName, domain + ":" +

"com.sun.jaw.impl.agent.services.mlet.MLetCacheVersionSrvMO", null);

// Set the directory for caching if you want.

mletSrv.setCacheDirectory("/home/foo");

The m-let security mode is specified in the object name. The default setting is false, this allows the agent to download .jar files from any source. The object name of an m-let service with version control that does not require .jar files to be signed is:


`domain:com.sun.jaw.impl.agent.services.mlet.MLetCacheVersionSrvMO.secure=false`

To instantiate an m-let service that will only download .jar files from trusted sources, the secure setting must be true. The object name of an m-let service with version control that will only download .jar files from trusted sources is:


`domain:com.sun.jaw.impl.agent.services.mlet.MLetCacheVersionSrvMO.secure=true`

Version Control Mechanism

When the m-let text file is loaded, the m-let service compares the version number specified in the MLET tag with the current version number of the m-bean, which is stored locally. If the version number specified in the MLET tag is greater than the current version number, the .jar files are loaded from the server to replace those stored locally in the cache. The current version number is updated to the value specified in the MLET tag. If the version number specified in the MLET tag is less than or equal to the current version number, the .jar files in the cache are used.

Implementing Your Own Version Control Mechanism

To implement your own version control mechanism, create a Java class that extends the com.sun.jaw.impl.agent.services.mlet.MLetCacheVersionSrv class. In your Java class, override the check method of the com.sun.jaw.impl.agent.services.mlet.MLetCacheVersionSrv class.

Bootstrap Service

The bootstrap service simplifies the distribution of new releases of an application (namely an agent or a manager) from a central server. It is a standalone Java program that enables you to load an application from a remote .jar file. To obtain a new version of an application, all you have to do is run the bootstrap service on the system that requires the application to be loaded and run. Information on the application is contained in an m-let text file. You specify the URL of the m-let text file when you run the bootstrap service.

Use of the `MLET` Tag in the Bootstrap Service

When you use the MLET tag with the bootstrap service, only a limited set of parameters is permitted, as shown in the following syntax statement:



`<MLET`
`CODE=applicationClassfile`
`ARCHIVE="archivelist"`
`[CODEBASE=codebaseURL]`
`>`
`</MLET>`

The attributes are:

CODE=applicationClassfile

This mandatory attribute specifies the full Java class name, including the package name, of the application to be instantiated. The compiled .class file of the application must be contained in one of the .jar files specified by the ARCHIVE attribute.

ARCHIVE="archivelist"

This mandatory attribute specifies one or more .jar files containing the application itself and m-beans or other Java classes to be used by the application to be instantiated. One of the .jar files must contain the file specified in the CODE parameter. If archivelist contains more than one file:

Each file must be separated from the one that follows it by a comma (,).
archivelist must be enclosed in double quote marks ("").

All .jar files in archivelist must be stored in the directory specified by the code base URL.

CODEBASE=codebaseURL

This optional attribute specifies the code base URL of the application to be instantiated. It identifies the directory that contains the .jar files specified by the ARCHIVE attribute. Specify this attribute only if the .jar files are not in the same directory as the m-let text file. If this attribute is not specified, the base URL of the m-let text file is used.

Loading an Application Using the Bootstrap Service

To be able to run the application after loading it from the remote server, the application itself needs to implement the java.lang.Runnable interface. The bootstrap service can then load and instantiate the class and invoke the run() method provided by the interface. In an agent, the run() method is responsible for instantiating the framework and adding the adaptors and services required by the agent being loaded.

If you are using the bootstrap service to load an agent that uses the supplied base agent, you have to modify the code of the supplied base agent so that it implements the java.lang.Runnable interface. The base agent provided with the Java Dynamic Management Kit does not implement the java.lang.Runnable interface.

Besides implementing the java.lang.Runnable interface, the application needs to set the framework class loader to the class loader that loaded the application.

CODE EXAMPLE 13-9 shows the code required by an agent, if it is to be loaded using the bootstrap service.

public void run() {

...

// Create an instance of Framework

Framework cmf = new Framework((MoRepSrvIf)rep,null);

// Set classloader for Framework

cmf.setClassLoader(this.getClass().getClassLoader());

...

}

CODE EXAMPLE 13-10 shows the code required by a client, if it is to be loaded using the bootstrap service.

public void run() {

...

// Create an instance of AdaptorClient.

AdaptorClient adaptor = new AdaptorClient();

// Set classloader for AdaptorClient.

adaptor.setClassLoader(this.getClass().getClassLoader());

...

}

Using the Bootstrap Service to Load the Java Dynamic Management Kit

It is possible to load the classes provided in the Java Dynamic Management Kit, contained in a .jar file, at the same time that you load and run an application. To load Java Dynamic Management Kit in this way, specify the .jar file containing Java Dynamic Management Kit as one of the .jar files in the MLET tag.

The following packages need to be installed in the local file systems of all machines that use the bootstrap service and the corresponding classes must be accessible through the CLASSPATH environment variable:

com.sun.jaw.impl.agent.services.bootstrap.*
com.sun.jaw.impl.agent.services.bootstrap.internal.*
com.sun.jaw.impl.common.DefaultPaths
com.sun.jaw.reference.common.Debug
com.sun.jaw.reference.common.LoaderRepository
com.sun.jaw.reference.agent.services.LibraryLoaderIf

If you want to use the bootstrap's built-in library loader mechanism the files contained in the following packages are also required:

com.sun.jaw.impl.common.Library
com.sun.jaw.impl.common.LibraryDefinition
com.sun.jaw.impl.common.NoSuchLibException
com.sun.jaw.reference.common.JawException

If you want to use the RMI adaptor, the files contained in the following packages are also required:

com.sun.jaw.impl.adaptor.rmi.*
com.sun.jaw.impl.adaptor.rmi.internal.*

Running the Bootstrap Service

To run the bootstrap service, type:


`% java com.sun.jaw.impl.agent.services.bootstrap.BootstrapSrv secure applicURL [local-libdir]`

Where secure is a flag that specifies whether the service is to be run in secure mode (true) or non-secure mode (false), applicURL specifies the URL location of the m-let text file containing the information for loading the application and local-libdir is an optional parameter that specifies the local directory for storing native libraries before they are loaded into memory.

Using the Library Loading Service

The m-let and bootstrap class loaders implement the LibraryLoaderIf interface to allow the loading of dynamic native libraries. The basic operation of the services is described in "Library Loaders" on page 142.

Default Temporary Library Directory

The m-let and bootstrap class loaders use a temporary directory to store the library files before they are loaded into memory. The default temporary library directory depends on the operating environment.


Operating Environment	Default temporary library directory
Solaris	`/tmp`
Windows NT	`C:\Program Files\SUNWconn\jaw\tmp`

Changing the Temporary Library Directory

If you want the m-let and bootstrap class loaders to use a temporary library directory other than the default, you can specify the new directory by invoking the setLibraryDirectory method.

CODE EXAMPLE 13-11 shows how to use the setLibraryDirectory method to change the temporary library directory. In this example, the m-let and bootstrap class loaders will store the library files in the /home/libs directory.

mletSrv.setLibraryDirectory("/home/libs");

Loading a Library From the Local File System

CODE EXAMPLE 13-12 shows an example hierarchy for the libraries on the agent host.

Library hierarchy in local file system of the agent host:

/usr/lib/libsocket.so

Local libraries are loaded by invoking the LibLoader.loadLibrary method. The LibLoader.loadLibrary method is invoked by a class that was loaded through the m-let or bootstrap class loaders. The LibLoader.loadLibrary method is described in "Including Native Code in an M-Bean" on page 143. CODE EXAMPLE 13-13 shows two methods of loading the same library.

LibLoader.loadLibrary(this.getClass(),"","socket");

// loads /usr/lib/libsocket.so

LibLoader.loadLibrary(this.getClass(),"","/usr/lib/libsocket.so");

// loads /usr/lib/libsocket.so

Loading a Library From a `.jar` File

CODE EXAMPLE 13-14 shows an example hierarchy for the libraries in a .jar file.

libs1/libA.so

libs2/libA.so

libs2/Solaris/sparc/2.x/lib/libB.so

libs2/WindowsNT/x86/4.0/lib/B.dll

Libraries are loaded from .jar files using the LibLoader.loadLibrary method. CODE EXAMPLE 13-15 shows code for loading two instances of the same library using the basename to differentiate between the two. CODE EXAMPLE 13-15 also shows code for loading libraries into two different operating environments.

LibLoader.loadLibrary(this.getClass(),"libs1","A");

// loads libs1/libA.so

LibLoader.loadLibrary(this.getClass(),"libs2","A");

// loads libs2/libA.so

LibLoader.loadLibrary(this.getClass(),"libs2","B");

// loads libs2/Solaris/sparc/2.x/lib/libB.so

// if the agent runs on Solaris

// loads libs2/WindowsNT/x86/4.0/lib/B.dll

// if the agent runs on Windows NT

LibLoader.loadLibrary(this.getClass(),"libs2",

"Solaris/sparc/2.x/lib/libB.so");

// loads libs2/Solaris/sparc/2.x/lib/libB.so

LibLoader.loadLibrary(this.getClass(),"libs2","WindowsNT/x86/4.0/lib/B.dll");

// loads libs2/WindowsNT/x86/4.0/lib/B.dll

Security Manager

The security manager supplied with the Java Dynamic Management Kit is programmed to accept incoming libraries. For further information, refer to "Security Manager" on page 145.

When running the m-let and bootstrap services in non-secure mode, you must use the security manager provided with the Java Dynamic Management Kit to be able to load native libraries.

When running the m-let and bootstrap services in secure mode, you must write a specific security manager that supports code signing and native library loading, as specified in "Code Signing" on page 145.

Code Signing

The m-let and bootstrap services support signed .jar files, enabling them to ensure that only classes from a trusted source are downloaded over a network. This involves:

Running the m-let and bootstrap services in secure mode
Signing the .jar files using the javakey security tool
Installing a specific security manager to ensure that only classes from a trusted source are allowed to be downloaded (see "Code Signing" on page 145 for further information)

Launcher Service

The launcher service enables all the Java Dynamic Management applications running on a single machine to share the same base agent. It also enables you to load new applications into a base agent that is already running. The launcher service uses the m-let service for loading the m-beans and other resources that make up an application.

By sharing a single base agent among all the Java Dynamic Management applications that run on a single machine, conflicts over port allocations are avoided. This is because only one process is responsible for port allocations.

Using the launcher service involves:

Creating a.jar file that contains the code of your application (namely, the m-beans and any other resources required by your application)
Creating an instance of the launcher service in the agent
Adding code to the agent for starting the launcher service
Writing an m-let text file for each application and putting it in the directory that the launcher service searches when it is started

Packaging of the Application Code

To use the launcher service, you have to create a .jar file containing all the code of your application. The launcher service does not impose any restrictions on where this file is located.

Adding the Launcher Service to an Agent

Before using the launcher service, you have to add it to an agent. Only one instance of the launcher service is allowed in a Java Dynamic Management agent. To add the launcher service, create an instance of the com.sun.jaw.impl.agent.services.mlet.LauncherSrv class.

CODE EXAMPLE 13-16 shows how to add the launcher service to an agent and register it with the repository.

//Set the name of the Java class to be used for the launcher service

launcherClassName = "com.sun.jaw.impl.agent.services.mlet.LauncherSrv";

...

//

// Add the launcher service and register it

//

String launcherName = domain +

":com.sun.jaw.impl.agent.services.mlet.LauncherSrvMO";

Debug.println("Adding " + launcherClassName +

" to CMF with name " + launcherName);

LauncherSrv launchSrv = (LauncherSrv)

cmf.newObject(launcherClassName, launcherName, null);

Adding Code for Starting the Launcher Service

To start the launcher service, an agent must invoke the performLaunch method of an instance of the launcher service, as shown in CODE EXAMPLE 13-17.

launchSrv.performLaunch();

Search Paths for `MLET` Text Files

Put the m-let text files used by the launcher service in the directory it searches when it is started. The launcher service requests the m-let service to load all the files it finds into the agent. A default search path is preset for the launcher service. If you want the launcher service to search in directories other than the defaults, you can specify the search path explicitly.

Default Search Path

The default search path depends on the operating environment:


Operating Environment	Directory
Solaris	`/etc/opt/SUNWconn/jaw/launch`
Windows NT	`C:\Program Files\SUNWconn\jaw\etc\launch`

Changing the Search Path

If you want the launcher service to search in directories other than the defaults, you can specify the search path by:

Specifying a path property in the object name you give to the service
Invoking the setPath method

CODE EXAMPLE 13-18 shows how to use the setPath method to change the search path. In this example, the launcher service will search for m-let text files in the /home/test/public_html/demo directory.

launchSrv.setPath("/home/test/public_html/demo");

To specify a path containing several directories, use the path separator for the operating environment in which your agent is running. To obtain the path separator, check the path.separator property.

Loading a Single M-Let Text File

To use the launcher service to load a single m-let text file, use the mletload command. To do this, type the command for your operating environment:

In a Solaris operating environment:

prompt% /opt/SUNWconn/bin/mletload mletfileURL
In a Windows NT operating environment:

C:\>"C:\Program Files\SUNWconn\jaw\bin\mletload" mletfileURL

`prompt% /opt/SUNWconn/bin/mletload mletfileURL`

where mletfileURL is the URL of the m-let text file that you want the launcher service to load. There are no restrictions on where this file is located.

Example

Two applications, represented by the m-beans A.class and B.class are to be installed on the same machine. To enable them to share the same base agent, the code of the base agent includes code for instantiating and starting the launcher service. The code of each application is packaged as follows:


Application	Code Base URL	JAR Files
`A.class`	`http://www.bar.com/jars/A`	`A1.jar`, `A2.jar`
`B.class`	`http://www.bar.com/jars/B`	`B1.jar`, `B2.jar`