buri.ddmsence

Class AbstractBaseComponent

Object

buri.ddmsence.AbstractBaseComponent

All Implemented Interfaces:

IDDMSComponent

Direct Known Subclasses:

AbstractAccessEntity, AbstractNtkString, AbstractProducerRole, AbstractQualifierValue, AbstractRoleEntity, AbstractSimpleString, AbstractTaskingRole, AbstractTspiAddress, AbstractTspiShape, Access, ApproximableDate, BoundingBox, BoundingGeometry, Category, Dates, ExtensibleElement, FacilityIdentifier, Format, GeographicIdentifier, GeospatialCoverage, Keyword, Link, MetacardInfo, Notice, NoticeList, Point, Polygon, Position, PostalAddress, ProductionMetric, ProfileList, RecordKeeper, RecordsManagementInfo, Resource, ResourceManagement, RevisionRecall, Rights, Security, SubjectCoverage, TaskID, TaskingInfo, TemporalCoverage, VerticalExtent, VirtualCoverage

public abstract class AbstractBaseComponent
extends Object
implements IDDMSComponent

Top-level base class for all DDMS elements and attributes modeled as Java objects.

In DDMS

2.0

3.0

3.1

4.0.1/4.1

5.0

Extensions of this class are generally expected to be immutable, and the underlying XOM element MUST be set before the component is used. It is assumed that after the constructor on a component has been called, the component will be well-formed and valid.

History
None.

Nested Elements
Name Cardinality Availability None. Extending classes may have additional elements.

Attributes
Name Cardinality Availability None. Extending classes may have additional attributes.

Validation Rules

Rule Type Applicability The component has a name. Error In DDMS 2.0 3.0 3.1 4.0.1/4.1 5.0 All child components use the same version of DDMS as this component. Error In DDMS 2.0 3.0 3.1 4.0.1/4.1 5.0 Warnings from any child components are claimed by this component. Warning In DDMS 2.0 3.0 3.1 4.0.1/4.1 5.0 Warnings from any security attributes are claimed by this component. Warning In DDMS 2.0 3.0 3.1 4.0.1/4.1 5.0

Since:

0.9.b

Author:

Brian Uri!

Field Summary

Fields

Modifier and Type	Field and Description
static Map<OutputFormat,String>	OUTPUT_TEMPLATES

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractBaseComponent() Empty constructor
protected	AbstractBaseComponent(nu.xom.Element element) Base constructor

Method Summary

Modifier and Type	Method and Description
protected void	addDdms40Warning(String component) Adds a warning about a component which is used in a valid manner, but may cause issues with systems that only process an earlier DDMS version with the same namespace.
protected static void	addJson(com.google.gson.JsonObject object, AbstractAttributeGroup value) Adds an attribute group's JSON object to a JSON object, but only if it is not empty.
protected static void	addJson(com.google.gson.JsonObject object, AbstractBaseComponent value) Adds a DMMS component's JSON object to a JSON object.
protected static void	addJson(com.google.gson.JsonObject object, String name, List<?> value) Adds a list of values to a JSON object, but only if it is not empty and not null.
protected static void	addJson(com.google.gson.JsonObject object, String name, Object value) Adds a value to a JSON object, but only if it is not empty and not null.
protected void	addWarning(String text) Convenience method to create a warning and add it to the list of validation warnings.
protected void	addWarnings(List<ValidationMessage> warnings, boolean forAttributes) Convenience method to add multiple warnings to the list of validation warnings.
protected String	buildHTMLTextOutput(OutputFormat format, String prefix, List<?> contents) Convenience method to build a meta tag for HTML output or a text line for Text output for a list of multiple DDMS components.
static String	buildHTMLTextOutput(OutputFormat format, String name, String content) Convenience method to build a meta tag for HTML output or a text line for Text output.
protected String	buildIndex(int index, int total) Constructs a braced 1-based index to differentiate multiples in HTML/Text output, based on the 0-based list index of the item, and the output.indexLevel configurable property.
protected String	buildPrefix(String prefix, String token, String suffix) Convenience method to construct a naming prefix for use in HTML/Text output
boolean	equals(Object obj) Test for logical equality.
protected String	getAttributeValue(String name) Convenience method to look up an attribute which is in the same namespace as the enclosing element
protected String	getAttributeValue(String name, String namespaceURI) Convenience method to look up an attribute
protected nu.xom.Element	getChild(String name) Convenience method to get the first child element with a given name in the same namespace as the parent element
protected static Double	getChildTextAsDouble(nu.xom.Element element, String name) Convenience method to convert one of the lat/lon fields into a Double.
protected DDMSVersion	getDDMSVersion() Returns the most recent compatible DDMSVersion for this component, based on the XML Namespace.
abstract String	getHTMLTextOutput(OutputFormat format, String prefix, String suffix) Renders this component as HTML or Text, with an optional prefix to nest it.
abstract com.google.gson.JsonObject	getJSONObject() Renders this component as a JSON object, which can either be converted to a JSON string or inserted into the parent JSON object.
protected String	getLocatorSuffix() Can be overridden to change the locator string used in warnings and errors.
String	getName() Will return an empty string if the element is not set, but this cannot occur after instantiation.
String	getNamespace() Will return an empty string if the element is not set, but this cannot occur after instantiation.
protected List<IDDMSComponent>	getNestedComponents() Accessor for a collection of nested components.
String	getPrefix() Will return an empty string if the element is not set, but this cannot occur after instantiation.
String	getQualifiedName() Will return an empty string if the element is not set, but this cannot occur after instantiation.
SecurityAttributes	getSecurityAttributes() The base implementation of a DDMS component assumes that there are no security attributes.
List<ValidationMessage>	getValidationWarnings() Returns a list of any warning messages that occurred during validation.
protected nu.xom.Element	getXOMElement() Accessor for the XOM element representing this component
nu.xom.Element	getXOMElementCopy() Accessor for a copy of the underlying XOM element
int	hashCode() Returns a hashcode for the component.
protected void	requireAtLeastVersion(String version) Helper method to validate that a specific version of DDMS (or higher) is being used.
protected void	requireAtMostVersion(String version) Helper method to validate that a specific version of DDMS (or lower) is being used.
protected void	setXOMElement(nu.xom.Element element, boolean validateNow) Accessor for the XOM element representing this component.
String	toHTML() Renders this component as HTML.
String	toJSON() Renders this component as JSON.
String	toString() Returns the XML representation of the component
String	toText() Renders this component as Text.
String	toXML() Will return an empty string if the name is not set, but this cannot occur after instantiation.
protected void	validate() Base case for validation.
protected void	validateWarnings() Base case for warnings.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

