xjavadoc

Class 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

static 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 List
PRIMITIVES
private Map
_abstractFileClasses
private 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 Map
_binaryClasses
private long
_birthday
Remember when we're born.
private String
_docEncoding
charset for generated file
private String
_encoding
charset for source file
private List
_logMessages
info, error and warning messages related to parsing and class qualification
private Map
_packages
private static HashMap
_primitiveClasses
private Map
_properties
private Set
_sourceSetClassNames
private Map
_sourceSetSourceClasses
This map contains all the classes that were passed in the source sets, excluding all inner classes.
private Collection
_sourceSetSourceClassesWithInnerClasses
This map contains all the classes that were passed in the source sets, including all inner classes.
private Set
_sourceSets
private XTagFactory
_tagFactory
private Map
_unknownClasses
private boolean
_useNodeParser
sticky parameter for useNodeParser.

Constructor Summary

XJavaDoc()

Method Summary

void
addAbstractFile(String qualifiedName, AbstractFile file)
private void
addInnerClassRecursive(XClass outer, Collection c)
Recursively adds inner classes to a collection
(package private) XPackage
addPackageMaybe(String packageName)
Describe the method
private void
addPrimitive(String name, 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(String qualifiedClassName)
String
dereferenceProperties(String value)
private Class
getClass(String qualifiedName)
Returns the Class with the given name, or null if unknown.
String
getDocEncoding()
Getter for generated file charset.
String
getEncoding()
Getter for source file charset.
private Collection
getOuterSourceClasses()
Returns all classes in the registered source sets
(package private) static Primitive
getPrimitive(String name)
Gets the Primitive attribute of the XJavaDoc class
Map
getPropertyMap()
Collection
getSourceClasses()
Returns all classes in the registered source sets, including inner classes
Collection
getSourceClasses(Predicate predicate)
private AbstractFile
getSourceFile(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(String packageName)
Returns the package.
Collection
getSourcePackages()
Returns the packages of the specified classes during parsing.
XTagFactory
getTagFactory()
XClass
getXClass(String qualifiedName)
Get the XClass corresponding to the qualifiedName.
(package private) void
logMessage(SourceClass clazz, UnknownClass unknownClass, String unqualifiedClassName, int level)
static void
parsePropertyString(String value, List fragments, List propertyRefs)
Parses a string containing ${xxx} style property references into two lists.
void
printLogMessages(PrintStream out, int level)
Prints the log messages encountered during parsing
static void
printMemoryStatus()
Dump to sytem out the status of XJavadoc.
void
registerTags(String classpath)
Registers tags.
static String
replaceProperties(String value, 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(String qualifiedName)
Scan's a class and puts it in the cache.
void
setDocEncoding(String docencoding)
Setter for generated file charset.
void
setEncoding(String encoding)
Setter for source file charset.
void
setPropertyMap(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(String qualifiedName)
Checks is the source exists
XClass
updateClassTag(String className, String tagName, String parameterName, String parameterValue, int tagIndex)
Describe what the method does
XClass
updateMethodTag(String className, String methodNameWithSignature, String tagName, String parameterName, String parameterValue, int tagIndex)
Describe what the method does

Field Details

IS_UNICODE

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

NO_IMPORTED_PACKAGES

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

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
Field Value:
1

PRIMITIVES

private static final List PRIMITIVES

_abstractFileClasses

private final Map _abstractFileClasses

_allSourceClasses

private final 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.

_binaryClasses

private final Map _binaryClasses

_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...

_docEncoding

private String _docEncoding
charset for generated file

_encoding

private String _encoding
charset for source file

_logMessages

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

_packages

private final Map _packages

_primitiveClasses

private static HashMap _primitiveClasses

_properties

private final Map _properties

_sourceSetClassNames

private final Set _sourceSetClassNames

_sourceSetSourceClasses

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

_sourceSetSourceClassesWithInnerClasses

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

_sourceSets

private final Set _sourceSets

_tagFactory

private final XTagFactory _tagFactory

_unknownClasses

private final Map _unknownClasses

_useNodeParser

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

Constructor Details

XJavaDoc

public XJavaDoc()

Method Details

addAbstractFile

public void addAbstractFile(String qualifiedName,
                            AbstractFile file)

addInnerClassRecursive

private void addInnerClassRecursive(XClass outer,
                                    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

addPackageMaybe

(package private)  XPackage addPackageMaybe(String packageName)
Describe the method
Parameters:
packageName - Describe the method parameter
Returns:
Describe the return value

addPrimitive

private final void addPrimitive(String name,
                                String type)
Describe the method
Parameters:
name - Describe the method parameter
type - The feature to be added to the Primitive attribute

addSourceClass

(package private)  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

addSourceSet

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

classExists

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

dereferenceProperties

public String dereferenceProperties(String value)

getClass

private final Class getClass(String qualifiedName)
Returns the Class with the given name, or null if unknown.
Parameters:
qualifiedName - Describe what the parameter does
Returns:
The Class value

getDocEncoding

public String getDocEncoding()
Getter for generated file charset.
Returns:
encoding

getEncoding

public String getEncoding()
Getter for source file charset.
Returns:
encoding

getOuterSourceClasses

private Collection getOuterSourceClasses()
Returns all classes in the registered source sets
Returns:
A Collection of XClass

getPrimitive

(package private) static Primitive getPrimitive(String name)
Gets the Primitive attribute of the XJavaDoc class
Parameters:
name - Describe what the parameter does
Returns:
The Primitive value

getPropertyMap

public Map getPropertyMap()

getSourceClasses

public Collection getSourceClasses()
Returns all classes in the registered source sets, including inner classes
Returns:
A Collection of XClass

getSourceClasses

public Collection getSourceClasses(Predicate predicate)

getSourceFile

private AbstractFile getSourceFile(String qualifiedName)
Gets the SourceFile attribute of the XJavaDoc object
Parameters:
qualifiedName - Describe what the parameter does
Returns:
The SourceFile value

getSourceFileFor

(package private) 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.

getSourcePackage

public XPackage getSourcePackage(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.

getSourcePackages

public Collection getSourcePackages()
Returns the packages of the specified classes during parsing.
Returns:
Describe the return value

getTagFactory

public XTagFactory getTagFactory()

getXClass

public XClass getXClass(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

logMessage

(package private)  void logMessage(SourceClass clazz,
                                   UnknownClass unknownClass,
                                   String unqualifiedClassName,
                                   int level)

parsePropertyString

public static void parsePropertyString(String value,
                                       List fragments,
                                       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 (org.apache.tools.ant.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.

printLogMessages

public void printLogMessages(PrintStream out,
                             int level)
Prints the log messages encountered during parsing
Parameters:
out -
level -

printMemoryStatus

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

registerTags

public void registerTags(String classpath)
Registers tags.
Parameters:
classpath - where tags are found.

replaceProperties

public static String replaceProperties(String value,
                                       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.

reset

public void reset(boolean resetTimeStamp)
Resets the caches.
Parameters:
resetTimeStamp - true if timestamps should be reset too.

scanAndPut

private SourceClass scanAndPut(String qualifiedName)
Scan's a class and puts it in the cache.
Parameters:
qualifiedName - Describe what the parameter does
Returns:
Describe the return value

setDocEncoding

public void setDocEncoding(String docencoding)
Setter for generated file charset.
Parameters:

setEncoding

public void setEncoding(String encoding)
Setter for source file charset.
Parameters:

setPropertyMap

public void setPropertyMap(Map properties)

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 -

sourceExists

private boolean sourceExists(String qualifiedName)
Checks is the source exists
Parameters:
qualifiedName - the class to check for
Returns:
true if source exists.

updateClassTag

public XClass updateClassTag(String className,
                             String tagName,
                             String parameterName,
                             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

updateMethodTag

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