com.sun.tools.doclets.internal.toolkit.util
Class Util

java.lang.Object
  com.sun.tools.doclets.internal.toolkit.util.Util

public class Util
extends java.lang.Object

Utilities Class for Doclets. This code is not part of an API. It is implementation that is subject to change. Do not use it as an API

Nested Class Summary

private static class

Util.TypeComparator We want the list of types in alphabetical order.

Field Summary

static java.lang.String[][]

HTML_ESCAPE_CHARS A mapping between characters and their corresponding HTML escape character.

Constructor Summary

Util()

Method Summary

private static void	addAllInterfaceTypes(java.util.Map<ClassDoc,Type> results, Type type, Type[] interfaceTypes, boolean raw, Configuration configuration)
static <T extends ProgramElementDoc> java.util.List<T>	asList(T[] members)
private static boolean	checkCopyDocFilesErrors(Configuration configuration, java.lang.String path, java.lang.String dirName) Given the parameters for copying doc-files, check for errors.
static void	copyDocFiles(Configuration configuration, java.lang.String path, java.lang.String dir, boolean overwrite) Copy the given directory contents from the source package directory to the generated documentation directory.
static void	copyFile(java.io.File destfile, java.io.File srcfile) Copy source file to destination file.
static void	copyResourceFile(Configuration configuration, java.lang.String resourcefile, boolean overwrite) Copy a file in the resources directory to the destination directory (if it is not there already).
static java.lang.String	escapeHtmlChars(java.lang.String s) Given a string, escape all special html characters and return the result.
static ProgramElementDoc[]	excludeDeprecatedMembers(ProgramElementDoc[] members) Return array of class members whose documentation is to be generated.
static java.util.List<ProgramElementDoc>	excludeDeprecatedMembersAsList(ProgramElementDoc[] members) Return array of class members whose documentation is to be generated.
static boolean	executableMembersEqual(ExecutableMemberDoc member1, ExecutableMemberDoc member2)
private static void	findAllInterfaceTypes(java.util.Map<ClassDoc,Type> results, ClassDoc c, boolean raw, Configuration configuration)
private static void	findAllInterfaceTypes(java.util.Map<ClassDoc,Type> results, ParameterizedType p, Configuration configuration)
static MethodDoc	findMethod(ClassDoc cd, MethodDoc method) Search for the given method in the given class.
static java.io.Writer	genWriter(Configuration configuration, java.lang.String path, java.lang.String filename, java.lang.String docencoding) Create the directory path for the file to be generated, construct FileOutputStream and OutputStreamWriter depending upon docencoding.
static java.util.List<Type>	getAllInterfaces(Type type, Configuration configuration)
static java.util.List<Type>	getAllInterfaces(Type type, Configuration configuration, boolean sort) For the class return all implemented interfaces including the superinterfaces of the implementing interfaces, also iterate over for all the superclasses.
static Type	getFirstVisibleSuperClass(ClassDoc classDoc, Configuration configuration) Given a class, return the closest visible super class.
static ClassDoc	getFirstVisibleSuperClassCD(ClassDoc classDoc, Configuration configuration) Given a class, return the closest visible super class.
static java.lang.String	getPackageFileHeadName(PackageDoc packageDoc) Given a package, return it's file name without the extension.
static java.lang.String	getPackageName(PackageDoc packageDoc) Given a package, return it's name.
static java.lang.String	getPackageSourcePath(Configuration configuration, PackageDoc pkgDoc) Given a PackageDoc, return the source path for that package.
static java.lang.String	getTypeName(Configuration config, ClassDoc cd, boolean lowerCaseOnly) Given a ClassDoc, return the name of its type (Class, Interface, etc.).
static boolean	isCoreClass(ClassDoc cd) According to the Java Language Specifications, all the outer classes and static inner classes are core classes.
static boolean	isDeprecated(ProgramElementDoc doc) Return true if the given Doc is deprecated.
static boolean	isDocumentedAnnotation(AnnotationTypeDoc annotationDoc) Given an annotation, return true if it should be documented and false otherwise.
static boolean	isLinkable(ClassDoc classDoc, Configuration configuration) Return true if this class is linkable and false if we can't link to the desired class.
static boolean	matches(ProgramElementDoc doc1, ProgramElementDoc doc2)
static boolean	nonPublicMemberFound(ProgramElementDoc[] members) Return true if a non-public member found in the given array.
static java.lang.String	quote(java.lang.String filepath) Enclose in quotes, used for paths and filenames that contains spaces
static void	replaceTabs(int tabLength, java.lang.StringBuffer s) Given a string, replace all tabs with the appropriate number of spaces.
static java.lang.String	replaceText(java.lang.String originalStr, java.lang.String oldStr, java.lang.String newStr) Given a string, replace all occurraces of 'newStr' with 'oldStr'.
static void	setEnumDocumentation(Configuration configuration, ClassDoc classDoc) The documentation for values() and valueOf() in Enums are set by the doclet.
static java.lang.String[]	tokenize(java.lang.String s, char separator, int maxTokens) Given a string, return an array of tokens.
static ProgramElementDoc[]	toProgramElementDocArray(java.util.List<ProgramElementDoc> list) Return the list of ProgramElementDoc objects as Array.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HTML_ESCAPE_CHARS

