Jalopy 1.0b10

de.hunsicker.jalopy
Class Jalopy

java.lang.Object
  |
  +--de.hunsicker.jalopy.Jalopy

public final class Jalopy
extends Object

The bean-like interface to Jalopy.

Sample Usage

 // create a new Jalopy instance with the currently active code convention settings
 Jalopy jalopy = new Jalopy();

 File file = ...;

 // specify input and output target
 jalopy.setInput(file);
 jalopy.setOutput(file);

 // format and overwrite the given input file
 jalopy.format();

 if (jalopy.getState() == Jalopy.State.OK)
     System.out.println(file + " successfully formatted");
 else if (jalopy.getState() == Jalopy.State.WARN)
     System.out.println(file + " formatted with warnings");
 else if (jalopy.getState() == Jalopy.State.ERROR)
     System.out.println(file + " could not be formatted");

 // setup a destination directory
 File destination = ...;

 jalopy.setDestination(destination);
 jalopy.setInput(file);
 jalopy.setOutput(file);

 // format the given input file and write the output to the given destination,
 // the package structure will be retained automatically
 jalopy.format();

 ...
 

Thread safety

This class is thread-hostile, it is not safe for concurrent use by multiple threads even if all method invocations are surrounded by external synchronisation. You should rather create one instance of this class per thread.

Version:
$Revision: 1.10 $
Author:
Marco Hunsicker

Inner Class Summary
static class Jalopy.State
          Represents a Jalopy run state.
 
Constructor Summary
Jalopy()
          Creates a new Jalopy object.
 
Method Summary
static void checkCompatibility(String packageName)
          Checks whether the specification version of the given Plug-in is compatible with the Jalopy Plug-in API spec version.
 void cleanupBackupDirectory()
          Cleans up the backup directory.
 boolean format()
          Formats the (via setInput(File)) specified input source and writes the formatted result to the specified target.
 File getBackupDirectory()
          Returns the directory where file backups will be stored.
 String getProfileTimes()
          Returns a string with the elapsed times for the different profiling categories.
 JavaRecognizer getRecognizer()
          Returns the used Java recognizer.
 Jalopy.State getState()
          Returns the current state info.
static Version getVersion()
          Returns the version information.
 void inspect()
          Inspects the (via setInput(File)) specified input source for code convention violations and coding weaknesses.
 void inspect(JavaNode tree)
          Inspects the given Java AST for code convention violations and coding weaknesses.
 boolean isInspect()
          Determines wether the code inspector is enabled during formatting runs.
 JavaNode parse()
          Parses the (via setInput(File)) specified input source.
 void reset()
          Resets this instance.
 void setBackup(boolean backup)
          Sets whether to hold a backup copy of an input file.
 void setBackupDirectory(File directory)
          Sets the directory where backup files will be stored.
 void setBackupDirectory(String directory)
          Sets the directory where backup files will be stored.
 void setBackupLevel(int level)
          Sets the number of backups to hold.
static void setConvention(File file)
          Sets the code convention to be loaded from the given file (either a qualified file path or single file name).
static void setConvention(String location)
          Sets the code convention to be loaded from the given location string.
static void setConvention(URL url)
          Sets the code convention to be loaded from the given url.
 void setDestination(File destination)
          Sets the destination directory to create all formatting output into.
 void setEncoding(String encoding)
          Sets the encoding that controls how Jalopy interprets text files containing characters beyond the ASCII character set.
 void setFileFormat(FileFormat format)
          Sets the file format of the output stream.
 void setFileFormat(String format)
          Sets the file format of the output stream.
 void setForce(boolean force)
          Specifies whether all files should be formatted no matter what the state of a file is.
 void setHistoryMethod(History.Method method)
          Sets the history method to use.
 void setHistoryPolicy(History.Policy policy)
          Sets the history policy to use.
 void setInput(File input)
          Sets the input source to use.
 void setInput(InputStream input, String path)
          Sets the input source to use.
 void setInput(Reader input, String path)
          Sets the input source to use.
 void setInput(String input, String path)
          Sets the input source to use.
 void setInspect(boolean enabled)
          Enables or disables the code inspector during formatting runs.
 void setOutput(File output)
          Sets the output target to use.
 void setOutput(StringBuffer output)
          Sets the output target to use.
 void setOutput(Writer output)
          Sets the output target to use.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Jalopy

public Jalopy()
Creates a new Jalopy object.
Method Detail

setConvention

