cox.jmatt.java.MathTools.markup
Class Tag

java.lang.Object
  extended by cox.jmatt.java.MathTools.markup.Tag
Direct Known Subclasses:
BaseHTag, SimpleTagImpl, StyleTag

public abstract class Tag
extends java.lang.Object

This class provides the basic machinery required to generate an XML tag. It tracks the tag name and attributes. No content is tracked but two methods are provided for handling it: _content() and _setcontent(). The default implementations return null and do nothing, respectively. Subclasses can override these methods if they have content to handle. The toString() method returns the data in String form, intelligently. If there is no content the attributes are returned in an empty tag. If there is content the return value is an opening tag, content, and a closing tag. Attributes can be added in an intelligent fashion; if the value is null or blank the value stored for that attribute key (if any) is removed. Numeric attributes have two add methods, one that simply adds the number and the other that allows value-clamping. Unlike the standard methods these two ignore null numeric values and simply return true.

In addition to the instance methods Tag also contains factory methods to create an optionally-empty opening tag and closing tag. No XML escaping is done so it must be handled manually.

This class is meant to serve as the superclass of any XML tag. There are no external dependencies, DOM or otherwise, and the methods work by operating on Strings. The internal data is handled automatically so only the tag name must be handled by the subclass. There is no public constructor and the only other one is protected and absolutely requires a tag name be given. If necessary a copy of the attributes Hashtable can be returned but this is only a copy; the original is never exposed directly.


Field Summary
protected  java.lang.String myTagName
          The current tag name.
 
Constructor Summary
protected Tag(java.lang.String pName)
          This constructor is used to create a named Tag.
 
Method Summary
protected  boolean _addAttribute(java.lang.String pKey, java.lang.String pValue)
          Add an attribute to the current tag, or remove one.
protected  void _addAttributes(java.util.Hashtable<java.lang.String,java.lang.String> pNewAtts)
          Add a Hashtable full of attributes.
protected  boolean _addNAttribute(java.lang.String pKey, java.lang.Number pVal)
          Add an attribute whose value is a java.lang.Number.
protected  boolean _asBoolean(java.util.Properties pPizza, java.lang.String pPrefix, java.lang.String pKey)
          Convenience method to extract and check a boolean key.
protected  java.lang.Double _asDouble(java.util.Properties pPizza, java.lang.String pPrefix, java.lang.String pKey, java.lang.Double pDefault)
          Convenience method to extract and return a Double (object!) from a parameter.
protected  java.lang.Integer _asInt(java.util.Properties pPizza, java.lang.String pPrefix, java.lang.String pKey, java.lang.Integer pDefault)
          Extract and return an Integer-object or a default if it is not found.
 java.util.Hashtable<java.lang.String,java.lang.String> _attributes()
          Return a copy of the tag's attributes.
protected  boolean _clampNAttribute(java.lang.String pKey, java.lang.Number pValue, java.lang.Double pMin, java.lang.Double pMax)
          Convenience method for _clampNAttribute(pKey, pValue, pMin, pMax, false).
protected  boolean _clampNAttribute(java.lang.String pKey, java.lang.Number pValue, java.lang.Double pMin, java.lang.Double pMax, boolean bRemoveIfNull)
          Add a 'clamped' attribute; one whose value is a java.lang.Number and whose value must fall between a maximum and minumum, both expressed as Double.
protected  java.lang.String _content()
          This method is meant to provide access to the tag's content, if any.
protected  java.lang.String _fixKey(java.lang.String pPrefix, java.lang.String pKey)
          This is a convenience method to format prefixes and keys.
protected  void _setContent(java.lang.String pContent)
          If the _content() method is overriden this one should be as well.
protected  void _setEnableXMLTag(boolean pEnable)
          Use this method to enable or disable (default) the '<?xml ...
static boolean badPizza(java.util.Properties pPizza)
          Return 'false' if the Properties objet is null or empty.
static java.lang.String closeTag(java.lang.String pName)
          Close the tag specified.
 void configureTag(java.lang.String pPrefix, java.util.Properties pConfigData)
          This is a generic default-configuration method.
 void configureTagFromGlobalPizza(java.lang.String pPrefix)
          Configure the tag from the Global Pizza.
