xjavadoc
Class XJavaDoc

java.lang.Object
  extended byxjavadoc.XJavaDoc

public final class XJavaDoc
extends java.lang.Object

This class represents the entry-point for xjavadoc classes. Come here to get classes and packages.

Author:
Aslak Helles�y

Nested Class Summary
(package private)  class XJavaDoc.LogMessage
           
static class XJavaDoc.NoInnerClassesPredicate
           
 
Field Summary
private  java.util.Map _abstractFileClasses
           
private  java.util.Map _allSourceClasses
          This map contains the same classes as _sourceSetSourceClasses, but it is also populated with additional classes that may be accessed that were not in the source sets.
private  java.util.Map _binaryClasses
           
private  long _birthday
          Remember when we're born.
private  java.lang.String _docEncoding
          charset for generated file
private  java.lang.String _encoding
          charset for source file
private  java.util.List _logMessages
          info, error and warning messages related to parsing and class qualification
private  java.util.Map _packages
           
private static java.util.HashMap _primitiveClasses
           
private  java.util.Map _properties
           
private  java.util.Set _sourceSetClassNames
           
private  java.util.Set _sourceSets
           
private  java.util.Map _sourceSetSourceClasses
          This map contains all the classes that were passed in the source sets, excluding all inner classes.
private  java.util.Collection _sourceSetSourceClassesWithInnerClasses
          This map contains all the classes that were passed in the source sets, including all inner classes.
private  XTagFactory _tagFactory
           
private  java.util.Map _unknownClasses
           
private  boolean _useNodeParser
          sticky parameter for useNodeParser.
static java.lang.String IS_UNICODE
          Indicates whether this XJavaDoc was built with or without unicode support
static int NO_IMPORTED_PACKAGES
          messgage level for reporting unqualified classes when there are no imported packages
static int ONE_OR_MORE_IMPORTED_PACKAGES
          messgage level for reporting unqualified classes when there are one or more imported packages
private static java.util.List PRIMITIVES
           
 
Constructor Summary
XJavaDoc()
           
 
Method Summary
 void addAbstractFile(java.lang.String qualifiedName, AbstractFile file)
           
private  void addInnerClassRecursive(XClass outer, java.util.Collection c)
          Recursively adds inner classes to a collection
(package private)  XPackage addPackageMaybe(java.lang.String packageName)
          Describe the method
private  void addPrimitive(java.lang.String name, java.lang.String type)
          Describe the method
(package private)  void addSourceClass(SourceClass sourceClass)
          Adds a source class to the cache.
 void addSourceSet(SourceSet sourceSet)
          Adds a new set of java sources to be parsed.
(package private)  boolean classExists(java.lang.String qualifiedClassName)
           
 java.lang.String dereferenceProperties(java.lang.String value)
           
private  java.lang.Class getClass(java.lang.String qualifiedName)
          Returns the Class with the given name, or null if unknown.
 java.lang.String getDocEncoding()
          Getter for generated file charset.
 java.lang.String getEncoding()
          Getter for source file charset.
private  java.util.Collection getOuterSourceClasses()
          Returns all classes in the registered source sets
(package private) static Primitive getPrimitive(java.lang.String name)
          Gets the Primitive attribute of the XJavaDoc class
 java.util.Map getPropertyMap()
           
 java.util.Collection getSourceClasses()
          Returns all classes in the registered source sets, including inner classes
 java.util.Collection getSourceClasses(org.apache.commons.collections.Predicate predicate)
           
private  AbstractFile getSourceFile(java.lang.String qualifiedName)
          Gets the SourceFile attribute of the XJavaDoc object
(package private) static AbstractFile getSourceFileFor(XProgramElement pe)
          Gets the file the pe is contained in.
 XPackage getSourcePackage(java.lang.String packageName)
          Returns the package.
 java.util.Collection getSourcePackages()
          Returns the packages of the specified classes during parsing.
 XTagFactory getTagFactory()
           
 XClass getXClass(java.lang.String qualifiedName)
          Get the XClass corresponding to the qualifiedName.
