javax.management.loading
Class MLet

java.lang.Object
  |
  +--java.lang.ClassLoader
        |
        +--java.security.SecureClassLoader
              |
              +--java.net.URLClassLoader
                    |
                    +--javax.management.loading.MLet

public class MLet

extends java.net.URLClassLoader

implements MLetMBean, MBeanRegistration, java.io.Externalizable

Allows you to instantiate and register one or several MBeans in the MBean server coming from a remote URL. M-let is a shortcut for management applet. The m-let service does this by loading an m-let text file, which specifies information on the MBeans to be obtained. The information on each MBean 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.

The MLET tag has the following syntax:
< MLET
CODE = class | OBJECT = serfile
ARCHIVE = "archiveList"
[CODEBASE = codebaseURL]
[NAME = mbeanname]
[VERSION = version]
>
[arglist]
< /MLET>

where:

CODE = class
This attribute specifies the full Java class name, including package name, of the MBean to be obtained. The compiled .class file of the MBean 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 MBean 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 MBeans or other resources used by the MBean 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 MBean 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.

NAME = mbeanname
This optional attribute specifies the object name to be assigned to the MBean 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.

VERSION = version
This optional attribute specifies the version number of the MBean 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. version must be a series of non-negative decimal integers each separated by a period from the one that precedes it.

arglist
This optional attribute specifies a list of one or more parameters for the MBean to be instantiated. This list describes the parameters to be passed the MBean's constructor. Use the following syntax to specify each item in arglist:

< ARG TYPE=argumentType VALUE=value>

where argumentType is the type of the argument that will be passed as parameter to the MBean's constructor.
The arguments' type in the argument list should be a Java primitive type or a Java basic type (java.lang.Boolean, java.lang.Byte, java.lang.Short, java.lang.Long, java.lang.Integer, java.lang.Float, java.lang.Double, java.lang.String).

When an m-let text file is loaded, an instance of each MBean specified in the file is created and registered. The m-let Service extends the java.net.URLClassLoader and can be used to load remote classes and jar files in the VM of the agent.

Note - The MLet class loader uses the DefaultLoaderRepository to load classes that could not be found in the loaded jar files.

Version:

1.17

Author:

Roberto Longobardi

See Also:

Serialized Form

Constructor Summary

MLet()
Constructs a new MLet using the default delegation parent ClassLoader.

MLet(java.net.URL[] urls)
Constructs a new MLet for the specified URLs using the default delegation parent ClassLoader.

MLet(java.net.URL[] urls, java.lang.ClassLoader parent)
Constructs a new MLet for the given URLs.

MLet(java.net.URL[] urls, java.lang.ClassLoader parent, java.net.URLStreamHandlerFactory factory)
Constructs a new MLet for the specified URLs, parent class loader, and URLStreamHandlerFactory.

Method Summary

void	addURL(java.lang.String url) Appends the specified URL to the list of URLs to search for classes and resources.
void	addURL(java.net.URL url) Appends the specified URL to the list of URLs to search for classes and resources.
protected java.lang.Class	findClass(java.lang.String name) This is the main method for class loaders that is being redefined.
protected java.lang.String	findLibrary(java.lang.String libname) Returns the absolute path name of a native library.
java.lang.String	getLibraryDirectory() Gets the current directory used by the library loader for storing native libraries before they are loaded into memory.
java.util.Set	getMBeansFromURL(java.lang.String url) Loads a text file containing MLET tags that define the MBeans to be added to the agent.
java.util.Set	getMBeansFromURL(java.net.URL url) Loads a text file containing MLET tags that define the MBeans to be added to the agent.
java.net.URL[]	getURLs() Returns the search path of URLs for loading classes and resources.
void	postDeregister() Allows the m-let to perform any operations needed after having been de-registered in the MBean server.
void	postRegister(java.lang.Boolean registrationDone) Allows the m-let to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void	preDeregister() Allows the m-let to perform any operations it needs before being de-registered by the MBean server.
ObjectName	preRegister(MBeanServer server, ObjectName name) Allows the m-let to perform any operations it needs before being registered in the MBean server.
void	readExternal(java.io.ObjectInput in) This method reads the object's contents during Object Serialization.
void	setLibraryDirectory(java.lang.String libdir) Sets the directory used by the library loader for storing native libraries before they are loaded into memory.
void	writeExternal(java.io.ObjectOutput out) This method saves the object's contents during Object Serialization.

