xbn.jdlcode
Class JDFile

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.jdlcode.JDFile

Direct Known Subclasses:

JDClass

public class JDFile

extends XBNObject

Represents a single JavaDoc (html) file that may or may not contain JavaDoc Link Codes.

JDFiles can have JavaDoc Link Codes directly, indirectly or not at all.

Source code: JDFile.java.

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

JDFile(String s_fqClassName)
Create a JDFile from the fully qualified class name, as found in the class map configuration file.

JDFile(String s_relDir, String s_fileName)
Create a JDFile from the path/filename combination found in HTMLStandardWriter.

Method Summary

boolean	equals(JDFile jd_file) Does the provided JDFile represent the same file as this JDFile?
APString	getAPSLinkPagesINDIRECT() Get the names for all JavaDoc html files that only display JavaDoc Link Codes indirectly.
APString	getAPSLinkPagesNONE() Get the names for all JavaDoc html files that have/display no JavaDoc Link Codes at all.
int	getDirCount() How many directories are there in the file represented by this JDFile?
String	getFileName() Get the name of this JDFile.
String	getList(String s_divider) Get a list of all part names, with the requested divider string.
String	getPackageList(String s_divider) Get a list of the package name for this JDFile (all parts but the last, which is the file name).
String	getPackagePrefix() Get the prefix for this JDFile.
String	getPart(int i_dx) Get the part at the requested array index.
int	getPartCount() How many parts exist in the name of this JDClass?
PASString	getPASSPackage() Get an PASString representing all the part names, except the final part (the file name itself).
PASString	getPASString() Get an PASString representing the part names.
boolean	hasJDLCsDirectly() Is it possible for this JDFile to contain JavaDoc Link Codes "directly"?
boolean	hasJDLCsIndirectly() Is it possible for this JDFile contain JavaDoc Link Codes "indirectly" (Examples: good and bad)?
boolean	hasNoJDLCodes() Does this JDFile contain no JavaDoc Link Codes?
boolean	isExternal() Is this JDFile external?
boolean	isInSamePackageAs(JDFile jd_file) Is the provided JDFile in the same package as this JDFile?.
boolean	isLocal() Is this JDFile local?
boolean	isPrimitive() Is this JDFile primitive?
String	toString() Get some information about this JDFile.

Methods inherited from class xbn.XBNObject

getXMsgPrefix, sop, sopl, sopl, throwAX, throwAXIfBadStr, throwAXIfNull, throwAXSpoof

Methods inherited from class java.lang.Object

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

Constructor Detail

JDFile

public JDFile(String s_relDir,
              String s_fileName)

Create a JDFile from the path/filename combination found in HTMLStandardWriter. It is expected that this constructor only be called by HTMLStandardWriter, via the "javadoc" process.

Parameters:

s_relDir - The relative url directory to the class or html file. For example, if xbn.jdlcode.UtilJDLCode is a class in your class map configuration text file, then this variable should equal "xbn/jdlcode". Another example: The file c:\home\my_javadoc\index-files\index-1.html has a relative url directory of index-files

s_fileName - The name of the class or html file. For example, if xbn.jdlcode.UtilJDLCode is in your class map, then this variable should equal "UtilJDLCode". Another example: The file c:\home\my_javadoc\index-files\index-1.html has a file name of index-1.html

JDFile

public JDFile(String s_fqClassName)

Create a JDFile from the fully qualified class name, as found in the class map configuration file.

Parameters:

s_fqClassName - The fully qualified name to a JavaDoc html file, divided by dots, minus the ".html". For example: xbn.array.VWObject or index-files.index-1. Must...

• ...be non-null, and at least one character in length.
• ...not start or end with a period.
• ...not end with ".html".
• ...not contain "..".
• ...be less than or equal to 100 characters in length.

Method Detail

getPartCount

public final int getPartCount()

How many parts exist in the name of this JDClass?

Each part is divided by a period. For example, xbn.XBNObject has two parts, and xbn.jdlcode.JDFile has three.

getDirCount

public final int getDirCount()

How many directories are there in the file represented by this JDFile?

Returns:

(getPartCount() - 1)

getPart

public final String getPart(int i_dx)

Get the part at the requested array index.

Parameters:

i_dx - The array index for the (private, internal) string array of parts. Must range zero..(getPartCount() - 1).

getFileName

public final String getFileName()

Get the name of this JDFile.

Returns:

getPart(getPartCount() - 1)

getPASString

public PASString getPASString()

Get an PASString representing the part names. This PASString object is created once, at constructor time.

getPASSPackage

public PASString getPASSPackage()

Get an PASString representing all the part names, except the final part (the file name itself).

This PASString object is created once, when this function is first called.

getList

public String getList(String s_divider)

Get a list of all part names, with the requested divider string.

Parameters:

s_divider - The dividing string. May not be null.

Returns:

