org.jperdian.launcher
Class Launcher

java.lang.Object
  |
  +--org.jperdian.launcher.Launcher

public class Launcher
extends java.lang.Object

A Launcher represents a comfortable way to start an application whose classes have been scattered in miscellanous classpath locations. To avoid a long and confusing -classpath argument on the command line, the Launcher takes care of organizing the files to be included in the classpath and provides a organized structure. Ever wondered why you encountered a NoClassDefFoundError or ClassNotFoundException when you were sure that you included the JAR file in the classpath and found out that is actually was available but not included? The Launcher can be configured to load all files from a directory, so that every new file you copy into the directory you do not need to care about the classpath yourself.

A Launcher must be started with a preferences file. This file can either be passed a first parameter on the command line, or - if no argument is passed - a default file named launcher.prefs.xml located in the current application directory will be used.

A base configuration file might look like this:

 <?xml version="1.0" encoding="ISO-8859-1" ?>
 <launcher verbose="true" >
 
   <!--
     If the argument verbose is set to true on the document element,
     the launcher will write misc. comments to the console about the
     files included in the classpath and other information
   -->
 
 
   <!--
     Define the classpath entries which will be included
     by the launcher into the ClassLoader by which the main
     application class is loaded
   -->
   <classpath base=".">
 
     <!-- Include all JAR files from the given directory -->
     <libdirectory location="lib/" />
 
     <!-- Include a single JAR file at the specified location -->
     <lib location="/home/test.jar" />
 
     <!-- Include a single JAR file at a remote URL -->
     <lib url="http://localhost:8080/test/test.jar" />
 
   </classpath>


   <!--
     Define the application class to be instantiated, the entry method
     that is called, and the parameters passed to the application. The
     entry method must be static and accept a string array as parameter
   -->
   <application class="org.jperdian.test.TestMainClass" method="main">
     <argument value="firstargument" />
     <argument value="-x" />
     <argument value="anothervalue" />
   </appliation>
 
 
   <!-- 
     Define additional VM environment variables, which can be inspected
     during runtime using a System.getProperty call
   -->
   <vm>
     <property name="file.encoding" value="ISO-8859-1" />
   </vm>  

 </launcher>
 

If you need the complete path of the currently selected directory within the XML configuration file itself, you can use the special String ${launcherDirectory} which will be replaced by the fully qualified directory name.

Most of the settings in the XML configuration file are optional, so a very basic version might look like this:

 <?xml version="1.0" encoding="ISO-8859-1" ?>
 <launcher>
 
   <!--
     The classpath in this exmaple consists only of the sub-directory lib. 
     Note: Theoretically you could completely omit the classpath element, but
     then the classpath would be the system classpath and there would be
     no need to use the launcher at all.
   -->
   <classpath>
     <libdirectory location="lib/" />
   </classpath>

   <!--
     An application main class must always be given.
   -->
   <application class="org.jperdian.test.TestMainClass" />

 </launcher>
 

Version:
1.1
Author:
Christian Robert

Constructor Summary
Launcher(java.io.File configurationFile)
          Creates a new launcher
 
Method Summary
protected  java.lang.ClassLoader createClassLoader()
          Creates the launchers ClassLoader from which the application'S main class is loaded
 void execute()
          Executes the current launcher and starts the application
protected static java.io.File findXmlConfigurationFile(java.lang.String[] arguments)
          Gets the XML configuration file from which the preferences will be loaded
protected  java.lang.String getApplicationClassName()
          Gets the name of the the class to be used as application launcher class
protected  java.lang.String getApplicationMethodName()
          Sets the method to be called when launching the application.
protected  java.util.List getApplicationParameters()
          Gets the List of String values that should be passed to the application to be launched via it's main method
protected  java.util.List getClassPathEntries()
          Gets the List of URL objects representing the classpath entries to be added to the classpath
protected  org.w3c.dom.Document getConfigurationDocument()
          Gets the XML document from which the configuration is loaded