(package private)  void logMessage(SourceClass clazz, UnknownClass unknownClass, java.lang.String unqualifiedClassName, int level)
           
static void parsePropertyString(java.lang.String value, java.util.List fragments, java.util.List propertyRefs)
          Parses a string containing ${xxx} style property references into two lists.
 void printLogMessages(java.io.PrintStream out, int level)
          Prints the log messages encountered during parsing
static void printMemoryStatus()
          Dump to sytem out the status of XJavadoc.
 void registerTags(java.lang.String classpath)
          Registers tags.
static java.lang.String replaceProperties(java.lang.String value, java.util.Map keys)
          Replaces ${xxx} style constructions in the given value with the string value of the corresponding data types.
 void reset(boolean resetTimeStamp)
          Resets the caches.
private  SourceClass scanAndPut(java.lang.String qualifiedName)
          Scan's a class and puts it in the cache.
 void setDocEncoding(java.lang.String docencoding)
          Setter for generated file charset.
 void setEncoding(java.lang.String encoding)
          Setter for source file charset.
 void setPropertyMap(java.util.Map properties)
           
 void setUseNodeParser(boolean useNodeParser)
          This method can be called prior to parsing so that all classes are parsed with AST (to make it possible to write the source back to disk)
private  boolean sourceExists(java.lang.String qualifiedName)
          Checks is the source exists
 XClass updateClassTag(java.lang.String className, java.lang.String tagName, java.lang.String parameterName, java.lang.String parameterValue, int tagIndex)
          Describe what the method does
 XClass updateMethodTag(java.lang.String className, java.lang.String methodNameWithSignature, java.lang.String tagName, java.lang.String parameterName, java.lang.String parameterValue, int tagIndex)
          Describe what the method does
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

IS_UNICODE

public static final java.lang.String IS_UNICODE
Indicates whether this XJavaDoc was built with or without unicode support

See Also:
Constant Field Values

NO_IMPORTED_PACKAGES

public static final int NO_IMPORTED_PACKAGES
messgage level for reporting unqualified classes when there are no imported packages

See Also:
Constant Field Values

ONE_OR_MORE_IMPORTED_PACKAGES

public static final int ONE_OR_MORE_IMPORTED_PACKAGES
messgage level for reporting unqualified classes when there are one or more imported packages

See Also:
Constant Field Values

PRIMITIVES

private static final java.util.List PRIMITIVES

_primitiveClasses

private static java.util.HashMap _primitiveClasses

_binaryClasses

private final java.util.Map _binaryClasses

_unknownClasses

private final java.util.Map _unknownClasses

_packages

private final java.util.Map _packages

_sourceSets

private final java.util.Set _sourceSets

_sourceSetSourceClasses

private final java.util.Map _sourceSetSourceClasses
This map contains all the classes that were passed in the source sets, excluding all inner classes.


_allSourceClasses

private final java.util.Map _allSourceClasses
This map contains the same classes as _sourceSetSourceClasses, but it is also populated with additional classes that may be accessed that were not in the source sets. This can be superclasses, classes referenced in methods, import statements etc.


_sourceSetClassNames

private final java.util.Set _sourceSetClassNames

_properties

private final java.util.Map _properties

_abstractFileClasses

private final java.util.Map _abstractFileClasses

_tagFactory

private final XTagFactory _tagFactory

_sourceSetSourceClassesWithInnerClasses

private java.util.Collection _sourceSetSourceClassesWithInnerClasses
This map contains all the classes that were passed in the source sets, including all inner classes.


_birthday

private long _birthday
Remember when we're born. We hate sources that are born after us and we pretend they don't exist, because if we don't we'll have very unpredictable behaviour. Well, since we have editor plugin and this is singleton object, we have to relax our policy on this. Or we will have to restart editor every time we like to tag the same class again...


_logMessages

private java.util.List _logMessages
info, error and warning messages related to parsing and class qualification


_useNodeParser

private boolean _useNodeParser
sticky parameter for useNodeParser. _useNodeParser = true -> slower parsing, but modifiable javaodcs.


_encoding

private java.lang.String _encoding
charset for source file


