Util (DDMSence 2.6.0 API)

Object
- buri.ddmsence.util.Util

```
public class Util
extends Object
```
A collection of stateless utility methods.

Since:

0.9.b

Author:

Brian Uri!

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`addAttribute(nu.xom.Element element, String prefix, String attributeName, String namespaceURI, String attributeValue)` Helper method to add an attribute to an element.
`static void`	`addDDMSAttribute(nu.xom.Element element, String attributeName, String attributeValue)` Helper method to add a ddms attribute to an element.
`static void`	`addDDMSChildElement(nu.xom.Element element, String childName, String childValue)` Helper method to add a ddms child element to an element.
`static void`	`addNonEmptyJsonProperty(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.
`static int`	`booleanHashCode(boolean b)` Returns an int value for a boolean, for use in a hashCode function.
`static nu.xom.Attribute`	`buildAttribute(String prefix, String name, String namespaceURI, String value)` Convenience method to create an attribute in a namespace.
`static nu.xom.Attribute`	`buildDDMSAttribute(String name, String value)` Convenience method to create an attribute in the default DDMS namespace.
`static nu.xom.Element`	`buildDDMSElement(String name, String childText)` Convenience method to create an element in the default DDMS namespace with some child text.
`static nu.xom.Element`	`buildElement(String prefix, String name, String namespaceURI, String childText)` Convenience method to create an element in a namespace with some child text.
`static nu.xom.xslt.XSLTransform`	`buildSchematronTransform(File schematronFile)` Takes a Schematron file and transforms it with the ISO Schematron skeleton files.
`static nu.xom.Document`	`buildXmlDocument(InputStream inputStream)` Loads a XOM object tree from an input stream.
`static String`	`capitalize(String string)` Capitalizes the first letter of a String.
`static nu.xom.Element`	`commitXml(String xml)` Attempts to convert arbitrary XML into an Element.
`static boolean`	`containsOnlyEmptyValues(List<String> list)` Checks if all of the entries in a list of Strings is empty or null.
`static String`	`decapitalize(String string)` Lowers the first letter of a String.
`static javax.xml.datatype.DatatypeFactory`	`getDataTypeFactory()` Accessor for the datatype factory, which is cached as a thread-local variable.
`static List<String>`	`getDDMSChildValues(nu.xom.Element parent, String name)` Gets the child text of any child elements in the DDMS namespace and returns them as a list.
`static String`	`getFirstDDMSChildValue(nu.xom.Element parent, String name)` Gets the child text of the first child element matching the name in the DDMS namespace.
`static com.google.gson.JsonArray`	`getJSONArray(List<?> values)` Converts a list of items into a JSON Array.
`static String`	`getNonNullString(String string)` Returns an empty string in place of a null one.
`static String`	`getSchematronQueryBinding(nu.xom.Document schDocument)` Locates the queryBinding attribute in an ISO Schematron file and returns it.
`static String`	`getXsList(List<?> list)` Converts a list of objects into a space-delimited xs:list, using the object's toString() implementation
`static List<String>`	`getXsListAsList(String value)` Helper method to convert an xs:NMTOKENS data type into a List of Strings.
`static boolean`	`isBounded(int testCount, int lowBound, int highBound)` Checks that a number is between two values, inclusive
`static boolean`	`isEmpty(String value)` Checks if a String value is empty.
`static boolean`	`listEquals(List<?> list1, List<?> list2)` Checks if two lists of Objects are identical.
`static boolean`	`nullEquals(Object obj1, Object obj2)` Checks object equality when the objects could possible be null.
`static void`	`requireBoundedChildCount(nu.xom.Element parent, String childName, int lowBound, int highBound)` Checks that the number of child elements with the given name in the same namespace as the parent are bounded.
`static void`	`requireCompatibleVersion(IDDMSComponent parent, IDDMSComponent child)` Validates that a child component has a compatible DDMS version as the parent.
`static void`	`requireDDMSDateFormat(String date, String ddmsNamespace)` Asserts that a date format is one of the 5 types accepted by DDMS.
`static void`	`requireDDMSQName(nu.xom.Element element, String localName)` Asserts that the qualified name of an element matches the expected name and a supported version of the DDMS XML namespace
`static void`	`requireDDMSValidURI(String uri)` Checks that a string is a valid URI.
`static void`	`requireDDMSValue(String description, Object value)` Asserts that a value required for DDMS is not null or empty.
`static void`	`requireHTMLText(OutputFormat format)` Asserts that the format is either HTML or Text.
`static void`	`requireQName(nu.xom.Element element, String namespaceURI, String localName)` Asserts that the qualified name of an element matches the expected name and namespace URI
`static void`	`requireValidLatitude(Double value)` Validates a latitude value
`static void`	`requireValidLongitude(Double value)` Validates a longitude value
`static void`	`requireValidNCName(String name)` Validates that a string is an NCName.
`static void`	`requireValidNCNames(List<String> names)` Validates that a list of strings contains NCNames.
`static void`	`requireValidNMToken(String name)` Validates that a string is an NMTOKEN.
`static void`	`requireValue(String description, Object value)` Asserts that a value required, for general cases.
`static javax.xml.datatype.XMLGregorianCalendar`	`toXMLGregorianCalendar(String date)` Helper method for DDMS components that use the DDMS custom date.
`static String`	`xmlEscape(String input)` Replaces XML special characters - '&', '<', '>', '\'', '"'

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getDataTypeFactory
```
public static javax.xml.datatype.DatatypeFactory getDataTypeFactory()
```
    Accessor for the datatype factory, which is cached as a thread-local variable.
  - toXMLGregorianCalendar
```
public static javax.xml.datatype.XMLGregorianCalendar toXMLGregorianCalendar(String date)
```
    Helper method for DDMS components that use the DDMS custom date. Converts date strings in any of the valid DDMS date types (ddms:CombinedDateType) into an XMLGregorianCalendar. Returns null if the string is empty or not a valid date type.
    
    Parameters:
    
    date - the raw date string
    
    Returns:
    
    an XMLGregorianCalendar for valid dates, null otherwise.
  - getJSONArray
```
public static com.google.gson.JsonArray getJSONArray(List<?> values)
```
    Converts a list of items into a JSON Array.
    
    Parameters:
    
    values - the values
    
    Returns:
    
    a JSON array, with the values in the same order
  - addNonEmptyJsonProperty
```
public static void addNonEmptyJsonProperty(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.
    
    Parameters:
    
    object - the object to add to
    
    name - the name of the array, if added
    
    value - the value to add
  - getNonNullString
```
public static String getNonNullString(String string)
```
    Returns an empty string in place of a null one.
    
    Parameters:
    
    string - the string to convert, if null
    
    Returns:
    
    an empty string if the string is null, or the string untouched
  - getXsListAsList
```
public static List<String> getXsListAsList(String value)
```
    Helper method to convert an xs:NMTOKENS data type into a List of Strings.
    The number of items returned is based on the normalization of the whitespace first. So, an xs:list defined as "a b" will return a List of 2 Strings ("a", "b"), and not a List of 4 String ("a", "", "", "b")
    
    Parameters:
    
    value - the xs:list style String to parse
    
    Returns:
    
    a List (never null)
  - getXsList
```
public static String getXsList(List<?> list)
```
    Converts a list of objects into a space-delimited xs:list, using the object's toString() implementation
    
    Parameters:
    
    list - the list to convert
    
    Returns:
    
    a space-delimited string, or empty string if the list was empty.
  - booleanHashCode
```
public static int booleanHashCode(boolean b)
```
    Returns an int value for a boolean, for use in a hashCode function.
    
    Parameters:
    
    b - the boolean
    
    Returns:
    
    1 for true and 0 for false
  - isEmpty
```
public static boolean isEmpty(String value)
```
    Checks if a String value is empty. An empty string is defined as one that is null, contains only whitespace, or has length 0.
    
    Parameters:
    
    value - the value to check.
    
    Returns:
    
    a boolean, true if the value is null or zero-length, false otherwise
  - containsOnlyEmptyValues
```
public static boolean containsOnlyEmptyValues(List<String> list)
```
    Checks if all of the entries in a list of Strings is empty or null.
    
    Parameters:
    
    list - the list containing strings
    
    Returns:
    
    true if the list only has null or empty values
  - getFirstDDMSChildValue
```
public static String getFirstDDMSChildValue(nu.xom.Element parent,
                                            String name)
```
    Gets the child text of the first child element matching the name in the DDMS namespace.
    
    Parameters:
    
    parent - the parent element
    
    name - the name of the child element
    
    Returns:
    
    the child text of the first discovered child element
  - getDDMSChildValues
```
public static List<String> getDDMSChildValues(nu.xom.Element parent,
                                              String name)
```
    Gets the child text of any child elements in the DDMS namespace and returns them as a list.
    
    Parameters:
    
    parent - the parent element
    
    name - the name of the child element
    
    Returns:
    
    a List of strings, where each string is child text of matching elements
  - requireHTMLText
```
public static void requireHTMLText(OutputFormat format)
```
    Asserts that the format is either HTML or Text.
    
    Parameters:
    
    format - the output format to test
    
    Throws:
    
    IllegalArgumentException - if the format is incorrect
  - requireDDMSValue
```
public static void requireDDMSValue(String description,
                                    Object value)
                             throws InvalidDDMSException
```
    Asserts that a value required for DDMS is not null or empty.
    
    Parameters:
    
    description - a descriptive name of the value
    
    value - the value to check
    
    Throws:
    
    InvalidDDMSException - if the value is null or empty
  - requireDDMSDateFormat
```
public static void requireDDMSDateFormat(String date,
                                         String ddmsNamespace)
                                  throws InvalidDDMSException
```
    Asserts that a date format is one of the 5 types accepted by DDMS.
    
    Parameters:
    
    date - the date in its raw XML format
    
    ddmsNamespace - the DDMS namespace of this date (DDM 4.0.1 and earlier only support 4 types).
    
    Throws:
    
    InvalidDDMSException - if the value is invalid. Does nothing if value is null.
  - requireDDMSQName
```
public static void requireDDMSQName(nu.xom.Element element,
                                    String localName)
                             throws InvalidDDMSException
```
    Asserts that the qualified name of an element matches the expected name and a supported version of the DDMS XML namespace
    
    Parameters:
    
    element - the element to check
    
    localName - the local name to compare to
    
    Throws:
    
    InvalidDDMSException - if the name is incorrect
  - requireQName
```
public static void requireQName(nu.xom.Element element,
                                String namespaceURI,
                                String localName)
                         throws InvalidDDMSException
```
    Asserts that the qualified name of an element matches the expected name and namespace URI
    
    Parameters:
    
    element - the element to check
    
    namespaceURI - the namespace to check
    
    localName - the local name to compare to
    
    Throws:
    
    IllegalArgumentException - if the name is incorrect
    
    InvalidDDMSException
  - requireValue
```
public static void requireValue(String description,
                                Object value)
```
    Asserts that a value required, for general cases.
    
    Parameters:
    
    description - a descriptive name of the value
    
    value - the value to check
    
    Throws:
    
    IllegalArgumentException - if the value is null or empty
  - requireBoundedChildCount
```
public static void requireBoundedChildCount(nu.xom.Element parent,
                                            String childName,
                                            int lowBound,
                                            int highBound)
                                     throws InvalidDDMSException
```
    Checks that the number of child elements with the given name in the same namespace as the parent are bounded.
    
    Parameters:
    
    parent - the parent element
    
    childName - the local name of the child
    
    lowBound - the lowest value the number can be
    
    highBound - the highest value the number can be
    
    Throws:
    
    InvalidDDMSException - if the number is out of bounds
  - requireValidNCNames
```
public static void requireValidNCNames(List<String> names)
                                throws InvalidDDMSException
```
    Validates that a list of strings contains NCNames. This method uses the built-in Verifier in XOM by attempting to create a new Element with the test string as a local name (Local names must be NCNames).
    
    Parameters:
    
    names - a list of names to check
    
    Throws:
    
    InvalidDDMSException - if any name is not an NCName.
  - requireCompatibleVersion
```
public static void requireCompatibleVersion(IDDMSComponent parent,
                                            IDDMSComponent child)
                                     throws InvalidDDMSException
```
    Validates that a child component has a compatible DDMS version as the parent.
    
    Parameters:
    
    parent - the parent component
    
    child - the child component
    
    Throws:
    
    InvalidDDMSException - if
  - requireValidNCName
```
public static void requireValidNCName(String name)
                               throws InvalidDDMSException
```
    Validates that a string is an NCName. This method relies on Saxon's library methods.
    
    Parameters:
    
    name - the name to check
    
    Throws:
    
    InvalidDDMSException - if the name is not an NCName.
  - requireValidNMToken
```
public static void requireValidNMToken(String name)
                                throws InvalidDDMSException
```
    Validates that a string is an NMTOKEN. This method relies on Saxon's library methods.
    
    Parameters:
    
    name - the name to check
    
    Throws:
    
    InvalidDDMSException - if the name is not an NMTOKEN.
  - requireDDMSValidURI
```
public static void requireDDMSValidURI(String uri)
                                throws InvalidDDMSException
```
    Checks that a string is a valid URI.
    
    Parameters:
    
    uri - the string to test
    
    Throws:
    
    InvalidDDMSException - if the string cannot be built into a URI
  - requireValidLongitude
```
public static void requireValidLongitude(Double value)
                                  throws InvalidDDMSException
```
    Validates a longitude value
    
    Parameters:
    
    value - the value to test
    
    Throws:
    
    InvalidDDMSException
  - requireValidLatitude
```
public static void requireValidLatitude(Double value)
                                 throws InvalidDDMSException
```
    Validates a latitude value
    
    Parameters:
    
    value - the value to test
    
    Throws:
    
    InvalidDDMSException
  - isBounded
```
public static boolean isBounded(int testCount,
                                int lowBound,
                                int highBound)
```
    Checks that a number is between two values, inclusive
    
    Parameters:
    
    testCount - the number to evaluate
    
    lowBound - the lowest value the number can be
    
    highBound - the highest value the number can be
    
    Returns:
    
    true if the number is bounded, false otherwise
    
    Throws:
    
    IllegalArgumentException - if the range is invalid.
  - listEquals
```
public static boolean listEquals(List<?> list1,
                                 List<?> list2)
```
    Checks if two lists of Objects are identical. Returns true if the lists are the same length and each indexed string also exists at the same index in the other list.
    
    Parameters:
    
    list1 - the first list
    
    list2 - the second list
    
    Returns:
    
    true if the lists are of equal size and contain the same objects, false otherwise.
    
    Throws:
    
    IllegalArgumentException - if one of the lists is null
  - nullEquals
```
public static boolean nullEquals(Object obj1,
                                 Object obj2)
```
    Checks object equality when the objects could possible be null.
    
    Parameters:
    
    obj1 - the first object
    
    obj2 - the second object
    
    Returns:
    
    true if both objects are null or obj1 equals obj2, false otherwise
  - xmlEscape
```
public static String xmlEscape(String input)
```
    Replaces XML special characters - '&', '<', '>', '\'', '"'
    
    Parameters:
    
    input - the string to escape.
    
    Returns:
    
    escaped String
  - capitalize
```
public static String capitalize(String string)
```
    Capitalizes the first letter of a String. Silently does nothing if the string is null, empty, or not a letter.
    
    Parameters:
    
    string - the string to capitalize
    
    Returns:
    
    the capitalized string
  - decapitalize
```
public static String decapitalize(String string)
```
    Lowers the first letter of a String. Silently does nothing if the string is null, empty, or not a letter.
    
    Parameters:
    
    string - the string to change
    
    Returns:
    
    the changed string
  - addDDMSAttribute
```
public static void addDDMSAttribute(nu.xom.Element element,
                                    String attributeName,
                                    String attributeValue)
```
    Helper method to add a ddms attribute to an element. Will not add the attribute if the value is empty or null. This method uses the DDMS namespace defined with DDMSVersion.getCurrentVersion().
    
    Parameters:
    
    element - the element to decorate
    
    attributeName - the name of the attribute (will be within the DDMS namespace)
    
    attributeValue - the value of the attribute
  - addAttribute
```
public static void addAttribute(nu.xom.Element element,
                                String prefix,
                                String attributeName,
                                String namespaceURI,
                                String attributeValue)
```
    Helper method to add an attribute to an element. Will not add the attribute if the value is empty or null.
    
    Parameters:
    
    element - the element to decorate
    
    prefix - the prefix to use (without a trailing colon)
    
    attributeName - the name of the attribute
    
    namespaceURI - the namespace this attribute is in
    
    attributeValue - the value of the attribute
  - addDDMSChildElement
```
public static void addDDMSChildElement(nu.xom.Element element,
                                       String childName,
                                       String childValue)
```
    Helper method to add a ddms child element to an element. Will not add if the value is empty or null.
    
    Parameters:
    
    element - the element to decorate
    
    childName - the name of the child (will be within the DDMS namespace)
    
    childValue - the value of the attribute
  - buildDDMSElement
```
public static nu.xom.Element buildDDMSElement(String name,
                                              String childText)
```
    Convenience method to create an element in the default DDMS namespace with some child text. The resultant element will use the DDMS prefix and have no attributes or children (yet).
    
    Parameters:
    
    name - the local name of the element
    
    childText - the text of the element
  - buildElement
```
public static nu.xom.Element buildElement(String prefix,
                                          String name,
                                          String namespaceURI,
                                          String childText)
```
    Convenience method to create an element in a namespace with some child text. The resultant element will use a custom prefix and have no attributes or children (yet).
    
    Parameters:
    
    prefix - the prefix to use (without a trailing colon)
    
    name - the local name of the element
    
    namespaceURI - the namespace this element is in
    
    childText - the text of the element
  - buildDDMSAttribute
```
public static nu.xom.Attribute buildDDMSAttribute(String name,
                                                  String value)
```
    Convenience method to create an attribute in the default DDMS namespace. The resultant attribute will use the DDMS prefix and have the provided value.
    
    Parameters:
    
    name - the local name of the attribute
    
    value - the value of the attribute
  - buildAttribute
```
public static nu.xom.Attribute buildAttribute(String prefix,
                                              String name,
                                              String namespaceURI,
                                              String value)
```
    Convenience method to create an attribute in a namespace.
    
    Parameters:
    
    prefix - the prefix to use (without a trailing colon)
    
    name - the local name of the attribute
    
    namespaceURI - the namespace this attribute is in
    
    value - the value of the attribute
  - buildXmlDocument
```
public static nu.xom.Document buildXmlDocument(InputStream inputStream)
                                        throws IOException
```
    Loads a XOM object tree from an input stream. This method does no schema validation.
    
    Parameters:
    
    inputStream - the input stream containing the XML document
    
    Returns:
    
    a XOM Document
    
    Throws:
    
    IOException - if there are problems loading or parsing the input stream
  - commitXml
```
public static nu.xom.Element commitXml(String xml)
                                throws InvalidDDMSException
```
    Attempts to convert arbitrary XML into an Element.
    
    Parameters:
    
    xml - the XML string
    
    Returns:
    
    a XOM element based upon the XML string
    
    Throws:
    
    InvalidDDMSException - if the element could not be created.
  - getSchematronQueryBinding
```
public static String getSchematronQueryBinding(nu.xom.Document schDocument)
                                        throws IOException
```
    Locates the queryBinding attribute in an ISO Schematron file and returns it.
    
    Parameters:
    
    schDocument - the Schematron file as an XML Document
    
    Returns:
    
    the value of the queryBinding attribute, or "xslt" if undefined.
    
    Throws:
    
    IOException - if there are file-related problems with looking up the attribute
  - buildSchematronTransform
```
public static nu.xom.xslt.XSLTransform buildSchematronTransform(File schematronFile)
                                                         throws IOException,
                                                                nu.xom.xslt.XSLException
```
    Takes a Schematron file and transforms it with the ISO Schematron skeleton files.
    1. The schema is preprocessed with iso_dsdl_include.xsl.
    2. The schema is preprocessed with iso_abstract_expand.xsl.
    3. The schema is compiled with iso_svrl_for_xslt1.xsl.
    The XSLTransform instance using the result of the processing is returned. This XSLTransform can then be used to validate DDMS components.
    Parameters:
    
    schematronFile - the Schematron file
    
    Returns:
    
    the XSLTransform instance
    
    Throws:
    
    IOException - if there are file-related problems with preparing the stylesheets
    
    nu.xom.xslt.XSLException - if stylesheet transformation fails

Class Util

Method Summary

Methods inherited from class Object

Method Detail

getDataTypeFactory

toXMLGregorianCalendar

getJSONArray

addNonEmptyJsonProperty

getNonNullString

getXsListAsList

getXsList

booleanHashCode

isEmpty

containsOnlyEmptyValues

getFirstDDMSChildValue

getDDMSChildValues

requireHTMLText

requireDDMSValue

requireDDMSDateFormat

requireDDMSQName

requireQName

requireValue

requireBoundedChildCount

requireValidNCNames

requireCompatibleVersion

requireValidNCName

requireValidNMToken

requireDDMSValidURI

requireValidLongitude

requireValidLatitude

isBounded

listEquals

nullEquals

xmlEscape

capitalize

decapitalize

addDDMSAttribute

addAttribute

addDDMSChildElement

buildDDMSElement

buildElement

buildDDMSAttribute

buildAttribute

buildXmlDocument

commitXml

getSchematronQueryBinding

buildSchematronTransform