public static final java.lang.String[][] HTML_ESCAPE_CHARS

A mapping between characters and their corresponding HTML escape character.

Constructor Detail

Util

public Util()

Method Detail

excludeDeprecatedMembers

public static ProgramElementDoc[] excludeDeprecatedMembers(ProgramElementDoc[] members)

Return array of class members whose documentation is to be generated. If the member is deprecated do not include such a member in the returned array.

Parameters:

members - Array of members to choose from.

Returns:

ProgramElementDoc[] Array of eligible members for whom documentation is getting generated.

excludeDeprecatedMembersAsList

public static java.util.List<ProgramElementDoc> excludeDeprecatedMembersAsList(ProgramElementDoc[] members)

Return array of class members whose documentation is to be generated. If the member is deprecated do not include such a member in the returned array.

Parameters:

members - Array of members to choose from.

Returns:

List List of eligible members for whom documentation is getting generated.

toProgramElementDocArray

public static ProgramElementDoc[] toProgramElementDocArray(java.util.List<ProgramElementDoc> list)

Return the list of ProgramElementDoc objects as Array.

nonPublicMemberFound

public static boolean nonPublicMemberFound(ProgramElementDoc[] members)

Return true if a non-public member found in the given array.

Parameters:

members - Array of members to look into.

Returns:

boolean True if non-public member found, false otherwise.

findMethod

public static MethodDoc findMethod(ClassDoc cd,
                                   MethodDoc method)

Search for the given method in the given class.

Parameters:

cd - Class to search into.

method - Method to be searched.

Returns:

MethodDoc Method found, null otherwise.

executableMembersEqual

public static boolean executableMembersEqual(ExecutableMemberDoc member1,
                                             ExecutableMemberDoc member2)

Parameters:

member1 - the first method to compare.

member2 - the second method to compare.

Returns:

true if member1 overrides/hides or is overriden/hidden by member2.

isCoreClass

public static boolean isCoreClass(ClassDoc cd)

According to the Java Language Specifications, all the outer classes and static inner classes are core classes.

matches

public static boolean matches(ProgramElementDoc doc1,
                              ProgramElementDoc doc2)

copyFile

public static void copyFile(java.io.File destfile,
                            java.io.File srcfile)
                     throws java.io.IOException

Copy source file to destination file.

Throws:

java.lang.SecurityException

java.io.IOException

copyDocFiles

public static void copyDocFiles(Configuration configuration,
                                java.lang.String path,
                                java.lang.String dir,
                                boolean overwrite)