static java.lang.String makeTag(java.lang.String pName, java.util.Hashtable<java.lang.String,java.lang.String> pAtts, java.lang.String pContent)
          Create a tag pair with all data supplied: name, attributes, and content.
static java.lang.String openTag(java.lang.String pName, java.util.Hashtable<java.lang.String,java.lang.String> pAtts, boolean isEmpty)
          This method creates an opening XML tag with the name and attributes provided.
 void reset()
          Clear all data except the tag name.
 void setID(java.lang.String pID)
          Set the 'id=' attribute of the tag.
 java.lang.String toString()
          Generate a tag or tag pair from the internal data.
static boolean validString(java.lang.String pStr)
          This is identical to Question.validString() but is repeated here for convenience.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

myTagName

protected java.lang.String myTagName
The current tag name. This must NEVER be null and should not be changed without a very good reason! It is protected to allow such 'good reason' cases.

Constructor Detail

Tag

protected Tag(java.lang.String pName)
This constructor is used to create a named Tag.

Method Detail

openTag

public static final java.lang.String openTag(java.lang.String pName,
                                             java.util.Hashtable<java.lang.String,java.lang.String> pAtts,
                                             boolean isEmpty)
This method creates an opening XML tag with the name and attributes provided.

Parameters:
pName - The name of the opening tag; if null or blank it is 'Tag'.
pAtts - The attributes to add to the tag.
isEmpty - true if the tag should be self-closed, false otherwise.

closeTag

public static final java.lang.String closeTag(java.lang.String pName)
Close the tag specified. If the name is null or blank the closed tag is 'Tag'.


makeTag

public static final java.lang.String makeTag(java.lang.String pName,
                                             java.util.Hashtable<java.lang.String,java.lang.String> pAtts,
                                             java.lang.String pContent)
Create a tag pair with all data supplied: name, attributes, and content. If the content is blank or null an empty tag is returned.

Parameters:
pName - The name of the tag to create.
pAtts - The attributes for the opening tag.
pContent - The String content of the tag.

validString

public static final boolean validString(java.lang.String pStr)
This is identical to Question.validString() but is repeated here for convenience.


_addAttribute

protected final boolean _addAttribute(java.lang.String pKey,
                                      java.lang.String pValue)

Add an attribute to the current tag, or remove one. If the key is null or blank the method returns false immediately. If the key is valid but the value is null or blank the value stored under that key is removed; if an attribute was removed the method returns true, if the mapping didn't exist it returns false. If both the key and value are valid the attribute is added.

This method is protected to prevent automatic addition of arbitrary attributes.

Parameters:
pKey - The name of the attribute to add.
pValue - The value of the attribute, or null to remove it.

_addNAttribute

protected final boolean _addNAttribute(java.lang.String pKey,
                                       java.lang.Number pVal)
Add an attribute whose value is a java.lang.Number. Unlike the _addAttribute() method this one ignores null values and returns true when one is set. A null or blank key still returns false.


_clampNAttribute

protected final boolean _clampNAttribute(java.lang.String pKey,
                                         java.lang.Number pValue,
                                         java.lang.Double pMin,
                                         java.lang.Double pMax,
                                         boolean bRemoveIfNull)
Add a 'clamped' attribute; one whose value is a java.lang.Number and whose value must fall between a maximum and minumum, both expressed as Double. If the max or min is null it is ignored. For non-null limits, if the Number is greater than the maximum or less than the minimum it is replaced by that limit. NOTE: This method does not check to see if the minimum is in fact less than the maximum!

Parameters:
pKey - The name of the attribute to set. If null, the method returns false.
pValue - The numeric value to be clamped.
pMin - The minimum value allowed, ignored if null.
pMax - The maximum value, ignored if null.
bRemoveIfNull - true to remove attributes with null values, false to ignore and return true.

_clampNAttribute

protected final boolean _clampNAttribute(java.lang.String pKey,
                                         java.lang.Number pValue,
                                         java.lang.Double pMin,
                                         java.lang.Double pMax)
Convenience method for _clampNAttribute(pKey, pValue, pMin, pMax, false).


_attributes

