org.codehaus.jam
Interface JamServiceParams


public interface JamServiceParams

Used to specify the parameters with which a JamService will be created.

Author:
Patrick Calahan <email: pcal-at-bea-dot-com>

Method Summary
 void addClassBuilder(JamClassBuilder cb)
          Adds a custom JamClassBuilder which will be consulted by the JamClassLoader when constructing representation of java types.
 void addClassLoader(java.lang.ClassLoader cl)
          DOCME
 void addClasspath(java.io.File classpathElement)
          Adds an elements to the JamService classpath.
 void addInitializer(MVisitor initializer)
           
 void addSourcepath(java.io.File sourcepathElement)
          Adds an elements to the JamService sourcepath.
 void addToolClasspath(java.io.File classpathElement)
          Adds an elements to the tool classpath.
 void excludeClass(java.lang.String qualifiedClassname)
          Names a specific class to be excluded in the JamService.
 void excludeClassFile(java.io.File[] sourcepath, java.io.File sourceFile)
          Excludes a single class File in the JamService in exactly the same way theat includeSourceFile() includes a source file.
 void excludeClassPattern(java.io.File[] classpath, java.lang.String pattern)
          Specifies a set of java class files to be excluded from the JamService.
 void excludeSourceFile(java.io.File[] sourcepath, java.io.File sourceFile)
          Excludes a single source File in the JamService in exactly the same way theat includeSourceFile() includes a source file.
 void excludeSourcePattern(java.io.File[] sourcepath, java.lang.String pattern)
          Specifies a set of java source files to be excluded in the JamService.
 void includeClass(java.lang.String qualifiedClassname)
          Names a specific class to be included in the JamService.
 void includeClassFile(java.io.File[] sourcepath, java.io.File sourceFile)
          Includes a single class File in the JamService in exactly the same way theat includeSourceFile() includes a source file.
 void includeClassPattern(java.io.File[] classpath, java.lang.String pattern)
          Specifies a set of java class files to be excluded in the JamService.
 void includeSourceFile(java.io.File file)
          Include a single java source file to be viewed.
 void includeSourceFile(java.io.File[] sourcepath, java.io.File sourceFile)
          Includes a single source File in the JamService.
 void includeSourcePattern(java.io.File[] sourcepath, java.lang.String pattern)
          Specifies a set of java source files to be included in the JamService.
 void set14WarningsEnabled(boolean b)
          Sets whether warnings should be displayed when running under JDK 1.4.
 void setCharacterEncoding(java.lang.String enc)
          Sets the encoding to use when reading java source files (e.g.
 void setJamLogger(JamLogger logger)
          Sets the JamLogger which will receive error and warning messages from JAM.
 void setJavadocTagParser(JavadocTagParser tp)
          Deprecated. The javadoc tag mapping mechanism in JAM has been deprecated. Instead, please use Annogen to do tag-to-175 mappings.
 void setLoggerWriter(java.io.PrintWriter out)
          Sets a PrintWriter to which the JamService implementation should log errors and debugging information.
 void setParentClassLoader(JamClassLoader loader)
          Sets the parent JamClassLoader of the service JamClassLoader.
 void setProperty(java.lang.String name, java.lang.String value)
          Sets an implementation-specific property.
 void setPropertyInitializer(MVisitor initializer)
           
 void setShowWarnings(boolean b)
          Enables or suppresses the logging of warning messages.
 void setUseSystemClasspath(boolean use)
          Specifies whether the JAM Service should load classes from the system classpath.
 void setVerbose(boolean v)
          Deprecated. use setVerbose(Class). This is the same as setVerbose(Object.class).
 void setVerbose(java.lang.Class c)
          Enables verbose debugging output from all instances of the given class.
 

Method Detail

includeSourceFile

void includeSourceFile(java.io.File file)

Include a single java source file to be viewed. Note that if your code is able to understand the file/package structure in which the source exists, you may get better performance by using the various include... methods which take a sourcepath parameter.


includeSourcePattern

void includeSourcePattern(java.io.File[] sourcepath,
                          java.lang.String pattern)
Specifies a set of java source files to be included in the JamService.

Note that calling this method implicitly includes the 'root' in the sourcepath (exactly as if addSourcepath(root) had been called).

Parameters:
sourcepath - Root directory/ies containing source files.
pattern - A relative file pattern (as described above under 'Include and Exclude Patterns').
Throws:
java.lang.IllegalArgumentException - if either argument is null.

excludeSourcePattern

void excludeSourcePattern(java.io.File[] sourcepath,
                          java.lang.String pattern)
Specifies a set of java source files to be excluded in the JamService. Note that calling this method implicitly includes the 'sourcepath' in the sourcepath (as in a call to addSourcepath(sourcepath)).

Parameters:
sourcepath - Root directory of the source files.
pattern - A relative file pattern (as described above under 'Include and Exclude Patterns').
Throws:
java.lang.IllegalArgumentException - if either argument is null.

includeClassPattern

void includeClassPattern(java.io.File[] classpath,
                         java.lang.String pattern)
Specifies a set of java class files to be excluded in the JamService. Note that calling this method implicitly includes the 'classpath' in the classpath (as in a call to addClasspath(classpath)).

Parameters:
classpath - Root directory of the source files.
pattern - A relative file pattern (as described above under 'Include and Exclude Patterns').
Throws:
java.lang.IllegalArgumentException - if either argument is null.

excludeClassPattern

void excludeClassPattern(java.io.File[] classpath,
                         java.lang.String pattern)
Specifies a set of java class files to be excluded from the JamService. Note that calling this method implicitly includes the 'classpath' in the classpath (as in a call to addClasspath(classpath)).

Parameters:
classpath - Root directory of the source files.
pattern - A relative file pattern (as described above under 'Include and Exclude Patterns').
Throws:
java.lang.IllegalArgumentException - if either argument is null.

includeSourceFile

void includeSourceFile(java.io.File[] sourcepath,
                       java.io.File sourceFile)

Includes a single source File in the JamService. The sourcepath parameter should identify the source sourcepath of the java source file; the sourceFile parameter must be under the sourcepath subtree.

For example, if a class "foo.bar.MyClass" is stored in a file "c:/myproject/src/foo/bar/MyClass.java", that class could be included in the service by calling

  includeSourceFile(new File("c:/myproject/src"),
                    new File("c:/myproject/src/foo/bar/MyClass.java"));
 

Note that this equivalent to calling

  includeSourceFiles(new File("c:/myproject/src"),"foo/bar/MyClass.java");
 

If you are calling this method and have more than one sourcepath directory, and do not readily know which is the correct sourcepath for a given source File, you can use the getRootForFile() utility method to determine the correct sourcepath to use.

Note that calling this method implicitly includes the 'sourcepath' in the sourcepath (exactly as if addSourcepath(sourcepath) had been called).

Parameters:
sourcepath - source sourcepath for the java source file
sourceFile - the java source file
Throws:
java.lang.IllegalArgumentException - if either argument is null or if sourcepath is not an ancestor of sourceFile in the file system.

excludeSourceFile

void excludeSourceFile(java.io.File[] sourcepath,
                       java.io.File sourceFile)

Excludes a single source File in the JamService in exactly the same way theat includeSourceFile() includes a source file.


includeClassFile

void includeClassFile(java.io.File[] sourcepath,
                      java.io.File sourceFile)

Includes a single class File in the JamService in exactly the same way theat includeSourceFile() includes a source file.


excludeClassFile

void excludeClassFile(java.io.File[] sourcepath,
                      java.io.File sourceFile)

Excludes a single class File in the JamService in exactly the same way theat includeSourceFile() includes a source file.


includeClass

void includeClass(java.lang.String qualifiedClassname)
Names a specific class to be included in the JamService. Note that this will return an 'unresolved' JClass unless a source or class file for the named class is available in the classpath or sourcepath.

Parameters:
qualifiedClassname - a full-qualified classname
Throws:
java.lang.IllegalArgumentException - if the argument is null or not a valid classname.

excludeClass

void excludeClass(java.lang.String qualifiedClassname)
Names a specific class to be excluded in the JamService. Note that this will have no affect if the named class cannot be found in the sourcepath or classpath.

Parameters:
qualifiedClassname - a full-qualified classname
Throws:
java.lang.IllegalArgumentException - if the argument is null or not a valid classname.

addSourcepath

void addSourcepath(java.io.File sourcepathElement)
Adds an elements to the JamService sourcepath. The service's JamClassLoader will search this path to find a .java file on which to base a JClass when requested to load a class that was not included in the service.


addClasspath

void addClasspath(java.io.File classpathElement)
Adds an elements to the JamService classpath. The service's JamClassLoader will search this path to find a .class file on which to base a JClass when requested to load a class that was not included in the service and for which no source could be found in the sourcepath.

Parameters:
classpathElement - elements of the classpath
Throws:
java.lang.IllegalArgumentException - if the argument is null

setLoggerWriter

void setLoggerWriter(java.io.PrintWriter out)
Sets a PrintWriter to which the JamService implementation should log errors and debugging information. If this is never set, all such output will be suppressed.

Parameters:
out - a PrintWriter to write to
Throws:
java.lang.IllegalArgumentException - if the argument is null

setJamLogger

void setJamLogger(JamLogger logger)
Sets the JamLogger which will receive error and warning messages from JAM.


setVerbose

void setVerbose(java.lang.Class c)

Enables verbose debugging output from all instances of the given class.


setShowWarnings

void setShowWarnings(boolean b)

Enables or suppresses the logging of warning messages. By default this is true.


setParentClassLoader

void setParentClassLoader(JamClassLoader loader)
Sets the parent JamClassLoader of the service JamClassLoader.

Parameters:
loader - the parent loaer
Throws:
java.lang.IllegalArgumentException - if the argument is null

addToolClasspath

void addToolClasspath(java.io.File classpathElement)

Adds an elements to the tool classpath. This is the classpath that will be used by the JamService implementation to find any libraries on which it depends. This classpath is distinct from the service classpath set by addClasspath() in that it has no affect on the input class set - it's only used for finding classes on which JAM itself depends.

Parameters:
classpathElement - elements of the classpath
Throws:
java.lang.IllegalArgumentException - if the argument is null

setPropertyInitializer

void setPropertyInitializer(MVisitor initializer)

addInitializer

void addInitializer(MVisitor initializer)

setUseSystemClasspath

void setUseSystemClasspath(boolean use)

Specifies whether the JAM Service should load classes from the system classpath. The default for this is true, and you shouldn't set it to false unless you really know what you are doing.


addClassBuilder

void addClassBuilder(JamClassBuilder cb)

Adds a custom JamClassBuilder which will be consulted by the JamClassLoader when constructing representation of java types. The given class builder will have priority over priority over JAM's default source- and reflection-based ClassBuilders. If this method id called more than once, the extra class builders will be prioritized in the order in which they were added.


addClassLoader

void addClassLoader(java.lang.ClassLoader cl)
DOCME


setProperty

void setProperty(java.lang.String name,
                 java.lang.String value)

Sets an implementation-specific property.


set14WarningsEnabled

void set14WarningsEnabled(boolean b)

Sets whether warnings should be displayed when running under JDK 1.4. The default is true.


setCharacterEncoding

void setCharacterEncoding(java.lang.String enc)
Sets the encoding to use when reading java source files (e.g. "UTF-8"). If this is not set, the vm's default encoding will be used.


setVerbose

void setVerbose(boolean v)
Deprecated. use setVerbose(Class). This is the same as setVerbose(Object.class).


setJavadocTagParser

void setJavadocTagParser(JavadocTagParser tp)
Deprecated. The javadoc tag mapping mechanism in JAM has been deprecated. Instead, please use Annogen to do tag-to-175 mappings.