com.github.aliteralmind.codelet.util

Class AllOnlineOfflineDocRoots

java.lang.Object

com.github.aliteralmind.codelet.util.AllOnlineOfflineDocRoots

public class AllOnlineOfflineDocRoots
extends Object

Collection of package-lists from all external Java libraries used by a project, for mapping a package name to its JavaDoc document root url--even if that online package-list is inaccessible. This information is the equivalent of javadoc.exe's -link and -linkoffline options.

While it may be possible to read in the values of -link and -linkoffline, as passed into javadoc.exe, doing so would make Codelet more dependant on com.sun.javadoc, which is against its goal of minimizing dependencies on this non-standard package.

Since:

0.1.0

Author:

Copyright (C) 2014, Jeff Epstein (aliteralmind __DASH__ github __AT__ yahoo __DOT__ com), dual-licensed under the LGPL (version 3.0 or later) or the ASL (version 2.0). See source code for details. http://codelet.aliteralmind.com, https://github.com/aliteralmind/codelet

Method Summary

Methods

Modifier and Type	Method and Description
StringBuilder	appendToString(StringBuilder to_appendTo)
Map<String,OnlineOfflineDocRoot>	getNameToRootMap() An immutable map whose key is the doc-root's name, and value is its OnlineOfflineDocRoot.
Map<String,String>	getPkgToUrlMap() An immutable map whose key is a package, and value is its document root url.
Map<String,OnlineOfflineDocRoot>	getUrlToRootMap() An immutable map whose key is the doc-root's url, and value is its OnlineOfflineDocRoot.
static AllOnlineOfflineDocRoots	newFromConfigLineIterator(Iterator<String> line_itr, String offlineName_prefixPath, String offlineName_postfix, int online_attemptCount, long online_sleepMills, RefreshOffline refresh_offline, IfError if_error, Appendable debug_ifNonNull, Appendable dbgError_ifNonNull) Create a new AllOnlineOfflineDocRoots from a configuration file, where each line contains two items: the doc-root's offline file path and online document-root url.
String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

getNameToRootMap

public Map<String,OnlineOfflineDocRoot> getNameToRootMap()

An immutable map whose key is the doc-root's name, and value is its OnlineOfflineDocRoot.

See Also:

getPkgToUrlMap()

getUrlToRootMap

public Map<String,OnlineOfflineDocRoot> getUrlToRootMap()

An immutable map whose key is the doc-root's url, and value is its OnlineOfflineDocRoot.

See Also:

getPkgToUrlMap()

getPkgToUrlMap

public Map<String,String> getPkgToUrlMap()

An immutable map whose key is a package, and value is its document root url.

See Also:

getUrlToRootMap(), getNameToRootMap()

toString

public String toString()

Overrides:

toString in class Object

Returns:

appendToString(new StringBuilder()).toString()

appendToString

public StringBuilder appendToString(StringBuilder to_appendTo)

Parameters:

to_appendTo - May not be null.

See Also:

toString()

newFromConfigLineIterator

public static final AllOnlineOfflineDocRoots newFromConfigLineIterator(Iterator<String> line_itr,
                                                 String offlineName_prefixPath,
                                                 String offlineName_postfix,
                                                 int online_attemptCount,
                                                 long online_sleepMills,
                                                 RefreshOffline refresh_offline,
                                                 IfError if_error,
                                                 Appendable debug_ifNonNull,
                                                 Appendable dbgError_ifNonNull)
                                                                throws InterruptedException

Create a new AllOnlineOfflineDocRoots from a configuration file, where each line contains two items: the doc-root's offline file path and online document-root url.

Each line in a configuration file is in the format

[offline_file_path] [url]

Where

• [offline_file_path] is the full path of the locally-stored file. This must exist, and be both readable and writable.
• [url] is the url to the JavaDoc document root ("{@docRoot}") for an external Java library. Must end with a slash ('/'), and must contain the library's "package-list" file.

The file-path and url are separated with at least one space or tab.

(Lines starting with '#' are ignored. Empty lines are not allowed.)

Example

If both offlineName_prefixPath and offlineName_postfix are null:

C:\java_code\config\javadoc_offline_package_lists\java.txt http://docs.oracle.com/javase/7/docs/api/

An equivalent is to set

• offlineName_prefixPath to "C:\java_code\config\javadoc_offline_package_lists\"
• and offlineName_postfix to ".txt"

and then the config line can be

java http://docs.oracle.com/javase/7/docs/api/

Steps for each line in line_itr:

1. If online_attemptCount is
   • Greater than zero: This creates the OnlineOfflineDocRoot with
     OnlineOfflineDocRoot.newFromOnline(name, url, path, online_attemptCount, online_sleepMills, if_error, refresh_offline, debug_ifNonNull, dbgError_ifNonNull)
   • Equal to zero (or if retrieving from online fails, and if_error.WARN): This creates the OnlineOfflineDocRoot with
     OnlineOfflineDocRoot.newFromOffline(name, url, path, debug_ifNonNull, dbgError_ifNonNull)

Parameters:

line_itr - May not be null, and should have at least one item. All offline paths must be unique, and all urls must be unique.

offlineName_prefixPath - If non-null, this is the base directory appended to each offline name, as described above. Setting this to null is the same as the empty string ("").

offlineName_postfix - If non-null, this is the postfix appended to each offline name.

refresh_offline - When online_attemptCount is greater than zero, should the offline package-list be refreshed from the online version? If online_attemptCount is zero, this parameter is ignored.

Throws:

InterruptedException

See Also:

CodeletBootstrap.EXTERNAL_DOC_ROOT_URL_FILE