public static void setConvention(File file)
                          throws IOException
Sets the code convention to be loaded from the given file (either a qualified file path or single file name).
Parameters:
file - the code convention file.
Throws:
IOException - if no code convention could be loaded from the given file.

setConvention

public static void setConvention(URL url)
                          throws IOException
Sets the code convention to be loaded from the given url.
Parameters:
url - url.
Throws:
IOException - if no code convention could be loaded from the given url.

setConvention

public static void setConvention(String location)
                          throws IOException
Sets the code convention to be loaded from the given location string.
Parameters:
location - location. Either a local file pathname or a pointer to a distributed resource accessible via the HTTP protocol (that is starting with "http://" or "www.").
Throws:
IOException - if no code convention could be loaded from the given location.

setEncoding

public void setEncoding(String encoding)
Sets the encoding that controls how Jalopy interprets text files containing characters beyond the ASCII character set.
Parameters:
encoding - a valid encoding name. For a list of valid encoding names refer to Supported Encodings. Note that null is permitted and indicates the platform's default encoding.
Throws:
IllegalArgumentException - if an invalid encoding was specified.

setFileFormat

public void setFileFormat(FileFormat format)
Sets the file format of the output stream. The file format controls what end of line character is used for the output files.
Parameters:
format - file format to use.

setFileFormat

public void setFileFormat(String format)
Sets the file format of the output stream. The file format controls what end of line character is used for the output files.
Parameters:
format - string representation of the file format to use.
See Also:
FileFormat.valueOf(java.lang.String)

setForce

public void setForce(boolean force)
Specifies whether all files should be formatted no matter what the state of a file is.

Defaults to false, which means that a source file will be only formatted if it hasn't ever been formatted before or if it has been modified since the last time it was processed.

Parameters:
force - if true all files are always formatted.

setHistoryMethod

public void setHistoryMethod(History.Method method)
Sets the history method to use.
Parameters:
method - a history method.
Since:
1.0b9

setHistoryPolicy

public void setHistoryPolicy(History.Policy policy)
Sets the history policy to use.
Parameters:
policy - a history policy.

setInspect

public void setInspect(boolean enabled)
Enables or disables the code inspector during formatting runs. You can always perform inspection using inspect() methods.
Parameters:
enabled - if true the code inspector will be enabled.
Since:
1.0b8
See Also:
inspect(), inspect(JavaNode)

isInspect

public boolean isInspect()
Determines wether the code inspector is enabled during formatting runs.
Returns:
true if the code inspector is enabled.
Since:
1.0b8

getVersion

public static Version getVersion()
Returns the version information.
Returns:
the current version information.

setOutput

public void setOutput(Writer output)
Sets the output target to use.
Parameters:
output - writer to use as output target.

getProfileTimes

public String getProfileTimes()
Returns a string with the elapsed times for the different profiling categories. Purely a diagnostic method only useful during developing.
Returns:
string with rudimentary profiling information.

getRecognizer

public JavaRecognizer getRecognizer()
Returns the used Java recognizer.
Returns:
the recognizer that is used for the language processing.
Since:
1.0b9

getState

public Jalopy.State getState()
Returns the current state info.
Returns:
The current state.

checkCompatibility

public static void checkCompatibility(String packageName)
                               throws VersionMismatchException
Checks whether the specification version of the given Plug-in is compatible with the Jalopy Plug-in API spec version.
Parameters:
packageName - the package name of a Plug-in as specified in the Jar Manifest, e.g. "de.hunsicker.jalopy.plugin.ant".
Throws:
VersionMismatchException - if the Plug-in with the given package name is not compatible with the Plug-in API version of the Jalopy runtime.
Since:
1.0b8

setBackup

public void setBackup(boolean backup)
Sets whether to hold a backup copy of an input file. Defaults to true.

This switch only takes action if you specify the same file for both input and output.

Note that you can specify how many backups should be retained, in case you want a history. See setBackupLevel(int) for further information.

Parameters:
backup - if true the backup of an input file will not be deleted after the run.
See Also:
setBackupLevel(int), setInput(File), setOutput(File)

setBackupDirectory

public void setBackupDirectory(File directory)
Sets the directory where backup files will be stored.
Parameters:
directory - path to an existing directory.
Throws:
IllegalArgumentException - if the given file does not denote a valid directory.
See Also:
setBackup(boolean)

setBackupDirectory