protected  java.util.Map getVirtualMachineProperties()
          Gets the Map in which the system properties to be set are stored
 void initialize()
          Initializes the current launcher from the information provided in the currently set XML source document
protected  void initializeApplication(org.w3c.dom.Element xmlElement)
          Initializes the applications runtime parameters
protected  void initializeClasspath(org.w3c.dom.Element xmlElement)
          Initializes the classpath to be used
protected  void initializeVM(org.w3c.dom.Element xmlElement)
          Initializes the Java VM system properties
protected  boolean isVerbose()
          Checks whether the current launcher is verbose and should print messages to the console
static void main(java.lang.String[] args)
           
protected  void setApplicationClassName(java.lang.String className)
          Sets the name of the the class to be used as application launcher class
protected  void setApplicationMethodName(java.lang.String methodName)
          Sets the method to be called when launching the application.
protected  void setConfigurationDocument(org.w3c.dom.Document document)
          Sets the XML document from which the configuration is loaded
protected  void setVerbose(boolean state)
          Sets whether the current launcher is verbose and should print messages to the console
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Launcher

public Launcher(java.io.File configurationFile)
         throws java.io.IOException
Creates a new launcher

Parameters:
configurationFile - the File from which to take the arguments and perform the launching operation
Throws:
java.io.IOException - thrown if the configuration data cannot be read from the file
Method Detail

main

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

findXmlConfigurationFile

protected static java.io.File findXmlConfigurationFile(java.lang.String[] arguments)
Gets the XML configuration file from which the preferences will be loaded

Parameters:
arguments - the arguments passed from the virtual machine. If the array is null or has a size of 0, the default file name will be selected (which is launcher.prefs.xml otherwise the file at the first index of the parameter array is selected

createClassLoader

protected java.lang.ClassLoader createClassLoader()
Creates the launchers ClassLoader from which the application'S main class is loaded


initialize

public void initialize()
                throws java.io.IOException
Initializes the current launcher from the information provided in the currently set XML source document

java.io.IOException

initializeClasspath

protected void initializeClasspath(org.w3c.dom.Element xmlElement)
                            throws java.io.IOException
Initializes the classpath to be used

java.io.IOException

initializeApplication

protected void initializeApplication(org.w3c.dom.Element xmlElement)
Initializes the applications runtime parameters


initializeVM

protected void initializeVM(org.w3c.dom.Element xmlElement)
Initializes the Java VM system properties


execute

public void execute()
             throws java.lang.Throwable
Executes the current launcher and starts the application

java.lang.Throwable

getClassPathEntries

protected java.util.List getClassPathEntries()
Gets the List of URL objects representing the classpath entries to be added to the classpath


getApplicationParameters

protected java.util.List getApplicationParameters()
Gets the List of String values that should be passed to the application to be launched via it's main method


getVirtualMachineProperties

protected java.util.Map getVirtualMachineProperties()
Gets the Map in which the system properties to be set are stored


setApplicationClassName

protected void setApplicationClassName(java.lang.String className)
Sets the name of the the class to be used as application launcher class


getApplicationClassName

protected java.lang.String getApplicationClassName()
Gets the name of the the class to be used as application launcher class


setApplicationMethodName

protected void setApplicationMethodName(java.lang.String methodName)
Sets the method to be called when launching the application. These method must be present within the class given and must accept a String array as parameter


getApplicationMethodName

protected java.lang.String getApplicationMethodName()
Sets the method to be called when launching the application. These method must be present within the class given and must accept a String array as parameter


setConfigurationDocument

protected void setConfigurationDocument(org.w3c.dom.Document document)
Sets the XML document from which the configuration is loaded


getConfigurationDocument

protected org.w3c.dom.Document getConfigurationDocument()
Gets the XML document from which the configuration is loaded


setVerbose

protected void setVerbose(boolean state)
Sets whether the current launcher is verbose and should print messages to the console


isVerbose

protected boolean isVerbose()
Checks whether the current launcher is verbose and should print messages to the console