OUTPUT_TEMPLATES

public static final Map<OutputFormat,String> OUTPUT_TEMPLATES

Constructor Detail

AbstractBaseComponent

protected AbstractBaseComponent()
                         throws InvalidDDMSException

Empty constructor

Throws:

InvalidDDMSException

AbstractBaseComponent

protected AbstractBaseComponent(nu.xom.Element element)
                         throws InvalidDDMSException

Base constructor

Parameters:

element - the XOM element representing this component

Throws:

InvalidDDMSException

Method Detail

getPrefix

public String getPrefix()

Will return an empty string if the element is not set, but this cannot occur after instantiation.

Specified by:

getPrefix in interface IDDMSComponent

Returns:

the prefix

See Also:

IDDMSComponent.getPrefix()

getName

public String getName()

Will return an empty string if the element is not set, but this cannot occur after instantiation.

Specified by:

getName in interface IDDMSComponent

Returns:

the name, without prefix

See Also:

IDDMSComponent.getName()

getNamespace

public String getNamespace()

Will return an empty string if the element is not set, but this cannot occur after instantiation.

Specified by:

getNamespace in interface IDDMSComponent

Returns:

the namespace

See Also:

IDDMSComponent.getNamespace()

getQualifiedName

public String getQualifiedName()

Will return an empty string if the element is not set, but this cannot occur after instantiation.

Specified by:

getQualifiedName in interface IDDMSComponent

Returns:

the name, with prefix if available

See Also:

IDDMSComponent.getQualifiedName()

getSecurityAttributes

public SecurityAttributes getSecurityAttributes()

The base implementation of a DDMS component assumes that there are no security attributes. Components with attributes should override this.

Specified by:

getSecurityAttributes in interface IDDMSComponent

getValidationWarnings

public List<ValidationMessage> getValidationWarnings()

Description copied from interface: IDDMSComponent

Returns a list of any warning messages that occurred during validation. Warnings do not prevent a valid component from being formed. A parent component should also claim the warnings of its child elements.

Specified by:

getValidationWarnings in interface IDDMSComponent

Returns:

a list of warnings

See Also:

IDDMSComponent.getValidationWarnings()

validate

protected void validate()
                 throws InvalidDDMSException

Base case for validation. This method can be overridden for more in-depth validation. It is always assumed that the subcomponents of a component are already valid.

Throws:

InvalidDDMSException

validateWarnings

protected void validateWarnings()

Base case for warnings. This method can be overridden for more in-depth validation. It is always assumed that the subcomponents of a component are already valid.

addDdms40Warning

protected void addDdms40Warning(String component)

Adds a warning about a component which is used in a valid manner, but may cause issues with systems that only process an earlier DDMS version with the same namespace.

DDMS 4.0 and 4.1 share the same XML namespace, so it is impossible to tell which DDMS version is employed from the XML namespace alone. If an XML instance of a metacard employs a new DDMS 4.1 construct (like the new ntk:Access element in a ddms:metacardInfo element), that XML instance will fail to work in a DDMS 4.0 system.