public void setBackupDirectory(String directory)
Sets the directory where backup files will be stored. Invokes setBackupDirectory(File) with newFile(directory).
Parameters:
directory - path to an existing directory.
See Also:
setBackup(boolean), setBackupDirectory(java.io.File)

getBackupDirectory

public File getBackupDirectory()
Returns the directory where file backups will be stored.
Returns:
the backup directory.
See Also:
setBackup(boolean)

setBackupLevel

public void setBackupLevel(int level)
Sets the number of backups to hold. A value of 0 means to hold no backup at all (same as setBackup(false)). The default is 1.
Parameters:
level - number of backups to hold.
Throws:
IllegalArgumentException - if level < 0
See Also:
setBackup(boolean)

setDestination

public void setDestination(File destination)
Sets the destination directory to create all formatting output into. This setting then lasts until you either specify another directory or reset() was called (which results in deleting the destination, files are overwritten now on).

If the given destination does not exist, it will be created.

Only applies if a file output target was specified.

Parameters:
destination - destination directory.
Throws:
IllegalArgumentException - if destination is null or does not denote a directory.
RuntimeException - if the destination directory could not be created.
See Also:
setOutput(File)

setInput

public void setInput(String input,
                     String path)
Sets the input source to use.
Parameters:
input - string to use as input source.
path - path of the file that is to be processed.
Throws:
NullPointerException - if input == null or path == null

setInput

public void setInput(InputStream input,
                     String path)
Sets the input source to use.
Parameters:
input - stream to use as input source.
path - path of file that is to be processed.
Throws:
IllegalArgumentException - if path == null or if path does not denote a valid, i.e. existing file or the system input stream.

setInput

public void setInput(Reader input,
                     String path)
Sets the input source to use.
Parameters:
input - reader to use as input source.
path - path of file that is to be processed.
Throws:
IllegalArgumentException - if path == null or if path does not denote a valid, i.e. existing file.

setInput

public void setInput(File input)
              throws FileNotFoundException
Sets the input source to use.
Parameters:
input - file to use as input source.
Throws:
FileNotFoundException - if the specified source file does not exist.
See Also:
setInput(Reader, String), setInput(String, String)

setOutput

public void setOutput(File output)
Sets the output target to use.
Parameters:
output - file to use as output target.

setOutput

public void setOutput(StringBuffer output)
Sets the output target to use.
Parameters:
output - buffer to use as output target.

cleanupBackupDirectory

public void cleanupBackupDirectory()
Cleans up the backup directory. All empty directories will be deleted. Only takes affect if no backup copies should be kept.
Since:
1.0b9
See Also:
setBackup(boolean)

format

public boolean format()
Formats the (via setInput(File)) specified input source and writes the formatted result to the specified target.

Formatting a file means that parsing, inspecting and printing will be performed in sequence depending on the current state. Thus the parsing and/or inspection phase may be skipped.

It is safe to call this method multiple times after you've first constructed an instance: just set new input/output targets and go with it. But remember that this class is thread-hostile: accessing the class concurrently from multiple threads will lead to unsuspected results.

Returns:
true if any formatting was applied.
Throws:
IllegalStateException - if no input source has been specified.
See Also:
setInput(File), setOutput(File), parse(), inspect()

inspect

public void inspect()
Inspects the (via setInput(File)) specified input source for code convention violations and coding weaknesses. If no parsing was performed yet, the input source will be first parsed.
Since:
1.0b8
See Also:
setInput(File), parse()

inspect

public void inspect(JavaNode tree)
Inspects the given Java AST for code convention violations and coding weaknesses.
Parameters:
tree - root node of the Java AST that is to be inspected.
Throws:
NullPointerException - if tree == null
IllegalArgumentException - if tree is not the root node of a Java AST.
Since:
1.0b8
See Also:
parse()

parse

public JavaNode parse()
Parses the (via setInput(File)) specified input source. You should always check the state after parsing, to be sure the input source could be successfully parsed.
Returns:
The root node of the created Java AST. May or may not return null if the input source could not be successfully parsed (i.e. always use getState() to check for success).
Throws:
IllegalStateException - if no input source has been specified.
Since:
1.0b8
See Also:
setInput(File), getState()

reset

public void reset()
Resets this instance.

Note that this method is not meant to be invoked after every call of format(), but rather serves as a way to reset this instance to exactly the state directly after the object creation.


Jalopy 1.0b10

Submit a bug or feature.

For further information and documentation, visit the official Jalopy website.
This page generated: November 14 2002