com.github.aliteralmind.codelet

Class TagletOfTypeProcessor<T extends CodeletTemplateBase>

java.lang.Object

com.github.aliteralmind.codelet.TagletOfTypeProcessor<T>

Direct Known Subclasses:

ConsoleOutProcessor, FileTextProcessor, SourceAndOutProcessor, SourceCodeProcessor

public class TagletOfTypeProcessor<T extends CodeletTemplateBase>
extends Object

Base class for type-specific Codelet processors. Called by TagletProcessor.

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

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_CUSTOMIZER_CLASS_NAME The name of the class in each package that uses codelets, that is the "fallback" location for IXC-customizers--Equal to "zCodeletCustomizers".

Constructor Summary

Constructors

Constructor and Description
TagletOfTypeProcessor(CodeletType sub_classType, CodeletInstance instance) Create a new instance.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	crashIfClassOrFileCannotUseCustomizer(CustomizationInstructions<T> instructions) If the class or file is not allowed to use the customizer, crash.
String	getClassOrFilePortion() The example code's fully-qualified class name (plus any command-line parameters), or the path to the plain-text file.
CustomizationInstructions<T>	getCustomCustomizationInstructions(CodeletType needed_defaultAlterType)
CustomizationInstructions<T>	getCustomizationInstructions(CodeletType needed_defaultAlterType)
String	getCustomizerPortion() The optional customizer part of a codelet, as found after its prefix character.
SimpleMethodSignature	getCustomizerSigFromString(String customizer_strSig) Given the customizer's fully-expanded string-signature, get its simple-signature.
String	getExampleCodeStringSig() Get the string-signature for executing the example code.
String	getFullyCustomizedOutput()
CodeletInstance	getInstance() The current taglet instance.
CustomizationInstructions<T>	getInstructionsFromSig(SimpleMethodSignature customizer_sig, CodeletType needed_defaultAlterType) Invoke the customizer and get its return value, as required by the taglet-processor--For {@.codelet.and.out} taglets only.
protected String	getSig2PrnsApnddForNameOrPostfix(String betweenPre_andPostInclUndrScr, String sig, boolean do_debug)
Iterator<String>	getSourceCodeLineIterator(CodeletInstance instance)
String	getStringSignature() Expands a potentially-shortened customizer signature (shortcut) to its full string-signature, for {@.codelet} and {@.codelet.out} taglets only.
T	getTemplateFromInstructionsOverrideOrDefault(CustomizationInstructions<T> instructions)
CustomizationInstructions<T>	newInstructionsForDefaults(CustomizationInstructions<T> instructions)
protected void	setFullyProcessedOutput(String fully_processed)

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CUSTOMIZER_CLASS_NAME

public static final String DEFAULT_CUSTOMIZER_CLASS_NAME

The name of the class in each package that uses codelets, that is the "fallback" location for IXC-customizers--Equal to "zCodeletCustomizers". This class is only applicable for customizers that are

• Not in BasicCustomizers,
• Not in the taglet's enclosing class, and
• Not explicitely specified in the taglet's text (after the customizer prefix character).

See Also:

Constant Field Values

Constructor Detail

TagletOfTypeProcessor

public TagletOfTypeProcessor(CodeletType sub_classType,
                     CodeletInstance instance)

Create a new instance.

Steps:

1. If a Codelet customizer is
   • specified (meaning its prefix character is found anywhere in tag_text), this sets
     1. getClassOrFilePortion() to the text preceding the prefix char.
     2. getCustomizerPortion() to the text following it.
   • Not specified, this sets
     1. getClassOrFilePortion() to instance.getText().
     2. getCustomizerPortion() to null.

Parameters:

sub_classType - The taglet type of the sub-class. May not be null. Discarded after construction.

instance - May not be null, and its type must be the same as sub_classType. Get with getInstance().

Throws:

NoSuchMethodException - If the customizer function does not exist, either in the specified or default classes, or with the required attributes, such as missing parameters, an unexpected return value, or if it's non-static.

NoSuchFileException - If the source-code or plain-text file does not exist.

AccessDeniedException - If the file exists, but cannot be read.

Method Detail

getInstance

public CodeletInstance getInstance()

The current taglet instance.

See Also:

TagletOfTypeProcessor(CodeletType, CodeletInstance)

getClassOrFilePortion

public String getClassOrFilePortion()

The example code's fully-qualified class name (plus any command-line parameters), or the path to the plain-text file. This is the portion of the taglet's text that follows the name and precedes the optional customizer prefix character. If no customizer is specified, this is equal to getInstance().getText()

See Also:

TagletOfTypeProcessor(CodeletType, CodeletInstance)

crashIfClassOrFileCannotUseCustomizer

protected void crashIfClassOrFileCannotUseCustomizer(CustomizationInstructions<T> instructions)

If the class or file is not allowed to use the customizer, crash. Otherwise, do nothing.

Throws:

