org.eclipse.actf.validation.javapp.launch
Class ValidationLauncher

java.lang.Object
  extended by org.eclipse.actf.validation.javapp.launch.ValidationLauncher
Direct Known Subclasses:
AspectJValidationLauncher

public abstract class ValidationLauncher
extends Object

a launcher used to launch and simultaneously validate Java rich-client applications. The primary purpose of this launcher is to form the command line that launches the AOP-based validation of a Java application. A Java application may be launched via either a main(String[]) method of a Java class or via an executable file, which is platform dependent. The sole criterion of the executable is that it must provide a way for this launcher to pass arguments to its underlying JVM.

Currently, ACTF supports AspectJ AOP.

Author:
Mike Squillace

Nested Class Summary
protected  class ValidationLauncher.Path
           
 
Field Summary
protected  ValidationLauncher.Path aopPath
           
protected  ValidationLauncher.Path bootClasspath
           
protected  ValidationLauncher.Path bootClasspath_a
           
protected  ValidationLauncher.Path bootClasspath_p
           
protected  ValidationLauncher.Path classpath
           
static String DISTINCT_JVM_KEY
          system property to indicate distinct JVM (i.e. running apart from Eclipse environment
static String EXTERNAL_JVM_DUMP
          system property indicating location of dump from launched JVM
static String JAVA_HOME_KEY
           
protected  IConfiguration valConfig
           
 
Constructor Summary
ValidationLauncher(String executableName)
          create a new launcher using the specified executable.
ValidationLauncher(String executableName, String aopFilename)
          create a validation launcher.
ValidationLauncher(String executableName, String aopFilename, String workingDir)
          create a validation launcher.
 
Method Summary
 void addJvmArgument(String swtch, String value)
          add an argument to be passed to the JVM.
 void addLaunchListener(ILaunchListener listener)
          add a LaunchListener to be notified when the start or completion of a launch takes place or when a launch has somehow measurably progressed.
 void addReportListener(IReportListener listener)
          add a ReportListener to be notified of report-related events
 void addSystemProperties(Map props)
          add all of the system properties contained in the map
 void addSystemProperty(String key, String value)
          add a system property to be added to the arguments to the JVM launched by this process.
 String[] allJvmArguments()
          returns all the JVM arguments held by this launcher.
protected  String[] allSystemProperties()
          get the registered system properties, each as a string prepared for the command line.
 void appendToClasspath(String path)
          append the given path to the formed classpath for the launcher.
protected  void configureResourceServer()
           
protected  void fireLaunchCompletedEvent()
           
protected  void fireLaunchInitiatedEvent()
           
protected  void fireLaunchProgressedEvent()
           
 String getClasspath()
          return the classpath
protected  String getExecutableName()
           
protected  String getExecutionArguments()
          return the execution arguments
protected  String getJavaPath()
          get the fully-qualified path to the java executable.
protected  String getJvmSubstitutionParameter()
          return the JVM substitution parameter
 Process getProcess()
          Return the process object that has been launched.
protected  String getSystemProperty(String key)
           
 String getWorkingDirectory()
          return the working directory for the process launched
protected  boolean isUsingJava14()
          return whether or not this launcher is using a JVM of version 1.4.2.
 void launch()
          called to launch the AOP-based validation of the Java application.
static int launchExternalProcess(String[] exec, File workingDir, String out, String err)
          launch an external OS process
static int launchExternalProcess(String[] exec, File workingDir, String out, String err, ValidationLauncher launcher)
          launch an external OS process
protected  void launchProcess()
          launches a process for running/validating the application.
 void prepareForLaunch()
          prepares for the launch by adding system properties used by ACTF and starting the ResourceServer.
 void prependToClasspath(String path)
          prepend the given path to the formed classpath for the launcher.
protected  void processSwtResources(ValidationLauncher.Path classPath, ValidationLauncher.Path libPath)
          process the SWT .jar and .dll files.
protected  String quoteString(String str)
          quote the given string
 void removeLaunchListener(ILaunchListener listener)
          remove the specified listener from the list of listeners to be notified when launch events take place.
 void removeReportListener(IReportListener listener)
          remove the specified listener from the list of listeners to be notified when report events take place.
 void setClasspath(String cp)
          set the classpath used by this launcher.
 void setExecutionArguments(String args)
          set the execution arguments for the application being launched/validated.
 void setJvmSubstitutionParameter(String jvmSub)
          set the JVM substitution parameter to be used by this launcher.
 void setProcess(Process p)
          Once get the process, set the process object to be the process that been launched.
 void setUsingJava14(boolean java14)
          set whether or not this launcher is using a JVM v. 1.4.2.
 void setWorkingDirectory(String dir)
          set the working directory.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

JAVA_HOME_KEY

public static final String JAVA_HOME_KEY
See Also:
Constant Field Values

DISTINCT_JVM_KEY

public static final String DISTINCT_JVM_KEY
system property to indicate distinct JVM (i.e. running apart from Eclipse environment

See Also:
Constant Field Values

EXTERNAL_JVM_DUMP

public static final String EXTERNAL_JVM_DUMP
system property indicating location of dump from launched JVM

See Also:
Constant Field Values

aopPath

protected ValidationLauncher.Path aopPath

bootClasspath_p

protected ValidationLauncher.Path bootClasspath_p

bootClasspath_a

protected ValidationLauncher.Path bootClasspath_a

bootClasspath

protected ValidationLauncher.Path bootClasspath

classpath

protected ValidationLauncher.Path classpath

valConfig

protected IConfiguration valConfig
Constructor Detail

ValidationLauncher

public ValidationLauncher(String executableName)
create a new launcher using the specified executable.

Parameters:
executableName - - name of executable
See Also:
ValidationLauncher(String, String)

ValidationLauncher

public ValidationLauncher(String executableName,
                          String aopFilename)
create a validation launcher. The format of the AOP file named by the filename will be AOP-platform dependent. The working directory will default to the current directory of the launched process.

Parameters:
executableName - - name of executable
aopFilename - - name of AOP file specifying aspects, pointcuts, and/or binding advice

ValidationLauncher

public ValidationLauncher(String executableName,
                          String aopFilename,
                          String workingDir)
create a validation launcher. The format of the AOP file will be AOP-platform dependent.

Parameters:
executableName - - name of executable
aopFilename - - AOP file containing bindings, aspects, pointcuts, etc.
workingDir - - working directory
See Also:
setWorkingDirectory(String)
Method Detail

setProcess

public void setProcess(Process p)
Once get the process, set the process object to be the process that been launched.

Parameters:
p - process

getProcess

public Process getProcess()
Return the process object that has been launched.

Returns:
process

configureResourceServer

protected void configureResourceServer()

addReportListener

public void addReportListener(IReportListener listener)
add a ReportListener to be notified of report-related events

Parameters:
listener - - listener to be called upon report event

removeReportListener

public void removeReportListener(IReportListener listener)
remove the specified listener from the list of listeners to be notified when report events take place.

Parameters:
listener - - listener to be removed

addLaunchListener

public void addLaunchListener(ILaunchListener listener)
add a LaunchListener to be notified when the start or completion of a launch takes place or when a launch has somehow measurably progressed.

Parameters:
listener - - listener to be called upon launch event

removeLaunchListener

public void removeLaunchListener(ILaunchListener listener)
remove the specified listener from the list of listeners to be notified when launch events take place.

Parameters:
listener - - listener to be removed

addJvmArgument

public void addJvmArgument(String swtch,
                           String value)
add an argument to be passed to the JVM. The switch will automatically be prepended with a hyphen (-) and added without any arguments if the value is null.

Note: The JVM arguments -classpath/-cp, -Xbootclasspath and its variants, and system properties should not be added in this way.

Parameters:
swtch - - JVM switch
value - - value of switch or null if switch is to occur on the command line without an argument
See Also:
addSystemProperty(String, String)

addSystemProperty

public void addSystemProperty(String key,
                              String value)
add a system property to be added to the arguments to the JVM launched by this process.

Parameters:
key -
value -

addSystemProperties

public void addSystemProperties(Map props)
add all of the system properties contained in the map

Parameters:
props - - system properties with keys and values of type java.lang.String

getWorkingDirectory

public String getWorkingDirectory()
return the working directory for the process launched

Returns:
working directory
See Also:
setWorkingDirectory(String)

setWorkingDirectory

public void setWorkingDirectory(String dir)
                         throws IllegalArgumentException
set the working directory. This directory is the working directory for the launched process.

Parameters:
dir - - working directory (may not be null)
Throws:
IllegalArgumentException - if specified directory already exists as a file or if the specified directory does not exist and cannot be created

getJvmSubstitutionParameter

protected String getJvmSubstitutionParameter()
return the JVM substitution parameter

Returns:
JVM substitution parameter
See Also:
setJvmSubstitutionParameter(String)

setJvmSubstitutionParameter

public void setJvmSubstitutionParameter(String jvmSub)
set the JVM substitution parameter to be used by this launcher. A JVM substitution parameter is used by launches in which executables with underlying JVMs (rather than Java classes) are being validated. This parameter is substituted by the arguments that ACTF must pass to the underlying JVM.

For example, if we are to validate the Eclipse workbench, we must pass arguments to the JVM launched by eclipse.exe on the Windows platform. The execution arguments for this launcher, then, must include:

-vmargs

so that ACTF knows where on the command line to place the JVM arguments. This argument may be left null for launchers launching Java classes.

Parameters:
jvmSub - - substitution parameter for this launcher

getExecutableName

protected String getExecutableName()

getExecutionArguments

protected String getExecutionArguments()
return the execution arguments

Returns:
execution arguments
See Also:
setExecutionArguments(String)

setExecutionArguments

public void setExecutionArguments(String args)
set the execution arguments for the application being launched/validated. If a JVM substitution parameter is provided and is non-null, then these arguments are taken as arguments to the executable being launched. For cases in which the JVM substitution parameter is null, it is assumed that a standard Java class is being launched and that these arguments are being passed to the main(String[]) method.

Parameters:
args - - execution arguments
See Also:
setJvmSubstitutionParameter(String)

getClasspath

public String getClasspath()
return the classpath

Returns:
classpath

setClasspath

public void setClasspath(String cp)
set the classpath used by this launcher. The Java process will be launched with the -cp switch followed by the value passed to this method and those prepended or appended to it.

The specified classpath must be a legitimate set of paths with the syntax specified of the underlying operating system.

Parameters:
cp - - classpath for JVM
See Also:
prependToClasspath(String), appendToClasspath(String)

prependToClasspath

public void prependToClasspath(String path)
prepend the given path to the formed classpath for the launcher. If no classpath has been specified via the setClasspath or appendToClasspath methods, a new classpath is formed.

Parameters:
path - - path to prepend
See Also:
setClasspath(String), appendToClasspath(String)

appendToClasspath

public void appendToClasspath(String path)
append the given path to the formed classpath for the launcher. If no classpath has been specified via the setClasspath or prependToClasspath methods, a new classpath is formed.

Parameters:
path - - path to append
See Also:
setClasspath(String), prependToClasspath(String)

isUsingJava14

protected boolean isUsingJava14()
return whether or not this launcher is using a JVM of version 1.4.2.

Returns:
true if JVM being launched by this process is 1.4.2, false otherwise
See Also:
setUsingJava14(boolean)

setUsingJava14

public void setUsingJava14(boolean java14)
set whether or not this launcher is using a JVM v. 1.4.2. When set to false (the default), the JVM being used is assumed to be version 1.5.0 or higher. In this case, the 'javaagent' command line option will be used to take advantage of the instrumentation capabilities of JDK 5.0 and higher whereas earlier versions must rely upon manipulating the system class loader or the bytecode of java.lang.ClassLoader to effect weaving of aspect code.

Parameters:
java14 - - set to true if JVM is version 1.4.2 only

launch

public void launch()
called to launch the AOP-based validation of the Java application. This method:


launchProcess

protected void launchProcess()
                      throws Exception
launches a process for running/validating the application. This method prepares the execution command, calls preLaunch(), and launches the JVM.

Throws:
Exception

prepareForLaunch

public void prepareForLaunch()
                      throws Exception
prepares for the launch by adding system properties used by ACTF and starting the ResourceServer.

Clients may overwrite, but should always call super.prepareForLaunch().

Throws:
Exception

fireLaunchInitiatedEvent

protected void fireLaunchInitiatedEvent()

fireLaunchCompletedEvent

protected void fireLaunchCompletedEvent()

fireLaunchProgressedEvent

protected void fireLaunchProgressedEvent()

getJavaPath

protected String getJavaPath()
get the fully-qualified path to the java executable. If no path for the JDK/JRE has been set, only the 'java' command is returned.

Returns:
fully-qualified path to java executable

getSystemProperty

protected String getSystemProperty(String key)

allSystemProperties

protected String[] allSystemProperties()
get the registered system properties, each as a string prepared for the command line. Each system property key will be prepended by the requisite '-D' switch and followed by an equals sign '='. The quoted value then follows. If a key has a value of null, it is not included in the returned string.

Returns:
array of system properties, each as it should appear on the command line

quoteString

protected String quoteString(String str)
quote the given string

Parameters:
str -
Returns:
""str""

processSwtResources

protected void processSwtResources(ValidationLauncher.Path classPath,
                                   ValidationLauncher.Path libPath)
                            throws IOException
process the SWT .jar and .dll files. This will vary depending upon the version of Eclipse being used:

Parameters:
classPath - - classpath to be modified
libPath - - library path to be modified
Throws:
IOException

allJvmArguments

public String[] allJvmArguments()
returns all the JVM arguments held by this launcher. JVM arguments will, in order, include:

Returns:
all JVM arguments

launchExternalProcess

public static int launchExternalProcess(String[] exec,
                                        File workingDir,
                                        String out,
                                        String err)
launch an external OS process

Parameters:
exec - - command line to be executed
workingDir - - working directory
out - - destination of output of process
err - - destination for error stream from process
Returns:
exit code of process

launchExternalProcess

public static int launchExternalProcess(String[] exec,
                                        File workingDir,
                                        String out,
                                        String err,
                                        ValidationLauncher launcher)
launch an external OS process

Parameters:
exec - - command line to be executed
workingDir - - working directory
out - - destination of output of process
err - - destination for error stream from process
launcher - - launcher launching process
Returns:
exit code of process