Copy the given directory contents from the source package directory to the generated documentation directory. For example for a package java.lang this method find out the source location of the package using SourcePath and if given directory is found in the source directory structure, copy the entire directory, to the generated documentation hierarchy.

Parameters:

configuration - The configuration of the current doclet.

path - The relative path to the directory to be copied.

dir - The original directory name to copy from.

overwrite - Overwrite files if true.

checkCopyDocFilesErrors

private static boolean checkCopyDocFilesErrors(Configuration configuration,
                                               java.lang.String path,
                                               java.lang.String dirName)

Given the parameters for copying doc-files, check for errors.

Parameters:

configuration - The configuration of the current doclet.

path - The relative path to the directory to be copied.

dirName - The original directory name to copy from.

copyResourceFile

public static void copyResourceFile(Configuration configuration,
                                    java.lang.String resourcefile,
                                    boolean overwrite)

Copy a file in the resources directory to the destination directory (if it is not there already). If overwrite is true and the destination file already exists, overwrite it.

Parameters:

configuration - Holds the destination directory and error message

resourcefile - The name of the resource file to copy

overwrite - A flag to indicate whether the file in the destination directory will be overwritten if it already exists.

getPackageSourcePath

public static java.lang.String getPackageSourcePath(Configuration configuration,
                                                    PackageDoc pkgDoc)

Given a PackageDoc, return the source path for that package.

Parameters:

configuration - The Configuration for the current Doclet.

pkgDoc - The package to seach the path for.

Returns:

A string representing the path to the given package.

getAllInterfaces

public static java.util.List<Type> getAllInterfaces(Type type,
                                                    Configuration configuration,
                                                    boolean sort)

For the class return all implemented interfaces including the superinterfaces of the implementing interfaces, also iterate over for all the superclasses. For interface return all the extended interfaces as well as superinterfaces for those extended interfaces.

Parameters:

type - type whose implemented or super interfaces are sought.

configuration - the current configuration of the doclet.

sort - if true, return list of interfaces sorted alphabetically.

Returns:

List of all the required interfaces.

getAllInterfaces

public static java.util.List<Type> getAllInterfaces(Type type,
                                                    Configuration configuration)

findAllInterfaceTypes

private static void findAllInterfaceTypes(java.util.Map<ClassDoc,Type> results,
                                          ClassDoc c,
                                          boolean raw,
                                          Configuration configuration)

findAllInterfaceTypes

private static void findAllInterfaceTypes(java.util.Map<ClassDoc,Type> results,
                                          ParameterizedType p,
                                          Configuration configuration)

addAllInterfaceTypes

private static void addAllInterfaceTypes(java.util.Map<ClassDoc,Type> results,
                                         Type type,
                                         Type[] interfaceTypes,
                                         boolean raw,
                                         Configuration configuration)

asList

public static <T extends ProgramElementDoc> java.util.List<T> asList(T[] members)

quote

public static java.lang.String quote(java.lang.String filepath)

Enclose in quotes, used for paths and filenames that contains spaces

getPackageName

public static java.lang.String getPackageName(PackageDoc packageDoc)

Given a package, return it's name.

Parameters:

packageDoc - the package to check.

Returns:

the name of the given package.

getPackageFileHeadName

public static java.lang.String getPackageFileHeadName(PackageDoc packageDoc)

Given a package, return it's file name without the extension.

Parameters:

packageDoc - the package to check.

Returns:

the file name of the given package.

replaceText

public static java.lang.String replaceText(java.lang.String originalStr,
                                           java.lang.String oldStr,
                                           java.lang.String newStr)

Given a string, replace all occurraces of 'newStr' with 'oldStr'.

Parameters:

originalStr - the string to modify.

oldStr - the string to replace.

newStr - the string to insert in place of the old string.

escapeHtmlChars

public static java.lang.String escapeHtmlChars(java.lang.String s)