Methods inherited from class java.net.URLClassLoader

definePackage, findResource, findResources, getPermissions, newInstance, newInstance

Methods inherited from class java.security.SecureClassLoader

defineClass

Methods inherited from class java.lang.ClassLoader

defineClass, defineClass, defineClass, definePackage, findLoadedClass, findSystemClass, getPackage, getPackages, getParent, getResource, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, loadClass, resolveClass, setSigners

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MLet

public MLet()

Constructs a new MLet using the default delegation parent ClassLoader.

MLet

public MLet(java.net.URL[] urls)

Constructs a new MLet for the specified URLs using the default delegation parent ClassLoader. The URLs will be searched in the order specified for classes and resources after first searching in the parent class loader.

Parameters:

urls - The URLs from which to load classes and resources.

MLet

public MLet(java.net.URL[] urls,
            java.lang.ClassLoader parent)

Constructs a new MLet for the given URLs. The URLs will be searched in the order specified for classes and resources after first searching in the specified parent class loader. The parent argument will be used as the parent class loader for delegation. The factory argument will be used as the stream handler factory to obtain protocol handlers when creating new URLs.

Parameters:

urls - The URLs from which to load classes and resources.

parent - The parent class loader for delegation.

MLet

public MLet(java.net.URL[] urls,
            java.lang.ClassLoader parent,
            java.net.URLStreamHandlerFactory factory)

Constructs a new MLet for the specified URLs, parent class loader, and URLStreamHandlerFactory. The parent argument will be used as the parent class loader for delegation. The factory argument will be used as the stream handler factory to obtain protocol handlers when creating new URLs.

Parameters:

urls - The URLs from which to load classes and resources.

parent - The parent class loader for delegation.

factory - The URLStreamHandlerFactory to use when creating URLs.

Method Detail

addURL

public void addURL(java.lang.String url)
            throws ServiceNotFoundException

Appends the specified URL to the list of URLs to search for classes and resources.

Specified by:

addURL in interface MLetMBean

Parameters:

url - the URL to be appended

Throws:

ServiceNotFoundException - The specified URL is malformed.

addURL

public void addURL(java.net.URL url)

Appends the specified URL to the list of URLs to search for classes and resources.

Specified by:

addURL in interface MLetMBean

Overrides:

addURL in class java.net.URLClassLoader

Parameters:

url - the URL to be appended

getURLs

public java.net.URL[] getURLs()

Returns the search path of URLs for loading classes and resources. This includes the original list of URLs specified to the constructor, along with any URLs subsequently appended by the addURL() method.

Specified by:

getURLs in interface MLetMBean

Overrides:

getURLs in class java.net.URLClassLoader

findClass

protected java.lang.Class findClass(java.lang.String name)
                             throws java.lang.ClassNotFoundException

This is the main method for class loaders that is being redefined.

Overrides:

findClass in class java.net.URLClassLoader

Parameters:

name - The name of the class.

Returns:

The resulting Class object.

Throws:

java.lang.ClassNotFoundException - The specified class could not be found.

findLibrary

protected java.lang.String findLibrary(java.lang.String libname)

Returns the absolute path name of a native library. The VM invokes this method to locate the native libraries that belong to classes loaded with this class loader. Libraries are searched in the JAR files using first just the native library name and if not found the native library name together with the architecture-specific path name (OSName/OSArch/OSVersion/lib/nativelibname), i.e. the library stat on Solaris SPARC 5.7 will be searched in the JAR file as:

1 libstat.so

2 SunOS/sparc/5.7/lib/libstat.so

the library stat on Windows NT 4.0 will be searched in the JAR file as:

1 stat.dll

2 WindowsNT/x86/4.0/lib/stat.dll

If this method returns null, i.e. the libraries were not found in any of the JAR files loaded with this class loader, the VM searches the library along the path specified as the java.library.path property. If the library is found inside one of the JAR files, it will be copied locally in the directory set by a previous call to setLibraryDirectory, provided that this call has been done and that we can write into it. If the library already exists in the specified directory, it will not be copied again.