_docEncoding

private java.lang.String _docEncoding
charset for generated file

Constructor Detail

XJavaDoc

public XJavaDoc()
Method Detail

printMemoryStatus

public static void printMemoryStatus()
Dump to sytem out the status of XJavadoc.


replaceProperties

public static java.lang.String replaceProperties(java.lang.String value,
                                                 java.util.Map keys)
Replaces ${xxx} style constructions in the given value with the string value of the corresponding data types. NOTE: This method was taken directly from Ant's source code (org.apache.tools.ant.ProjectHelper) and modified slightly to use a Map instead of a HashMap.

Parameters:
value - The string to be scanned for property references. May be null , in which case this method returns immediately with no effect.
keys - Mapping (String to String) of property names to their values. Must not be null.
Returns:
the original string with the properties replaced, or null if the original string is null.

parsePropertyString

public static void parsePropertyString(java.lang.String value,
                                       java.util.List fragments,
                                       java.util.List propertyRefs)
Parses a string containing ${xxx} style property references into two lists. The first list is a collection of text fragments, while the other is a set of string property names. null entries in the first list indicate a property reference from the second list. NOTE: This method was taken directly from Ant's source code (ProjectHelper) with the BuildException throwing removed.

Parameters:
value - Text to parse. Must not be null.
fragments - List to add text fragments to. Must not be null.
propertyRefs - List to add property names to. Must not be null.

getPrimitive

static Primitive getPrimitive(java.lang.String name)
Gets the Primitive attribute of the XJavaDoc class

Parameters:
name - Describe what the parameter does
Returns:
The Primitive value

getSourceFileFor

static AbstractFile getSourceFileFor(XProgramElement pe)
Gets the file the pe is contained in. Note: calling this method with a XProgramElement not from source (but from a binary or unknown class) will result in a ClassCastException, so don't do that. This method is only used for diagnostics in error reporting.

Parameters:
pe - the program element we want the source for.
Returns:
the file the program element is contained in.

addPrimitive

private final void addPrimitive(java.lang.String name,
                                java.lang.String type)
Describe the method

Parameters:
name - Describe the method parameter
type - The feature to be added to the Primitive attribute

getSourceClasses

public java.util.Collection getSourceClasses(org.apache.commons.collections.Predicate predicate)

getSourceClasses

public java.util.Collection getSourceClasses()
Returns all classes in the registered source sets, including inner classes

Returns:
A Collection of XClass

getSourcePackages

public java.util.Collection getSourcePackages()
Returns the packages of the specified classes during parsing.

Returns:
Describe the return value

getPropertyMap

public java.util.Map getPropertyMap()

getXClass

public XClass getXClass(java.lang.String qualifiedName)
Get the XClass corresponding to the qualifiedName. This can be a class from source, a precompiled class or a primitive. UnknownClass is never returned from this method, unless it has been previously instantiated. IMPORTANT: If the Java source can be located, an instance of SourceClass will be returned. -Even if that file was not among the files in the fileset or sourceset. IMPORTANT: If qualifiedName represents an inner class, an UnknownClass will be returned unless the enclousing "outer" class has been resolved first.

Parameters:
qualifiedName - Fully qualified class name
Returns:
The XClass value

getSourcePackage

public XPackage getSourcePackage(java.lang.String packageName)
Returns the package. The package must be one of the packages of the sources. Other packages, such as java.lang are not available.

Parameters:
packageName -
Returns:
an XPackage, or null if the packageName is not among the sources.

setUseNodeParser

public void setUseNodeParser(boolean useNodeParser)
This method can be called prior to parsing so that all classes are parsed with AST (to make it possible to write the source back to disk)

Parameters:
useNodeParser -

setPropertyMap

public void setPropertyMap(java.util.Map properties)

reset

public void reset(boolean resetTimeStamp)
Resets the caches.

Parameters:
resetTimeStamp - true if timestamps should be reset too.

printLogMessages

public void printLogMessages(java.io.PrintStream out,
                             int level)
Prints the log messages encountered during parsing

Parameters:
out -
level -

