com.github.aliteralmind.codelet

Enum CodeletBootstrap

java.lang.Object

java.lang.Enum<CodeletBootstrap>

com.github.aliteralmind.codelet.CodeletBootstrap

All Implemented Interfaces:

Serializable, Comparable<CodeletBootstrap>

public enum CodeletBootstrap
extends Enum<CodeletBootstrap>

Initializes Codelet by loading all configuration--This is triggered by the first codelet-taglet encountered by javadoc.exe.

This:

1. Obtains the codelet_config_dir system property as passed into the javadoc application.
2. Loads base configuration from codelet.properties, as exists in the configuration directory. This includes the Codelet-required and user-created named debuggers, and the external JavaDoc library package-lists.
3. Loads default templates.
4. Loads the template-override configuration from template_overrides_config.

This order is required to avoid circular dependencies.

Automated named debuggers

zzconfiguration.

• nameddebuglevels.listallafterload: List all levels after being loaded.
• nameddebuglevels.eachquery: List each level when queried--regardless if on or off. Use this to determine any unused levels that may exist in the configuration file.
• allvaluessummary: List all basic configuration values after complete.
• progress: The basic steps taken while loading all configuration.
• templateoverrides.
  • allentriespostloaded: List all entries organized by JavaDoc file.
  • eachentryasloaded: List all entries as they are loaded.

Full names:

zzconfiguration.nameddebuglevels.listallafterload
zzconfiguration.nameddebuglevels.eachquery
zzconfiguration.allvaluessummary
zzconfiguration.progress
zzconfiguration.templateoverrides.allentriespostloaded
zzconfiguration.templateoverrides.eachentryasloaded

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

Enum Constant Summary

Enum Constants

Enum Constant and Description
INSTANCE

Field Summary

Fields

Modifier and Type	Field and Description
static String	BASE_CONFIG_FILE_NAME The name of the "base" configuration file--Equal to "codelet.properties".
static String	CODELET_CONFIG_DIR_SYS_PROP_NAME The name of the system property that is passed into the javadoc application, whose value is the directory in which all Codelet configuration files are stored--Equal to "codelet_config_dir".
static String	CODELET_RQD_NAMED_DBGRS_CONFIG_FILE The name of the configuration file containing Codelet-required named debuggers--Equal to "named_debuggers_config_CODELET_RQD.txt".
static String	EXTERNAL_DOC_ROOT_URL_FILE The name of the file in which all external {@docRoot} urls are listed--Equal to "external_doc_root_urls.txt".
static String	NAMED_DEBUGGERS_CONFIG_FILE The name of the configuration file containing user-created named-debugging-levels--Equal to "named_debuggers_config.txt".
static String	TMPL_OVERRIDES_CONFIG_FILE_NAME The name of the template-overrides configuration file--Equal to "template_overrides_config.txt".

Method Summary

Methods

Modifier and Type	Method and Description
static String	getCodeletConfigDir() The directory in which all Codelet configuration files exist, as passed in via the javadoc.exe system property named "codelet_config_dir".
static CodeletBootstrap	valueOf(String name) Returns the enum constant of this type with the specified name.
static CodeletBootstrap[]	values() Returns an array containing the constants of this enum type, in the order they are declared.
static boolean	wasLoaded() Was all Codelet configuration properly loaded?.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

INSTANCE

public static final CodeletBootstrap INSTANCE

Field Detail

CODELET_CONFIG_DIR_SYS_PROP_NAME

public static final String CODELET_CONFIG_DIR_SYS_PROP_NAME

The name of the system property that is passed into the javadoc application, whose value is the directory in which all Codelet configuration files are stored--Equal to "codelet_config_dir".

codelet.properties, template_overrides_config.txt, and "external_doc_root_urls.txt" must all be in this directory.

See Also:

CodeletBootstrap, getCodeletConfigDir(), Constant Field Values

BASE_CONFIG_FILE_NAME

public static final String BASE_CONFIG_FILE_NAME

The name of the "base" configuration file--Equal to "codelet.properties".

See Also:

TMPL_OVERRIDES_CONFIG_FILE_NAME, CodeletBaseConfig, Constant Field Values

NAMED_DEBUGGERS_CONFIG_FILE

public static final String NAMED_DEBUGGERS_CONFIG_FILE

The name of the configuration file containing user-created named-debugging-levels--Equal to "named_debuggers_config.txt".

(View {@docRoot}/../codelet_config/named_debuggers_config.txt.)

This file contains a list of zero or more names, each of which is associated to a specific debugging task and level. These are in addition to those in the Codelet-required configuration file.

Named debuggers allow for very specific control over what information is logged, without having to recompile code. In particular, named debuggers are useful for debugging custom customizers.

All possible level numbers:

• -1: Never output.
• 0: Always output (even if OFF).
• 1: Output only when the actual level on--equal to or greater than ONE.
• 2: Output when the actual level is TWO or greater.
• 3: Output when the actual level is THREE or greater.
• 4: Output when the actual level is FOUR or FIVE.
• 5: Output only when the actual level is FIVE.

Example

Add this line to "named_debuggers_config.txt":

super.important.debugginginformation=2

Then associate specific debugging statements to it:

if(isDebugOn("super.important.debugginginformation", null)) { debugln("Super-duper important!") }

(Unless otherwise noted, all below "See" links are located in CodeletBaseConfig.)

See Also:

NamedDebuggers#newMapFromConfigFile, GLOBAL_DEBUG_LEVEL, isDebugOn(s,ci), getDebugApblIfOn(ci,s), getDebugAptrIfOn(ci,s), Constant Field Values

CODELET_RQD_NAMED_DBGRS_CONFIG_FILE

public static final String CODELET_RQD_NAMED_DBGRS_CONFIG_FILE

The name of the configuration file containing Codelet-required named debuggers--Equal to "named_debuggers_config_CODELET_RQD.txt".

(View {@docRoot}/../codelet_config/named_debuggers_config_CODELET_RQD.txt.)

This file contains a list of names, each of which is associated to a specific debugging task and level. These are in addition to those in the user-created configuration file.

Changing the level numbers in this file allows you to print or suppress very specific aspects of debugging information that is already built into Codelet. Warning: Changing the names of any level in this file will result in an error. All Codelet-required levels are prefixed with "zz".

An example of a function taking advantage of named debuggers is
BasicCustomizers.lineRange.

See Also:

NAMED_DEBUGGERS_CONFIG_FILE, NamedDebuggers#newMapFromConfigFile, Constant Field Values

EXTERNAL_DOC_ROOT_URL_FILE

public static final String EXTERNAL_DOC_ROOT_URL_FILE

The name of the file in which all external {@docRoot} urls are listed--Equal to "external_doc_root_urls.txt".

These urls are the directories in which an external JavaDoc library's package-list file exists. Each url must end with a slash: '/'.

Each package-list file is also stored locally, in a sub-directory named "offline_package_lists". The offline files are automatically used when the online version is not accessible or available. These files may be manually created and, if configured, are automatically updated.

Each line is in the format

[offline_file_name_prefix] [url]

Where

• [offline_file_name] is the name of the locally-stored file (aside from ".txt"), which exists in a sub-directory named "offline_package_lists". This is in the same directory as this "external_doc_root_urls.txt" file. Must only contain letters, digits, and underscores ('_').
• [url] is the url to the JavaDoc document root ("{@docRoot}") of an external Java library. Must end with a slash ('/'), and must contain the library's "package-list" file.

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

Example file

templatefeather     http://aliteralmind.com/docs/computer/programming/templatefeather/documentation/javadoc/
xbnjava             http://aliteralmind.com/docs/computer/programming/xbnjava/documentation/javadoc/
commons_collections http://commons.apache.org/proper/commons-collections/javadocs/api-release/
commons_io          http://commons.apache.org/proper/commons-io/javadocs/api-2.4/
commons_lang        http://commons.apache.org/proper/commons-lang/javadocs/api-release/
java                http://docs.oracle.com/javase/7/docs/api/
javadoc             http://docs.oracle.com/javase/7/docs/jdk/api/javadoc/doclet/
junit               http://junit.sourceforge.net/javadoc/

If the path of "external_doc_root_urls.txt" is
C:\java_code\my_package\codelet_config\external_doc_root_urls.txt
then the path to the "commons_io" offline package-list is
C:\java_code\my_package\codelet_config\offline_package_lists\commons_io.txt
The ".txt" postfix is customizable.

(View {@docRoot}/../codelet_config/external_doc_root_urls.txt.)

This configuration file is loaded by AllOnlineOfflineDocRoots.newFromConfigLineIterator

Related (all in CodeletBaseConfig):

• pkglist_online_attempt_sleep_mills: The pause between each attempt.
• pkglist_if_online_retrieval_fails__warn_crash: The behavior after all attempts fail
• pkglist_auto_refresh_offline__yes_no: After successfully retrieved, should the packages in its offline counterpart be refreshed?
• pkglist_offline_name_postfix: The postfix added to each offline-name in the configuration file.
• CodeletBaseConfig.OFFLINE_PACKAGE_LIST_DIR_NAME: The name of the sub-directory, existing in the main Codelet configuration directory, in which offline package lists are stored.

See Also:

NewJavaDocLinkReplacerFor#getDocRootUrlToTargetClass, util.AllOnlineOfflineDocRoots#newFromConfigLineIterator, Constant Field Values

TMPL_OVERRIDES_CONFIG_FILE_NAME

public static final String TMPL_OVERRIDES_CONFIG_FILE_NAME

The name of the template-overrides configuration file--Equal to "template_overrides_config.txt".

See Also:

BASE_CONFIG_FILE_NAME, TemplateOverrides, Constant Field Values

Method Detail

values

public static CodeletBootstrap[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (CodeletBootstrap c : CodeletBootstrap.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static CodeletBootstrap valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

wasLoaded

public static final boolean wasLoaded()

Was all Codelet configuration properly loaded?.

Returns:

TemplateOverrides.wasLoaded()

getCodeletConfigDir

public static final String getCodeletConfigDir()

The directory in which all Codelet configuration files exist, as passed in via the javadoc.exe system property named "codelet_config_dir".

See Also:

CODELET_CONFIG_DIR_SYS_PROP_NAME