Overrides:

findLibrary in class java.lang.ClassLoader

Parameters:

libname - The library name.

Returns:

The absolute path of the locally-stored native library, or null in the following cases: the library could not be found in any JAR file, the library directory has not been previously set or is not writable.

getLibraryDirectory

public java.lang.String getLibraryDirectory()

Gets the current directory used by the library loader for storing native libraries before they are loaded into memory.

Specified by:

getLibraryDirectory in interface MLetMBean

Returns:

The current directory used by the library loader.

setLibraryDirectory

public void setLibraryDirectory(java.lang.String libdir)

Sets the directory used by the library loader for storing native libraries before they are loaded into memory.

Specified by:

setLibraryDirectory in interface MLetMBean

Parameters:

libdir - The directory used by the library loader.

getMBeansFromURL

public java.util.Set getMBeansFromURL(java.lang.String url)
                               throws ServiceNotFoundException

Loads a text file containing MLET tags that define the MBeans to be added to the agent. The location of the text file is specified by a URL. The MBeans specified in the MLET file will be instantiated and registered by the MBeanServer.

Specified by:

getMBeansFromURL in interface MLetMBean

Parameters:

url - The URL of the text file to be loaded as String object.

Returns:

A set containing one entry per MLET tag in the m-let text file loaded. Each entry specifies either the ObjectInstance for the created MBean, or a throwable object (that is, an error or an exception) if the MBean could not be created.

Throws:

ServiceNotFoundException - One of the following errors has occurred: The m-let text file does not contain an MLET tag, the m-let text file is not found, a mandatory attribute of the MLET tag is not specified, the value of url is malformed.

getMBeansFromURL

public java.util.Set getMBeansFromURL(java.net.URL url)
                               throws ServiceNotFoundException

Loads a text file containing MLET tags that define the MBeans to be added to the agent. The location of the text file is specified by a URL. The MBeans specified in the MLET file will be instantiated and registered by the MBeanServer.

Specified by:

getMBeansFromURL in interface MLetMBean

Parameters:

url - The URL of the text file to be loaded as String object.

Returns:

A set containing one entry per MLET tag in the m-let text file loaded. Each entry specifies either the ObjectInstance for the created MBean, or a throwable object (that is, an error or an exception) if the MBean could not be created.

Throws:

ServiceNotFoundException - One of the following errors has occurred: The m-let text file does not contain an MLET tag, the m-let text file is not found, a mandatory attribute of the MLET tag is not specified, the value of url is malformed.

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)

Allows the m-let to perform any operations it needs before being registered in the MBean server. If the ObjectName is null, the m-let provides a default name for its registration :type=MLet

Specified by:

preRegister in interface MBeanRegistration

Parameters:

server - The MBean server in which the m-let will be registered.

name - The object name of the m-let.

Returns:

The name of the m-let registered.

Throws:

java.langException - This exception should be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postRegister

public void postRegister(java.lang.Boolean registrationDone)

Allows the m-let to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Specified by:

postRegister in interface MBeanRegistration

Parameters:

registrationDone - Indicates whether or not the m-let has been successfully registered in the MBean server. The value false means that either the registration phase has failed.

preDeregister

public void preDeregister()
                   throws java.lang.Exception

Allows the m-let to perform any operations it needs before being de-registered by the MBean server.

Specified by:

preDeregister in interface MBeanRegistration

Throws:

java.langException - - This exception should be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postDeregister

public void postDeregister()

Allows the m-let to perform any operations needed after having been de-registered in the MBean server.

Specified by:

postDeregister in interface MBeanRegistration

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException

This method reads the object's contents during Object Serialization.

Specified by:

readExternal in interface java.io.Externalizable

Parameters:

in - The serialization input stream.

Throws:

java.io.IOException - Signals that an I/O exception of some sort has occurred.

java.lang.ClassNotFoundException - The class for an object being restored cannot be found.

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException

This method saves the object's contents during Object Serialization.

Specified by:

writeExternal in interface java.io.Externalizable

Parameters:

out - - The serialization output stream.

Throws:

java.io.IOException - - Signals that an I/O exception of some sort has occurred.