Given a string, escape all special html characters and return the result.

Parameters:

s - The string to check.

Returns:

the original string with all of the HTML characters escaped.

See Also:

HTML_ESCAPE_CHARS

genWriter

public static java.io.Writer genWriter(Configuration configuration,
                                       java.lang.String path,
                                       java.lang.String filename,
                                       java.lang.String docencoding)
                                throws java.io.IOException,
                                       java.io.UnsupportedEncodingException

Create the directory path for the file to be generated, construct FileOutputStream and OutputStreamWriter depending upon docencoding.

Parameters:

path - The directory path to be created for this file.

filename - File Name to which the PrintWriter will do the Output.

docencoding - Encoding to be used for this file.

Returns:

Writer Writer for the file getting generated.

Throws:

java.io.IOException - Exception raised by the FileWriter is passed on to next level.

java.io.UnsupportedEncodingException - Exception raised by the OutputStreamWriter is passed on to next level.

See Also:

FileOutputStream, OutputStreamWriter

isDocumentedAnnotation

public static boolean isDocumentedAnnotation(AnnotationTypeDoc annotationDoc)

Given an annotation, return true if it should be documented and false otherwise.

Parameters:

annotationDoc - the annotation to check.

Returns:

true return true if it should be documented and false otherwise.

tokenize

public static java.lang.String[] tokenize(java.lang.String s,
                                          char separator,
                                          int maxTokens)

Given a string, return an array of tokens. The separator can be escaped with the '\' character. The '\' character may also be escaped by the '\' character.

Parameters:

s - the string to tokenize.

separator - the separator char.

maxTokens - the maxmimum number of tokens returned. If the max is reached, the remaining part of s is appended to the end of the last token.

Returns:

an array of tokens.

isLinkable

public static boolean isLinkable(ClassDoc classDoc,
                                 Configuration configuration)

Return true if this class is linkable and false if we can't link to the desired class.
NOTE: You can only link to external classes if they are public or protected.

Parameters:

classDoc - the class to check.

configuration - the current configuration of the doclet.

Returns:

true if this class is linkable and false if we can't link to the desired class.

getFirstVisibleSuperClass

public static Type getFirstVisibleSuperClass(ClassDoc classDoc,
                                             Configuration configuration)

Given a class, return the closest visible super class.

Parameters:

classDoc - the class we are searching the parent for.

configuration - the current configuration of the doclet.

Returns:

the closest visible super class. Return null if it cannot be found (i.e. classDoc is java.lang.Object).

getFirstVisibleSuperClassCD

public static ClassDoc getFirstVisibleSuperClassCD(ClassDoc classDoc,
                                                   Configuration configuration)

Given a class, return the closest visible super class.

Parameters:

classDoc - the class we are searching the parent for.

configuration - the current configuration of the doclet.

Returns:

the closest visible super class. Return null if it cannot be found (i.e. classDoc is java.lang.Object).

getTypeName

public static java.lang.String getTypeName(Configuration config,
                                           ClassDoc cd,
                                           boolean lowerCaseOnly)

Given a ClassDoc, return the name of its type (Class, Interface, etc.).

Parameters:

cd - the ClassDoc to check.

lowerCaseOnly - true if you want the name returned in lower case. If false, the first letter of the name is capatilized.

Returns:

replaceTabs

public static void replaceTabs(int tabLength,
                               java.lang.StringBuffer s)

Given a string, replace all tabs with the appropriate number of spaces.

Parameters:

tabLength - the length of each tab.

s - the String to scan.

setEnumDocumentation

public static void setEnumDocumentation(Configuration configuration,
                                        ClassDoc classDoc)

The documentation for values() and valueOf() in Enums are set by the doclet.

isDeprecated

public static boolean isDeprecated(ProgramElementDoc doc)

Return true if the given Doc is deprecated.

Parameters:

doc - the Doc to check.

Returns:

true if the given Doc is deprecated.