IllegalStateException - If
FilenameUtils.wildcardMatch(getClassOrFilePortion(), instructions.getClassNameOrFilePathRestricter)
is false.

getCustomizerPortion

public String getCustomizerPortion()

The optional customizer part of a codelet, as found after its prefix character. If no customizer is specified, this is null.

See Also:

TagletOfTypeProcessor(CodeletType, CodeletInstance), CodeletInstance#CUSTOMIZER_PREFIX_CHAR

getFullyCustomizedOutput

public String getFullyCustomizedOutput()

setFullyProcessedOutput

protected void setFullyProcessedOutput(String fully_processed)

getTemplateFromInstructionsOverrideOrDefault

public T getTemplateFromInstructionsOverrideOrDefault(CustomizationInstructions<T> instructions)

getExampleCodeStringSig

public String getExampleCodeStringSig()

Get the string-signature for executing the example code.

Returns:

clsNm + "#main(" + params + ")"
Where clsNm is
TagletTextUtil.getExampleClassFQName(instance)
and params is
TagletTextUtil.getExampleCommandLineParams(instance)

getCustomCustomizationInstructions

public CustomizationInstructions<T> getCustomCustomizationInstructions(CodeletType needed_defaultAlterType)
                                                                                            throws ClassNotFoundException,
                                                                                                   NoSuchMethodException,
                                                                                                   SecurityException

Throws:

ClassNotFoundException

NoSuchMethodException

SecurityException

getInstructionsFromSig

public CustomizationInstructions<T> getInstructionsFromSig(SimpleMethodSignature customizer_sig,
                                                  CodeletType needed_defaultAlterType)
                                                                                throws ClassNotFoundException,
                                                                                       NoSuchMethodException,
                                                                                       SecurityException

Invoke the customizer and get its return value, as required by the taglet-processor--For {@.codelet.and.out} taglets only.

This obtains and then invokes the customizer signature, and returns its return value, which must be a CustomizationInstructions of the type required by the processor.

Parameters:

customizer_sig - May not be null, and the function in represents must conform to the requirements.

Throws:

IllegalArgumentException - If
[the-instructions-returned-by-the-customizer].getNeededAlterArrayType()
is different than needed_defaultAlterType. See
CustomizationInstructions.CustomizationInstructions(CodeletInstance, CodeletType)

ClassNotFoundException

NoSuchMethodException

SecurityException

getCustomizerSigFromString

public SimpleMethodSignature getCustomizerSigFromString(String customizer_strSig)
                                                 throws ClassNotFoundException

Given the customizer's fully-expanded string-signature, get its simple-signature.

Steps:

1. If there is no customizer: This returns null.
2. If the fully-qualified class-name, in which the customizer function exists, is
   • not specified (before the '#'): The following classes are set as its defaults, one in which the customizer function must exist (although that's verified externally--not by this function). They are search in order:
     1. BasicCustomizers
     2. The taglet's enclosing class
     3. And if it exists: The enclosing package's default processor class.
   • Returns a new simple signature

Parameters:

customizer_strSig - The expanded string-signature. If null, no customizer is specified.

Throws:

ClassNotFoundException - If the class name, but not its package, is in the string-signature, and the class does not exist in the enclosing package.

See Also:

getStringSignature()

getStringSignature

public String getStringSignature()

Expands a potentially-shortened customizer signature (shortcut) to its full string-signature, for {@.codelet} and {@.codelet.out} taglets only. This does not validate the taglet text or the returned signature.

Steps:

1. If no customizer is in the taglet, this returns null.
2. If it is equal to "()", this returns the default Codelet customizer function name
   1. The taglet-type's default prefix
   2. The example classes simple name (the text after the final dot: '.' in the example code's fully-qualified class name).
   3. "()"
   Example: "getSourceConfigAGreatExample()"
3. If the line-proc starts with an underscore ('_'), it is the function name's postfix, which is appended after the classes simple name. This returns (for example)
   "getSourceConfigAGreatExample_DoSpecialStuff()"
4. This returns the line-proc portion of the taglet's text unchanged.

In all cases, if there are no paremeters specified, empty parentheses are appended to the signature: "()"

getSig2PrnsApnddForNameOrPostfix

protected String getSig2PrnsApnddForNameOrPostfix(String betweenPre_andPostInclUndrScr,
                                      String sig,
                                      boolean do_debug)

newInstructionsForDefaults

public CustomizationInstructions<T> newInstructionsForDefaults(CustomizationInstructions<T> instructions)

getSourceCodeLineIterator

public Iterator<String> getSourceCodeLineIterator(CodeletInstance instance)

getCustomizationInstructions

public CustomizationInstructions<T> getCustomizationInstructions(CodeletType needed_defaultAlterType)
                                                                                      throws ClassNotFoundException,
                                                                                             NoSuchMethodException,
                                                                                             NoSuchFileException,
                                                                                             AccessDeniedException

Throws:

ClassNotFoundException

NoSuchMethodException

NoSuchFileException

AccessDeniedException