Parameters:

component - a text description of the component that is being warned about

toHTML

public String toHTML()

Description copied from interface: IDDMSComponent

Renders this component as HTML.

Specified by:

toHTML in interface IDDMSComponent

Returns:

the HTML representation of this component

See Also:

IDDMSComponent.toHTML()

toJSON

public String toJSON()

Description copied from interface: IDDMSComponent

Renders this component as JSON. Use the output.json.prettyPrint property to control pretty printing of the output.

Specified by:

toJSON in interface IDDMSComponent

Returns:

the JSON representation of this component

See Also:

IDDMSComponent.toJSON()

toText

public String toText()

Description copied from interface: IDDMSComponent

Renders this component as Text. Use the output.indexLevel property to add indices to the output.

Specified by:

toText in interface IDDMSComponent

Returns:

the text-based representation of this component

See Also:

IDDMSComponent.toText()

getJSONObject

public abstract com.google.gson.JsonObject getJSONObject()

Renders this component as a JSON object, which can either be converted to a JSON string or inserted into the parent JSON object. Although this method is marked a public, it is only intended to be used internally, and is not part of the IDDMSComponent interface. Use the toJSON() method as the public way to get JSON output.

addJson

protected static void addJson(com.google.gson.JsonObject object,
                              String name,
                              Object value)

Adds a value to a JSON object, but only if it is not empty and not null. This method delegates to Util, so the individual JSON implementations are cleaner.

Parameters:

object - the object to add to

name - the name of the array, if added

value - the value to add

addJson

protected static void addJson(com.google.gson.JsonObject object,
                              String name,
                              List<?> value)

Adds a list of values to a JSON object, but only if it is not empty and not null. This method delegates to Util, so the individual JSON implementations are cleaner.

Parameters:

object - the object to add to

name - the name of the array, if added

value - the value to add, converted into a JSON array

addJson

protected static void addJson(com.google.gson.JsonObject object,
                              AbstractAttributeGroup value)

Adds an attribute group's JSON object to a JSON object, but only if it is not empty. This method delegates to Util, so the individual JSON implementations are cleaner.

Parameters:

object - the object to add to

value - the value to add

addJson

protected static void addJson(com.google.gson.JsonObject object,
                              AbstractBaseComponent value)

Adds a DMMS component's JSON object to a JSON object. This method delegates to Util, so the individual JSON implementations are cleaner.

Parameters:

object - the object to add to

value - the value to add

getHTMLTextOutput

public abstract String getHTMLTextOutput(OutputFormat format,
                                         String prefix,
                                         String suffix)

Renders this component as HTML or Text, with an optional prefix to nest it.

I consider this to be an internal method, that unfortunately must be marked as public to allow cross-package access when generating output. Use toHTML() and toText() as the formal, public methods to generate output.

Parameters:

format - the desired format of this output

prefix - an optional prefix to put on each name.

suffix - an optional suffix to append to each name, such as an index.

Returns:

the representation of this component in the specified format

getNestedComponents

protected List<IDDMSComponent> getNestedComponents()

Accessor for a collection of nested components. A list such as this is useful for bulk actions, such as checking emptiness, equality, generating hash codes, or applying mass validation.

buildHTMLTextOutput

public static String buildHTMLTextOutput(OutputFormat format,
                                         String name,
                                         String content)

Convenience method to build a meta tag for HTML output or a text line for Text output.

Parameters:

format - the desired format of this output

name - the name of the name-value pairing (will be escaped in HTML)

content - the value of the name-value pairing (will be escaped in HTML)

Returns:

a string containing the output

Throws:

UnsupportedOperationException - if the format is not HTML or Text.

buildHTMLTextOutput

protected String buildHTMLTextOutput(OutputFormat format,
                                     String prefix,
                                     List<?> contents)

Convenience method to build a meta tag for HTML output or a text line for Text output for a list of multiple DDMS components.

Parameters:

format - the desired format of this output

prefix - the first part of the name in the name-value pairing (will be escaped in HTML)

contents - a list of the values (will be escaped in HTML)

Returns:

a string containing the output

Throws:

UnsupportedOperationException - if the format is not HTML or Text.

buildPrefix

protected String buildPrefix(String prefix,
                             String token,
                             String suffix)

Convenience method to construct a naming prefix for use in HTML/Text output

Parameters:

prefix - an optional first part to the prefix

token - an optional second part to the prefix

suffix - an optional third part to the prefix

Returns:

a String containing the concatenated values

buildIndex

protected String buildIndex(int index,
                            int total)

Constructs a braced 1-based index to differentiate multiples in HTML/Text output, based on the 0-based list index of the item, and the output.indexLevel configurable property. When this property is 0, indices are never shown. At 1, indices are shown when needed, but hidden when there is only 1 item to display. At 2, indices are always shown. If the property is set to something else, it defaults to 0.