Assuming this array of parts: {"xbn", "jdlcode", "JDFile"}, if s_divider equals...

• ...".": xbn.jdlcode.JDFile
• ..."/": xbn/jdlcode/JDFile
• ..."bla": jeffybladocletblaJDFile

Specifically, this returns getPASString().getList(s_divider)

getPackageList

public String getPackageList(String s_divider)

Get a list of the package name for this JDFile (all parts but the last, which is the file name).

Parameters:

s_divider - The dividing string. May not be null.

Returns:

Assuming this array of parts: {"xbn", "jdlcode", "JDFile"}, if s_divider equals...

• ...".": xbn.jdlcode
• ..."/": xbn/jdlcode
• ..."bla": jeffybladoclet

Specifically, this returns getPASSPackage().getList(s_divider)

getPackagePrefix

public String getPackagePrefix()

Get the prefix for this JDFile.

Returns:

"" If getDirCount equals zero.
getPart(0) If otherwise.

isInSamePackageAs

public boolean isInSamePackageAs(JDFile jd_file)

Is the provided JDFile in the same package as this JDFile?.

Parameters:

jd_file - The JDFile, whose package should be declared to this JDFile's package. May not be null.

Returns:

jd_file.getPackageList(".").equals(getPackageList("."))

isLocal

public boolean isLocal()

Is this JDFile local?

See isPrimitive and isExternal.

What does local mean?

Let's say you generate your JavaDoc into C:\my_java_code\javadoc\, and the following three directories--after running the JavaDoc command--exist in it: "index-files", "xbn", "random_java_pkg". index-files is a directory created automatically by JavaDoc. xbn and random_java_pkg are the directories in which the documentation for my packages are held. So the xbn.* and random_java_pkg.* packages are local.

Returns:

true All JDFiles are local.

isPrimitive

public boolean isPrimitive()

Is this JDFile primitive?

See isLocal and isExternal.

What does primitive mean?

int, char, long, float, ...

For the sake of Javadoc, primitive variables cannot be linked to, nor from. There are no JavaDoc html pages existing for these primitive types.

Returns:

false All JDFiles are local.

isExternal

public boolean isExternal()

Is this JDFile external?

See isLocal and isPrimitive.

What does external mean?

All packages that are not local, but are defined in the class map configuration text file--even if you never link to that package in your documentation.

Returns:

false All JDFiles are local.

toString

public String toString()

Get some information about this JDFile.

Overrides:

toString in class Object

hasNoJDLCodes

public final boolean hasNoJDLCodes()

Does this JDFile contain no JavaDoc Link Codes?

If the name of this file exists in getAPSLinkPagesNONE, then this is a file that is not editable at all by you (the Java programmer). Rather, this file is created solely by the javadoc process. Therefore, this page cannot contain nor display any JavaDoc Link Codes, either directly or indirectly.

JDFiles with no JavaDoc Link Codes cannot be analyzed by UtilJDLCode.crashIfBadTarget.

Returns:

(!hasJDLCsDirectly() && !hasJDLCsIndirectly())

hasJDLCsDirectly

public final boolean hasJDLCsDirectly()

Is it possible for this JDFile to contain JavaDoc Link Codes "directly"?

If the name of this file does not exist in either getAPSLinkPagesNONE or getAPSLinkPagesINDIRECT, then this JDFile represents one of the actual "*.java" or "package.html" files in your packages. It therefore can contain JavaDoc Link Codes in it.

For example

This link was written by me in JDFile.java, has this JavaDoc Link Code as the url:

~JD~vwo~EJD~

It is displayed in this file (JDFile.html), "directly", with the resulting relative url:

../array/VWObject.html

Direct and Indirect

JDFiles that have JavaDoc Link Codes directly can also display them indirectly. For example, Template.java has no documentation written in it for getName(). However, Template.html inherits the documentation for this function from Named.getName. Note that Template.html#getName says "Description copied from...".

Technically speaking: When [yourJDFile].hasJDLCsDirectly() equals true, [yourJDFile].hasJDLCsIndirectly() also (always) equals true.

UtilJDLCode.crashIfBadTarget()

You can ensure that indirect JavaDoc Link Codes are pointing to a target that actually exists, by using UtilJDLCode.crashIfBadTarget. This function is optionally called by the javadoc and ReportBadJDLinkCodes processes.

The SplitLinkCode constructor also validates JavaDoc Link Codes, but only to ensure proper formatting.

Process	How to turn target validation on	How to turn it off
javadoc	Go into HtmlStandardWriter.java, change the second-to-last boolean (the third-to-last overall) parameter of "getJavadocLine" to true, and recompile (sorry, no convenient method at this point..).	Change the second-to-last boolean parameter of "getJavadocLine" to false and recompile.
ReportBadJDLinkCodes	When you run ReportBadJDLinkCodes, set the third command-line parameter ("ENSURE_LINK_TARGETS_EXIST") to "true".	Set the third command-line parameter to "false".

