org.eclipse.hyades.probekit
Interface IProbeCompiler

public interface IProbeCompiler

This is the interface that probe compilers must implement. The Probe Compiler Factory will return one of these when asked. The decision of which one it returns depends on who extends the org.eclipse.hyades.probekit.compilerFactory extension point, and how. HOW TO USE PROBE COMPILERS: You instantiate one from the factory, and you feed it one or more resources of type org.eclipse.hyades.models.probekit.Probekit. Then you extract the artifacts necessary to use the probes: a string representing the Java source for the class containing the probe fragments, and a string representing the engine script that will instrument class files based on those probes. The class ProbekitException is used for all exceptions. It wraps all exceptions that can occur inside the compiler, including internal errors like NullPointerException. The exception text string tells what really happened. Use the ProbeCompiler class this way: 1. Create an instance Use default constructor or convenience constructors 2. Populate the instance by calling addIFile or the two-parameter addResource (all other adders are deprecated: they don't return the id of the added probe source, and they don't know where to hang markers to report errors) 3. Use getGeneratedSource() and getEngineScript() (in either order) to get the Java source and engine script text, respectively. You need to call setClassPrefix() to set the first part of the generated class name. Also, call setPackageName to put the generated classes in a package - otherwise they'll be in the default package. The class prefix normally comes from the file name, and the package name might come from anywhere. Of course file names might have characters in them that are not valid Java identifier characters. For consistency among users of Probekit, the utility function makeValidJavaIdentifier is provided in this.

Field Summary

static java.lang.String

PROBEKIT_PROBLEM_MARKER This string is the marker type string for Probekit markers (see IMarker).

Method Summary

void	addFile(java.lang.String file) Deprecated. use addIFile
java.lang.String	addIFile(org.eclipse.core.resources.IFile f) Add probekits that appear in the indicated IFile.
void	addProbekit(org.eclipse.hyades.models.internal.probekit.Probekit probekit) Deprecated. use addIFile
void	addResource(org.eclipse.emf.ecore.resource.Resource res) Deprecated. use addIFile
java.lang.String	addResource(org.eclipse.emf.ecore.resource.Resource res, org.eclipse.core.resources.IResource ires) Add probekits that appear in the indicated resource.
java.lang.String	getClassSuffix() Returns the suffix string that is added to the string from setClassPrefix() to form the class name.
java.lang.String	getEngineScript() Get the script that describes this probe set to the BCI engine.
java.lang.String	getGeneratedSource() Get the generated source.
java.lang.String	makeValidJavaIdentifier(java.lang.String arg) Method to turn any string into a valid Java class name prefix.
void	setClassPrefix(java.lang.String prefix) Sets the class prefix to use for generated probe classes.
void	setPackageName(java.lang.String pkg) Sets the package name to use for generated probe classes.
void	verify() Tests a probe set for correctness and consistency.

Field Detail

PROBEKIT_PROBLEM_MARKER

public static final java.lang.String PROBEKIT_PROBLEM_MARKER

This string is the marker type string for Probekit markers (see IMarker).

See Also:

Constant Field Values

Method Detail

setClassPrefix

public void setClassPrefix(java.lang.String prefix)
                    throws ProbekitException

Sets the class prefix to use for generated probe classes. They will be in a package determined by the probe compiler, but here the caller can set the class name prefix. You'll get classes called classPrefix_probe.

Throws:

ProbekitException

setPackageName

public void setPackageName(java.lang.String pkg)
                    throws ProbekitException

Sets the package name to use for generated probe classes. Must be a valid Java package name string, with dots as separators, like "com.sample.probes" One reason to put probes in a package is to put them into a package which is filtered by default from other kinds of observation.

Parameters:

pkg - the package name to use, in dotted form.

Throws:

ProbekitException - if the pkg argument is not a valid Java package name string.

getClassSuffix

public java.lang.String getClassSuffix()

Returns the suffix string that is added to the string from setClassPrefix() to form the class name. Callers have to know this so they can form the Java source file name.

Don't change the value of this string ("_probe") because it's something users of the static instrumentation system are likely to write into their automation scripts.

Returns:

the class name suffix

makeValidJavaIdentifier

public java.lang.String makeValidJavaIdentifier(java.lang.String arg)

Method to turn any string into a valid Java class name prefix. Characters which are inappropriate as Java class name characters (including leading characters which can't start Java class names) are replaced with _XXXX (where XXXX is the hex code for the character, using as many digits as necessary).

Note that the output, while valid for Java class names, is not unique or reversible: The output string "_201" can come from a single-letter input string with char value 0x201, or from a two-letter input string " 1" (space-one).

Parameters:

arg - the string to convert

Returns:

a converted form of the string which is a valid Java class name prefix

addProbekit

public void addProbekit(org.eclipse.hyades.models.internal.probekit.Probekit probekit)
                 throws ProbekitException

Deprecated. use addIFile

Add a probekit object to the list of probekits this compiler will compile.

Parameters:

probekit - the Probekit to add

Throws:

ProbekitException

addFile

public void addFile(java.lang.String file)
             throws ProbekitException

Deprecated. use addIFile

Load the named file as a resource and add probekit objects found at the top level to this Compiler.

Parameters:

file - the name of the file to load.

Throws:

ProbekitException

addResource

public void addResource(org.eclipse.emf.ecore.resource.Resource res)
                 throws ProbekitException

Deprecated. use addIFile

Add probekits that appear at the top level of a resource to the probekits this compiler will compile.

Parameters:

res - the Resource to scan for probekits.

Throws:

ProbekitException

addIFile

public java.lang.String addIFile(org.eclipse.core.resources.IFile f)
                          throws ProbekitException

Add probekits that appear in the indicated IFile. Use this in preference to other adders, so errors will be reported as markers on the proper resource. Opens the IFile as an EMF Resource and calls addResrouce(res, f).

Parameters:

f - the IFile to add to the Compiler.

Returns:

the "id" string for the added probe, or null if it does not specify one

Throws:

ProbekitException - for serious errors; uses markers for probe source errors etc.

addResource

public java.lang.String addResource(org.eclipse.emf.ecore.resource.Resource res,
                                    org.eclipse.core.resources.IResource ires)
                             throws ProbekitException

Add probekits that appear in the indicated resource. The first argument is an EMF resource; the second is

Parameters:

res - the EMF Resource containing a probekit

ires - the Eclipse IResource that this probekit source comes from. This is the resource that error markers will be attached to.

Returns:

the "id" string for the added probe, or null if it does not specify one

Throws:

ProbekitException - for serious errors; uses markers for probe source errors etc.

verify

public void verify()
            throws ProbekitException

Tests a probe set for correctness and consistency. Throws an exception if the probe set fails any tests. The tests tend to be for things that aren't already forbidden by the modeling.

Throws:

ProbekitException - if there is any inconsistency in the set. The exception string describes one or more problems encountered, separated by the host-specific newline separator. It's possible that not all problems will be reported - for instance, only one internal integrity failure for a given probe might get reported, even if it has more than one problem. This verification step permits the core implementation to have less internal consistency checking logic.

getGeneratedSource

public java.lang.String getGeneratedSource()
                                    throws ProbekitException

Get the generated source. If the source hasn't been generated yet, it will be. Internally calls verify() and can throw ProbekitException if there is a problem.

Returns:

the generated source as a string.

Throws:

ProbekitException

getEngineScript

public java.lang.String getEngineScript()
                                 throws ProbekitException

Get the script that describes this probe set to the BCI engine.

Returns:

the string form of the description data

Throws:

ProbekitException