addSourceSet

public void addSourceSet(SourceSet sourceSet)
Adds a new set of java sources to be parsed.

Parameters:
sourceSet - a set of java sources.

addAbstractFile

public void addAbstractFile(java.lang.String qualifiedName,
                            AbstractFile file)

updateMethodTag

public XClass updateMethodTag(java.lang.String className,
                              java.lang.String methodNameWithSignature,
                              java.lang.String tagName,
                              java.lang.String parameterName,
                              java.lang.String parameterValue,
                              int tagIndex)
                       throws XJavaDocException
Describe what the method does

Parameters:
className - qualified name of class
tagName - tag name
parameterName - parameter name
parameterValue - new parameter value
tagIndex - index of tag (??)
methodNameWithSignature - method name followed by signature. no spaces. Ex:
doIt(java.lang.String,int)
Returns:
the class corresponding to the className
Throws:
XJavaDocException - If the tag for some reason couldn't be updated

updateClassTag

public XClass updateClassTag(java.lang.String className,
                             java.lang.String tagName,
                             java.lang.String parameterName,
                             java.lang.String parameterValue,
                             int tagIndex)
                      throws XJavaDocException
Describe what the method does

Parameters:
className - Describe what the parameter does
tagName - Describe what the parameter does
parameterName - Describe what the parameter does
parameterValue - Describe what the parameter does
tagIndex - Describe what the parameter does
Returns:
Describe the return value
Throws:
XJavaDocException - Describe the exception

dereferenceProperties

public java.lang.String dereferenceProperties(java.lang.String value)

classExists

final boolean classExists(java.lang.String qualifiedClassName)
Parameters:
qualifiedClassName -
Returns:
true if the class exists, either as source or binary

logMessage

void logMessage(SourceClass clazz,
                UnknownClass unknownClass,
                java.lang.String unqualifiedClassName,
                int level)

addPackageMaybe

XPackage addPackageMaybe(java.lang.String packageName)
Describe the method

Parameters:
packageName - Describe the method parameter
Returns:
Describe the return value

addSourceClass

void addSourceClass(SourceClass sourceClass)
Adds a source class to the cache. This method is also called from JavaParser when parsing inner classes.

Parameters:
sourceClass - Describe the method parameter

getClass

private final java.lang.Class getClass(java.lang.String qualifiedName)
Returns the Class with the given name, or null if unknown.

Parameters:
qualifiedName - Describe what the parameter does
Returns:
The Class value

getOuterSourceClasses

private java.util.Collection getOuterSourceClasses()
Returns all classes in the registered source sets

Returns:
A Collection of XClass

getSourceFile

private AbstractFile getSourceFile(java.lang.String qualifiedName)
Gets the SourceFile attribute of the XJavaDoc object

Parameters:
qualifiedName - Describe what the parameter does
Returns:
The SourceFile value

addInnerClassRecursive

private void addInnerClassRecursive(XClass outer,
                                    java.util.Collection c)
Recursively adds inner classes to a collection

Parameters:
outer - The feature to be added to the InnerClassRecursive attribute
c - The feature to be added to the InnerClassRecursive attribute

sourceExists

private boolean sourceExists(java.lang.String qualifiedName)
Checks is the source exists

Parameters:
qualifiedName - the class to check for
Returns:
true if source exists.

scanAndPut

private SourceClass scanAndPut(java.lang.String qualifiedName)
Scan's a class and puts it in the cache.

Parameters:
qualifiedName - Describe what the parameter does
Returns:
Describe the return value

getTagFactory

public XTagFactory getTagFactory()

registerTags

public void registerTags(java.lang.String classpath)
Registers tags.

Parameters:
classpath - where tags are found.

getEncoding

public java.lang.String getEncoding()
Getter for source file charset.

Returns:
encoding

setEncoding

public void setEncoding(java.lang.String encoding)
Setter for source file charset.


getDocEncoding

public java.lang.String getDocEncoding()
Getter for generated file charset.

Returns:
encoding

setDocEncoding

public void setDocEncoding(java.lang.String docencoding)
Setter for generated file charset.