Validating direct JavaDoc Link Codes has precedence over indirect. When direct ones are validated (via either process, or the crashIfBadTarget function) indirect ones may be validated. When direct ones are not being validated, it is not possible to validate indirect ones.

Returns:

true If it is possible for the html file (as represented by this JDFile) to have JavaDoc Link Codes directly.
false If it is not possible.

hasJDLCsIndirectly

public final boolean hasJDLCsIndirectly()

Is it possible for this JDFile contain JavaDoc Link Codes "indirectly" (Examples: good and bad)?

If the name of this file exists in getAPSLinkPagesINDIRECT, then this is a file that is both...

• ...not editable at all by you (the Java programmer). Rather, this file is created solely by the javadoc process.
• ...is a page that displays JavaDoc Link Codes indirectly. "Indirectly", meaning the links are displayed in this page, but only as a reference to the page in which it actually (directly) exists.

For example

The "good" and "bad" example links above were written in JDFile.java, having these urls:

Good: ~JD~jdf#getList(s)~EJD~
Bad: ~JD~getList(s)~EJD~

These are displayed in this file (JDFile.html), "directly", with the urls:

Good: JDFile.html#getList(java.lang.String)
Bad: #getList(java.lang.String)

These same links are also displayed "indirectly" in the "H" index page, with these urls:

Good: ../xbn/jdlcode/JDFile.html#getList(java.lang.String)
Bad: #getList(java.lang.String)

The "good" link works in both JDFile.html and the "H" index page. The "bad" one works in JDFile (this class, this function's first sentence of documentation), but not the "H" index.

All JavaDoc Link Codes existing in the first sentence of a JavaDoc Block (as the "good" and "bad" links are in this) are also displayed in index and, potentially, deprecated pages. Therefore, to prevent errors such as demonstrated with the "bad" link, ensure that you provide the class prefix to every first-sentence JavaDoc Link Code.

Indirect and Direct

When [yourJDFile].hasJDLCsIndirectly() equals true, [yourJDFile].hasJDLCsDirectly() may equal true or false.

JDFiles that have JavaDoc Link Codes indirectly may or may not have them directly. For example, as described in the documentation for hasJDLCsDirectly, Template.html has both indirect and direct. However, all index pages have only indirect.

UtilJDLCode.crashIfBadTarget()

You can ensure that indirect JavaDoc Link Codes are pointing to a target that actually exists, by using UtilJDLCode.crashIfBadTarget. This function is optionally called by the javadoc process.

The SplitLinkCode constructor also validates JavaDoc Link Codes, but only to ensure proper formatting.

Since these JDFiles contain no JavaDoc Link Codes directly, you may or may not want the targets verified.

Process	How to turn target validation on	How to turn it off
javadoc	Go into HtmlStandardWriter.java, change the last boolean (the second-to-last overall) parameter of "getJavadocLine" to false, and recompile (sorry, no convenient method at this point..).	Change the last boolean parameter of "getJavadocLine" to true and recompile.
ReportBadJDLinkCodes	N/A. Indirect JavaDoc Link Codes cannot be checked by this process

This table assumes direct JavaDoc Link Codes are being validated.

Validating direct JavaDoc Link Codes has precedence over indirect. When direct ones are being validated (via either process) indirect ones may be validated. When direct ones are not being validated, it is not possible to validate indirect ones.

Returns:

true If it is possible for the html file (as represented by this JDFile) to display JavaDoc Link Codes indirectly.
false If it is not possible.

getAPSLinkPagesNONE

public final APString getAPSLinkPagesNONE()

Get the names for all JavaDoc html files that have/display no JavaDoc Link Codes at all.

See hasNoJDLCodes.

Returns:

new APString(new String[] {"allclasses-frame", "help-doc", "index", "overview-frame", "overview-tree", "package-frame", "package-list", "package-tree", "packages", "serialized-form"}

The APString is created only once.

getAPSLinkPagesINDIRECT

public final APString getAPSLinkPagesINDIRECT()

Get the names for all JavaDoc html files that only display JavaDoc Link Codes indirectly.

See hasJDLCsIndirectly.

Returns:

new APString(new String[] {"deprecated-list", "index-1", "index-10", "index-11", "index-12", "index-13", "index-14", "index-15", "index-16", "index-17", "index-18", "index-19", "index-2", "index-20", "index-21", "index-22", "index-23", "index-24", "index-25", "index-26", "index-3", "index-4", "index-5", "index-6", "index-7", "index-8", "index-9"}

The APString is created only once.

equals

public final boolean equals(JDFile jd_file)

Does the provided JDFile represent the same file as this JDFile?

Parameters:

jd_file - The JDFile to compare this against. May not be null.

Returns:

true If jd_file and this...

• ...have the same part counts.
• ...and every getPart(x) is equal to jd_file.getPart(x).

false If otherwise.