Parameters:

index - the 0-based index of an item in a list

total - the total number of items in that list

Returns:

a String containing the index text, if applicable

toXML

public String toXML()

Will return an empty string if the name is not set, but this cannot occur after instantiation.

Specified by:

toXML in interface IDDMSComponent

Returns:

the XML representation of this component

See Also:

IDDMSComponent.toXML()

getAttributeValue

protected String getAttributeValue(String name)

Convenience method to look up an attribute which is in the same namespace as the enclosing element

Parameters:

name - the local name of the attribute

Returns:

attribute value, or an empty string if it does not exist

getAttributeValue

protected String getAttributeValue(String name,
                                   String namespaceURI)

Convenience method to look up an attribute

Parameters:

name - the local name of the attribute

namespaceURI - the namespace of the attribute

Returns:

attribute value, or an empty string if it does not exist

getChild

protected nu.xom.Element getChild(String name)

Convenience method to get the first child element with a given name in the same namespace as the parent element

Parameters:

name - the local name to search for

Returns:

the element, or null if it does not exist

getChildTextAsDouble

protected static Double getChildTextAsDouble(nu.xom.Element element,
                                             String name)

Convenience method to convert one of the lat/lon fields into a Double. Returns null if the field does not exist.

Parameters:

element - the parent element

name - the local name of the child

Returns:

a Double, or null if it cannot be created

requireAtLeastVersion

protected void requireAtLeastVersion(String version)
                              throws InvalidDDMSException

Helper method to validate that a specific version of DDMS (or higher) is being used.

Parameters:

version - the inclusive threshold version

Throws:

InvalidDDMSException - if the version is not high enough

requireAtMostVersion

protected void requireAtMostVersion(String version)
                             throws InvalidDDMSException

Helper method to validate that a specific version of DDMS (or lower) is being used.

Parameters:

version - the inclusive threshold version

Throws:

InvalidDDMSException - if the version is too high enough

getDDMSVersion

protected DDMSVersion getDDMSVersion()

Returns the most recent compatible DDMSVersion for this component, based on the XML Namespace. Depends on the XOM Element being set. For DDMS versions that share the same namespace (4.0.1 and 4.1), the newer version is always returned.

Returns:

a version

Throws:

UnsupportedVersionException - if the XML namespace is not one of the supported DDMS namespaces.

equals

public boolean equals(Object obj)

Test for logical equality.

The base case tests against the name value and namespaceURI, as well as any child components classified as "nested components" and any security attributes. Extending classes may require additional rules for equality. This case automatically includes any nested components or security attributes.

Overrides:

equals in class Object

See Also:

Object.equals(Object)

hashCode

public int hashCode()

Returns a hashcode for the component.

This automatically includes any nested components or security attributes.

Overrides:

hashCode in class Object

See Also:

Object.hashCode()

toString

public String toString()

Returns the XML representation of the component

Overrides:

toString in class Object

See Also:

Object.toString()

getLocatorSuffix

protected String getLocatorSuffix()

Can be overridden to change the locator string used in warnings and errors.

For components such as Format, there are wrapper elements that are not implemented as Java objects. These elements should be included in the XPath string used to identify the source of the error.

For example, if a ddms:extent element has a warning and the ddms:format element reports it, the locator information should be "/ddms:format/ddms:Media/ddms:extent" and not the default of "/ddms:format/ddms:extent"

Returns:

an empty string, unless overridden.

addWarning

protected void addWarning(String text)

Convenience method to create a warning and add it to the list of validation warnings.

Parameters:

text - the description text

addWarnings

protected void addWarnings(List<ValidationMessage> warnings,
                           boolean forAttributes)

Convenience method to add multiple warnings to the list of validation warnings.

Child locator information will be prefixed with the parent (this) locator information. This does not overwrite the original warning -- it creates a new copy.

Parameters:

warnings - the list of validation messages to add

forAttributes - if true, the locator suffix is not used, because the attributes will be for the topmost element (for example, warnings for gml:Polygon's security attributes should not end up with a locator of /gml:Polygon/gml:exterior/gml:LinearRing).

getXOMElement

protected nu.xom.Element getXOMElement()

Accessor for the XOM element representing this component

getXOMElementCopy

public nu.xom.Element getXOMElementCopy()

Accessor for a copy of the underlying XOM element

Specified by:

getXOMElementCopy in interface IDDMSComponent

setXOMElement

protected void setXOMElement(nu.xom.Element element,
                             boolean validateNow)
                      throws InvalidDDMSException

Accessor for the XOM element representing this component. When the element is set, the component is validated again with validate.

Parameters:

element - the XOM element to use

validateNow - whether to validate the component immediately after setting

Throws:

InvalidDDMSException