Documentation

Installation

The only prerequisite is that a Java developer's kit version 1.4 or higher is installed on your system and that javac, the java compiler, can be found in the file search path (i.e. the PATH environment variable on a windows machine).

First, the .zip archive in the download section of the Factory homepage has to be downloaded and uncompressed using the path information in the archive. All files in the archive are placed in a folder factory which contains two subfolders: src and classes. src contains the source code for the Factory specific parts of the precompiler. classes contains all the classes that Factory requires to work.

The classes folder has to be added to the java class search path: either by modifying the CLASSPATH environment variable or, on a per-use basis, with the -classpath command line option of the java virtual machine java.

On a windows machine the class search path could be modified like this (e.g. in the autoexec.bat file):

set CLASSPATH=%CLASSPATH%;c:\programs\factory\classes

The classpath for a particular invokation of the java virtual machine could be set like this:

java -classpath c:\programs\factory\classes factory.Factory ...

Usage

Once the installation is done, you can start the Factory precompiler from the command line. The general syntax of a command line call to Factory is as follows:

java factory.Factory [options] <factory source file> [argument classes]

The parts in brackets [] are optional, the part in less than and greater than signs <> is a placeholder. In the following they are described in further detail.

The <factory source file> denotes the factory that should be used in this call to the Factory tool. This can either be a valid pathname or, alternatively, a reference to a factory that is part of some java package in the class path. First, Factory checks if is denotes a valid pathname, then it tries to find the factory in the class path.

References to factories in java packages are like those used for resources: A factory myFactory in the package directory of package my.package is referred to as my/package/myFactory. Note that a factory does always have the file suffix .factory; however, you can omit this suffix in both the pathname of and the java resource reference to a factory. Note that all the java classes used in a factory must be found in the class path.

Command Line Options

The following command line options are available:

-help

This prints the version of the tool and a short description of its usage onto the standard output stream.

-javad

This sets the destination directory for generated .java files. All the generated .java files will be written directly into or into subdirectories of this .java destination directory depending on the package of the class in the respective .java file. This works similar to the -d option of the javac java compiler: If the .java destination directory is set to mydir and the Factory tool generates a file MyClass.java containing a class in a package my.package, then MyClass.java will be written to directory mydir/my/package. If some of those directories do not exist, they will be created. The default setting for the .java destination directory is the current directory.

-classd

This sets the destination directory for compiled .class files. All the compiled .class files will be written directly into or into subdirectories of this .class destination directory depending on the package of the class that the .class file contains. This works similar to the -d option of the javac java compiler: If the .class destination directory is set to mydir and the Factory tool compiles a file MyClass.class of a class in a package my.package, then MyClass.class will be written to directory mydir/my/package. If some of those directories do not exist, they will be created. The default setting for the .class destination directory is the current directory.

-greenlist

This sets the file or the directory containing the "green list" file of permitted methods and fields. For details on the purpose and structure of this list, see section "The Green List". If the argument provided after -greenlist is a valid path to a file, Fcatory will try to parse the green list from that file. If the argument is a valid path to a directory, Factory will search that directory for a green list file named GreenList.txt. If the -greenlist option is omitted, the default green list in file GreenList.txt in the factory package directory is used.

-verbose

This prints out messages about what Factory is currently doing onto the standard output stream.

-showfactory

This tells factory to show a window with the AST of the parsed factory. It does only work, when an appropriate windowing system (e.g. Windows) is currently running.

-showgenerate

This tells factory to show a window with the AST of the generated java class. It does only work, when an appropriate windowing system (e.g. Windows) is currently running.

-debug

This prints out various information used for debugging purposes onto the standard output stream.

Example

On a system where factory is installed in c:\programs\factory the compilation of an unparameterized factory source file myFactory.factory which is located in directory c:\projects\my\factories could look like this:

java -classpath c:\programs\factory\classes c:\projects\my\factories\myFactory.factory

If we had a factory source file myFactory2.factory which requires two arbitrary classes as actual parameters and we want to use that factory on the classes myClass1 and myClass2 which are in package my.classes in directory c:\projects\my\classes, then we would have to name those two classes on the command line.

If, say, we also wanted the generated java sources to be written into a subdirectory, according to their package, of c:\projects\source and the generated class files into proper subdirectories of c:\projects, then a call to the precompiler could look like this:

java -classpath c:\programs\factory\classes;c:\projects
  factory.Factory -javad c:\projects\source -classd c:\projects
  my\factories\myFactory my.classes.myClass1 my.classes.myClass2