com.gridsystems.launcher
Class Launcher

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      com.gridsystems.launcher.Launcher

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

public class Launcher
extends org.xml.sax.helpers.DefaultHandler

Allows the execution of a java application within a custom classloader.

This class allows two usage styles. It can be used as the main application class, and it will use an "XML descriptor" to construct the classloader and execute the class, or it can be used directly from code.

Descriptor Interface

When executed as a standalone application, this class will search for an XML descriptor file according to the following rules:

• The default file name is "launcher.xml". It can be modified through the "launcher.file" system property (-D flag in the command line)
• Firstly, it tries to construct a valid URL from the file name
• If is is not a valid URL, it checks if it corresponds to an existent file
• If no file is found, it will search a resource with the specified name

If a valid source is found, it will be read and parsed. This descriptor will contain the name of the class to launch, as well as the classpath to use in the custom classloader. The syntax of this descriptor is rather simple:

<!DOCTYPE launcher SYSTEM "http://www.gridsystems.com/dtds/launcher.dtd">
<launcher>
<application class="full.class.path" [method="XXX(default main)"]/>
<!-- Sets a system property with the given value -->
<property name="name" value="value"/> <!-- Sets a system property with the given relative path -->
<property name="name" path="path"/> </application>

<classpath>
<!-- Includes a single jar file -->
<include file="path"/>

<!-- Includes a class directory -->
<include dir="path"/>

<!-- Includes all jars in the specified path -->
<include jars="path" [recursive="true / false(default)"]/>