public final java.util.Hashtable<java.lang.String,java.lang.String> _attributes()
Return a copy of the tag's attributes. The original is left untouched. If no attributes are set an empty but non-null Hashtable is returned.


_addAttributes

protected final void _addAttributes(java.util.Hashtable<java.lang.String,java.lang.String> pNewAtts)
Add a Hashtable full of attributes. Ignored if null or empty.


_content

protected java.lang.String _content()
This method is meant to provide access to the tag's content, if any. The default implementation returns null; subclasses that may contain content should override this method to provide appropriate functionality.


_setContent

protected void _setContent(java.lang.String pContent)
If the _content() method is overriden this one should be as well. It provides a method to set content. This implementation is empty. Subclasses defining this method must be able to handle a null argument since this is how the reset() method clears it.


reset

public void reset()
Clear all data except the tag name. Any attributes will be lost. This method does call _setContent(null) and reset the XML declaration to false.


configureTag

public void configureTag(java.lang.String pPrefix,
                         java.util.Properties pConfigData)

This is a generic default-configuration method. The implementation here is empty but it is provided for subclasses.

The theory behind the method is that a Tag subclass can search through the Properties object and select information relevant to itself. No input validation or other checking is done, that is the responsibility of the subclass. Subclasses defining this method must supply ALL relevant details and documentation!

The prefix is supplied to allow multiple configurations to be stored in a single file. If used, pizza-configurable tags will prepend the prefix to all configuration keys. Overridden methods should check to see that a valid (non-null, non-blank) prefix ends with a dot character ('.') and if not, supply one automatically.

Parameters:
pConfigData - A Properties object holding configuration data for the subclass instance.

configureTagFromGlobalPizza

public void configureTagFromGlobalPizza(java.lang.String pPrefix)
Configure the tag from the Global Pizza. The prefix is passed through unaltered.


_fixKey

protected java.lang.String _fixKey(java.lang.String pPrefix,
                                   java.lang.String pKey)

This is a convenience method to format prefixes and keys. If the prefix is null or blank it is ignored, otherwise it is checked to see if it ends with a dot. If not one is attached, the key is appended and the entire thing returned. If the key value is null or blank a blank String is returned.

Parameters:
pPrefix - The prefix to attach to the key or ignore if null or blank.
pKey - The value of the key.

_asBoolean

protected boolean _asBoolean(java.util.Properties pPizza,
                             java.lang.String pPrefix,
                             java.lang.String pKey)

Convenience method to extract and check a boolean key. If the (case-insensitive) value of the prefix-key combination is 'true' the method returns true, otherwise it returns false.

Parameters:
pPizza - The pizza to check. If null or empty the method returns false.
pPrefix - The key prefix.
pKey - The value of the key to check.

_asDouble

protected java.lang.Double _asDouble(java.util.Properties pPizza,
                                     java.lang.String pPrefix,
                                     java.lang.String pKey,
                                     java.lang.Double pDefault)

Convenience method to extract and return a Double (object!) from a parameter. ANY errors are silently ignored. If the key requested is not present or cannot be parsed as a double the default value is returned.


_asInt

protected java.lang.Integer _asInt(java.util.Properties pPizza,
                                   java.lang.String pPrefix,
                                   java.lang.String pKey,
                                   java.lang.Integer pDefault)

Extract and return an Integer-object or a default if it is not found.


badPizza

public static boolean badPizza(java.util.Properties pPizza)
Return 'false' if the Properties objet is null or empty. Laziness method.


setID

public void setID(java.lang.String pID)
Set the 'id=' attribute of the tag. Included in this class since it is so common among XML tags. Setting null removes it.


_setEnableXMLTag

protected final void _setEnableXMLTag(boolean pEnable)
Use this method to enable or disable (default) the '<?xml ... ?>' declaration. If enabled it prints before the tag opens. If this is enabled it only lasts for ONE toString() call, afterward it resets to false and must be re-enabled.


toString

public java.lang.String toString()
Generate a tag or tag pair from the internal data. If there is content it is printed, enclosed by opening and closing tags. If the XML declaration tag is enabled it appears before the opening tag and calling this method resets it to false.

Overrides:
toString in class java.lang.Object