<!-- Includes WEB-INF/classes and WEB-INF/lib/*.jar -->
<include webapp="path"/>
</classpath>
</launcher>

The DTD URL is ficticious, and Launcher will use an internal DTD located at the same directory as the class in the jar (via class.getResource()).

All relative paths in the descriptor are considered relative to the "base directory". This base directory is determined as follows:

• If a system property called launcher.basedir is set, uses its value,
• If the property is not set, but the descriptor is a file, the file directory will be used,
• Otherwise, the current working directory will be used

Programmatic Interface

This class can also be used from within another program. The following is an example of how to use it: File tomcatHome = new File("[path to tomcat]");

Launcher launcher = new Launcher();
launcher.setClassName("[class name]");
launcher.setMethodName("[method name]");
launcher.setBaseDir(tomcatHome);
launcher.addWebapp("webapps/" + contextName);
launcher.addDir("common/classes");
launcher.addJars("common/lib");

try {
launcher.launch(args);
}
catch (LaunchException e) {
...
}

Classes in the classpath are searched for in order of addition, so the order of calls to addXXX methods is important. In the example above, classes will be searched for starting by [contextName]/WEB-INF/classes, and ending by the jars in [tomcatHome]/common/lib.

Version:

1.0

Author:

Rodrigo Ruiz

Constructor Summary

Launcher()
Empty constructor.

Method Summary

void	addDir(java.lang.String path) Adds a single directory to the classpath.
void	addFile(java.lang.String path) Adds a single file to the classpath.
void	addJars(java.lang.String path, boolean recursive) Adds all jars in the specified directory to the classpath.
void	addUrl(java.lang.String surl) Adds a single URL to the classpath.
void	addUrl(java.net.URL url) Adds a single URL to the classpath.
void	addWar(java.lang.String path) Adds a war packed web application to the classpath.
void	addWebApp(java.lang.String path) Adds a web application to the classpath.
void	doInherit() Makes the generated classloader to be a child of the current context classloader.
void	endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)
void	error(org.xml.sax.SAXParseException e)
void	fatalError(org.xml.sax.SAXParseException e)
java.io.File	getBaseDir() Gets the base directory for all relative paths.
void	launch(java.lang.String[] args) Executes the configured class and method, passing it the specified arguments, into the built class loader.
void	loadProperties(java.lang.String path) Loads all properties from the specified file path and adds them as system properties.
static void	main(java.lang.String[] args) Starts the launcher in "stand-alone" mode.
org.xml.sax.InputSource	resolveEntity(java.lang.String publicId, java.lang.String systemId)
void	setBaseDir(java.io.File dir) Sets the base directory.
void	setClassName(java.lang.String className) Sets the name of the class to execute.
void	setMethodName(java.lang.String methodName) Sets the name of the method to execute.
void	startElement(java.lang.String ns, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)
void	warning(org.xml.sax.SAXParseException err)

Methods inherited from class org.xml.sax.helpers.DefaultHandler

characters, endDocument, endPrefixMapping, ignorableWhitespace, notationDecl, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startPrefixMapping, unparsedEntityDecl

Methods inherited from class java.lang.Object

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

Constructor Detail

Launcher

public Launcher()

Empty constructor.

Method Detail

launch

public void launch(java.lang.String[] args)
            throws LaunchException

Executes the configured class and method, passing it the specified arguments, into the built class loader. The method must have the following signature:

static public void [methodName](String[])

Parameters:

args - The arguments to pass to the method

Throws:

LaunchException - If an unhandled error is thrown during the execution

setClassName

public void setClassName(java.lang.String className)

Sets the name of the class to execute.

Parameters:

className - The fully qualified class name

setMethodName

public void setMethodName(java.lang.String methodName)

Sets the name of the method to execute. The method MUST have the following signature (or a compatible one):

static public void [methodName](String args[]) throws Exception

Parameters:

methodName - The name of the method to invoke

getBaseDir

public java.io.File getBaseDir()

Gets the base directory for all relative paths.

If not explicitly set, a default base directory will be selected according to the rules explained above.

Returns:

The base directory

setBaseDir

public void setBaseDir(java.io.File dir)

Sets the base directory. Only paths added after this change will be affected; already added paths will not be modified.

Parameters:

dir - The new base directory

doInherit

public void doInherit()

Makes the generated classloader to be a child of the current context classloader.

Needed to gain access to base classes in an embedded environment.

addDir

public void addDir(java.lang.String path)

Adds a single directory to the classpath.

Parameters:

path - A path to a directory containing .class files

addFile

public void addFile(java.lang.String path)

Adds a single file to the classpath. Currently, only .jar files are accepted.

Parameters:

path - A relative

addJars

public void addJars(java.lang.String path,
                    boolean recursive)

Adds all jars in the specified directory to the classpath.

The order of the jars in path is platform dependent, so applications should not rely on them being sorted by any specific criteria.

Parameters:

path - A path to a directory containing jar files

recursive - Whether the search will recurse into subdirectories or not

addUrl

public void addUrl(java.lang.String surl)
            throws org.xml.sax.SAXException

Adds a single URL to the classpath.

Parameters:

surl - The string with the URL to add

Throws:

org.xml.sax.SAXException - In case of a syntax error in the URL

addUrl

public void addUrl(java.net.URL url)

Adds a single URL to the classpath.

Parameters:

url - The URL to add

addWebApp

public void addWebApp(java.lang.String path)

Adds a web application to the classpath.

It is equivalent to:

launcher.addDir(path + "/WEB-INF/classes");
launcher.addJars(path + "/WEB-INF/lib", false);

Parameters:

path - The path to the web application context

addWar

public void addWar(java.lang.String path)

Adds a war packed web application to the classpath.

Parameters:

path - Path to the .war file

loadProperties

public void loadProperties(java.lang.String path)
                    throws java.io.IOException

Loads all properties from the specified file path and adds them as system properties.

Parameters:

path - The path to the .properties file

Throws:

java.io.IOException - In case of read error

main

public static void main(java.lang.String[] args)

Starts the launcher in "stand-alone" mode.

Parameters:

args - The the command line arguments

resolveEntity

public org.xml.sax.InputSource resolveEntity(java.lang.String publicId,
                                             java.lang.String systemId)
                                      throws org.xml.sax.SAXException

Specified by:

resolveEntity in interface org.xml.sax.EntityResolver

Overrides:

resolveEntity in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

endElement

public void endElement(java.lang.String namespaceURI,
                       java.lang.String localName,
                       java.lang.String qName)
                throws org.xml.sax.SAXException

Specified by:

endElement in interface org.xml.sax.ContentHandler

Overrides:

endElement in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

startElement

public void startElement(java.lang.String ns,
                         java.lang.String localName,
                         java.lang.String qName,
                         org.xml.sax.Attributes atts)
                  throws org.xml.sax.SAXException

Specified by:

startElement in interface org.xml.sax.ContentHandler

Overrides:

startElement in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

error

public void error(org.xml.sax.SAXParseException e)
           throws org.xml.sax.SAXException

Specified by:

error in interface org.xml.sax.ErrorHandler

Overrides:

error in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

fatalError

public void fatalError(org.xml.sax.SAXParseException e)
                throws org.xml.sax.SAXException

Specified by:

fatalError in interface org.xml.sax.ErrorHandler

Overrides:

fatalError in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

warning

public void warning(org.xml.sax.SAXParseException err)
             throws org.xml.sax.SAXException

Specified by:

warning in interface org.xml.sax.ErrorHandler

Overrides:

warning in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException