XTCEFunctions (XML Telemetric and Command Exchange Toolkit 1.1.4 API)

java.lang.Object
- org.xtce.toolkit.XTCEFunctions

```
public class XTCEFunctions
extends Object
```
This class is a container to capture some common static functions that are applicable throughout the toolkit. This class is not meant to be constructed, since the functions are static.

Author:

David Overeem

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static String`	`bitSetToHex(BitSet bits, int minBytes)` Convert a BitSet object to a hex byte string, ordered from the most significant byte to the least significant byte.
`static boolean`	`checkLocaleAvailable(Locale userLocale)` Checks if a Locale preference is supported by this toolkit.
`static String`	`generalErrorPrefix()` Retrieves the internationalized version of the ERROR prefix used for exception and log messages.
`static String`	`generalWarningPrefix()` Retrieves the internationalized version of the Warning prefix used for exception and log messages.
`static XTCEAbsoluteTimeType`	`getAbsoluteTimeHandler(org.omg.space.xtce.AbsoluteTimeDataType element)` Method to locate a time handler for an XTCE AbsoluteTimeDataType element.
`static BitSet`	`getBitSetFromByteArray(byte[] bytes)` This function converts a byte array to a BitSet suitable for use in the container content processing when applying a binary data set.
`static BitSet`	`getBitSetFromStreamByteArray(byte[] bytes)` This function converts a byte array to a BitSet suitable for use in the container content processing when applying a binary data set.
`static byte[]`	`getBytesFromHexString(String hex)` Retrieves a byte array from a hexadecimal stream represented by a string.
`static String`	`getCleanHexString(String inputText)` Retrieve a "cleaned up" hex string from a user input hexadecimal field.
`static String`	`getMemoryUsageStatistics()` Creates a string with the current memory usage statistics from the Java Virtual Machine.
`static String`	`getNameFromPathReferenceString(String filepath)` This function is for stripping off object name from an XTCE path reference from the data model for containerRef, parameterRef, and argumentRef, amongst others.
`static String`	`getPathNameFromReferenceString(String filepath)` This function is for stripping the path off an path reference in the XTCE data model for containerRef, parameterRef, and argumentRef, amongst others.
`static byte[]`	`getStreamByteArrayFromBitSet(BitSet rawBits, int minBytes)` This function converts a BitSet from the encode functions to a byte array in the order it would exist on the wire in that the zeroth index is the first byte read/written.
`static String`	`getText(String key)` This function supports I18N and L10N for the XTCE toolkit by permitting this class to maintain the statics for internationalization and making it easy for calling code to get internationalized strings from anywhere.
`static String`	`makeAliasDisplayString(XTCENamedObject parameter, boolean showAllNamespaces, boolean showAliasNamespaces, String preferredNamespace)` This function formats the aliases on a named and typed object based on some preferences.
`static String`	`makeRepeatString(long count, long total)` This function makes the repeat parameter/argument string, taking into account the internationalization.
`static boolean`	`matchesUsingGlob(String text, String glob)` A matcher function that uses the glob style algorithm to determine if a candidate string matches a glob style pattern.
`static void`	`registerAbsoluteTimeHandler(XTCEAbsoluteTimeType instance)` Method to register a custom time handler for XTCE AbsoluteTimeDataType elements.
`static String`	`resolvePathReference(String currentPath, String pathReference)` This function mimics the behavior of the ubiquitous filesystem function called realpath().
`static boolean`	`setLocalePreference(Locale userLocale)` Sets the user language and country preference so that a ResourceBundle can be loaded to assist the getText() function.
`static String`	`xmlPrettyPrint(NodeList nodes)` Method to format and "beautify" the XML text from a provided DOM NodeList object.
`static String`	`xmlPrettyPrint(String xmlText)` Method to format and "beautify" the XML text from a provided String object containing XML ASCII text.

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

- Method Detail
  - registerAbsoluteTimeHandler
```
public static void registerAbsoluteTimeHandler(XTCEAbsoluteTimeType instance)
```
    Method to register a custom time handler for XTCE AbsoluteTimeDataType elements.
    
    Parameters:
    
    instance - Constructed object of a type that implements the interface XTCEAbsoluteTimeType in toolkit.
  - getAbsoluteTimeHandler
```
public static XTCEAbsoluteTimeType getAbsoluteTimeHandler(org.omg.space.xtce.AbsoluteTimeDataType element)
                                                   throws XTCEDatabaseException
```
    Method to locate a time handler for an XTCE AbsoluteTimeDataType element. Handlers are searched in reverse order of addition, so the newest is always checked first.
    
    Parameters:
    
    element - AbsoluteTimeDataType XML element from an XTCE document.
    
    Returns:
    
    Handler that implements the XTCEAbsoluteTimeType class in this toolkit that matches the XML element required contents. If not handler exists, then the function throws.
    
    Throws:
    
    XTCEDatabaseException - thrown in the event that a handler is not available or not usable for this element.
  - getBitSetFromByteArray
```
public static BitSet getBitSetFromByteArray(byte[] bytes)
```
    This function converts a byte array to a BitSet suitable for use in the container content processing when applying a binary data set. The BitSet is sequenced where bit 0 is the first bit in the data bytes, progressing forward in count until the last bit in the data bytes.
    
    Parameters:
    
    bytes - byte[] array of raw binary data.
    
    Returns:
    
    BitSet containing the binary data exactly sized to the number of bytes, so it will always be a multiple of 8 bits in size.
  - getStreamByteArrayFromBitSet
```
public static byte[] getStreamByteArrayFromBitSet(BitSet rawBits,
                                                  int minBytes)
```
    This function converts a BitSet from the encode functions to a byte array in the order it would exist on the wire in that the zeroth index is the first byte read/written.
    
    Parameters:
    
    rawBits - BitSet containing the raw binary data.
    
    minBytes - int containing the number of bytes expected. Sometimes the BitSet can be short or long due to allocations.
    
    Returns:
    
    byte[] containing the data for streaming or printing.
  - getBitSetFromStreamByteArray
```
public static BitSet getBitSetFromStreamByteArray(byte[] bytes)
```
    This function converts a byte array to a BitSet suitable for use in the container content processing when applying a binary data set. The BitSet is sequenced where bit 0 is the first bit in the data bytes, progressing forward in count until the last bit in the data bytes.
    
    Parameters:
    
    bytes - byte[] array of raw binary data.
    
    Returns:
    
    BitSet containing the binary data exactly sized to the number of bytes, so it will always be a multiple of 8 bits in size.
  - bitSetToHex
```
public static String bitSetToHex(BitSet bits,
                                 int minBytes)
```
    Convert a BitSet object to a hex byte string, ordered from the most significant byte to the least significant byte. The most significant bits are padded with zero in this case when the raw size is not on an even 8 bit boundary. This results in the function never returning a hex string that is less than 2 characters for each byte, with a minimum of 1 byte. A "0x" is prepended.
    
    Parameters:
    
    bits - BitSet containing an arbitrarily long binary field.
    
    minBytes - integer containing the minimum number of bytes to output on the hex string. This results in 0 padding if the BitSet is too small.
    
    Returns:
    
    String containing the hex of the raw value, subject to the explanation above associated with this function.
  - resolvePathReference
```
public static String resolvePathReference(String currentPath,
                                          String pathReference)
```
    This function mimics the behavior of the ubiquitous filesystem function called realpath(). The purpose is to take a filesystem path reference, which may contain relative or absolute path, and may also contain the . or .. or multiple slashes, and convert that to an absolute path reference. In order to do this, the candidate path provided by a user (in this case, an XTCE document) and also the current working Space System path are needed.
    
    Parameters:
    
    currentPath - The current working Space System path from which the candidate path reference is to be resolved from.
    
    pathReference - The candidate path reference, generally from an XTCE containerRef, parameterRef, or argumentRef.
    
    Returns:
    
    String that will always contain the absolute path fully resolved for the candidate path reference.
  - getPathNameFromReferenceString
```
public static String getPathNameFromReferenceString(String filepath)
```
    This function is for stripping the path off an path reference in the XTCE data model for containerRef, parameterRef, and argumentRef, amongst others.
    
    Parameters:
    
    filepath - An XTCE style path reference string that contains the Space System path leading up to the object of interest, such as a Container, Parameter, or Argument, amongst others.
    
    Returns:
    
    String containing just the path to the object name.
  - getNameFromPathReferenceString
```
public static String getNameFromPathReferenceString(String filepath)
```
    This function is for stripping off object name from an XTCE path reference from the data model for containerRef, parameterRef, and argumentRef, amongst others.
    
    Parameters:
    
    filepath - An XTCE style path reference string that contains the Space System path leading up to the object of interest, such as a Container, Parameter, or Argument, amongst others.
    
    Returns:
    
    String containing just the name of the object.
  - makeAliasDisplayString
```
public static String makeAliasDisplayString(XTCENamedObject parameter,
                                            boolean showAllNamespaces,
                                            boolean showAliasNamespaces,
                                            String preferredNamespace)
```
    This function formats the aliases on a named and typed object based on some preferences. The format of the returned string will have each alias space delimited, unless there is only one. The "showAllNamespaces" takes precedence over the "preferredNamespace". The string will be in the form NS1:ALIAS1 NS2:ALIAS2 if the "showAliasNamespaces" option is true. Otherwise, it will just be ALIAS1 ALIAS2.
    
    Parameters:
    
    parameter - XTCENamedObject containing any of the objects that can be aliased in the XTCE data model and are supported by this toolkit.
    
    showAllNamespaces - boolean indicating if all of the namespaces should appear in the string.
    
    showAliasNamespaces - boolean indicating if the alias names should be included in the alias string.
    
    preferredNamespace - String containing the preferred namespace if there is more than one defined.
    
    Returns:
    
    String for display purposes.
  - getCleanHexString
```
public static String getCleanHexString(String inputText)
```
    Retrieve a "cleaned up" hex string from a user input hexadecimal field. The output will have any leading "0x" removed, will be in lower case, will contain no whitespace, no commas, no periods, or semicolons. At present this function does not guarantee viability of the string from a "NumberFormatException" when parsing.
    
    Parameters:
    
    inputText - String containing user input text.
    
    Returns:
    
    String suitable for parsing the text in base 16.
  - getBytesFromHexString
```
public static byte[] getBytesFromHexString(String hex)
```
    Retrieves a byte array from a hexadecimal stream represented by a string.
    
    Parameters:
    
    hex - String containing the user provided hexadecimal string. It is recommended to call the "getCleanHexString()" on this text first.
    
    Returns:
    
    byte[] byte array of sufficient size to capture the hexadecimal string provided.
    
    Throws:
    
    NumberFormatException - if the string cannot be interpreted as a hex string by the Java Integer class.
  - matchesUsingGlob
```
public static boolean matchesUsingGlob(String text,
                                       String glob)
```
    A matcher function that uses the glob style algorithm to determine if a candidate string matches a glob style pattern. This function is to the credit of a suggested algorithm found on many stackoverflow.com searches. It is not the authors original work. The posting user name is "Mihi" who links to a website at: http://schierlm.users.sourceforge.net The stackoverflow thread that contains this code is at: http://stackoverflow.com/questions/1247772/is-there-an-equivalent-of-java-util-regex-for-glob-type-patterns
    
    Parameters:
    
    text - String containing the candidate text to match.
    
    glob - String containing the glob pattern, probably provided by a user to match something from a list.
    
    Returns:
    
    boolean indicating if the seatch text matches the glob by the glob algorithm rules.
  - getText
```
public static String getText(String key)
```
    This function supports I18N and L10N for the XTCE toolkit by permitting this class to maintain the statics for internationalization and making it easy for calling code to get internationalized strings from anywhere.
    
    Parameters:
    
    key - String containing the key to lookup the desired text message from the locale appropriate properties file.
    
    Returns:
    
    String to display in the local language and country preference.
  - setLocalePreference
```
public static boolean setLocalePreference(Locale userLocale)
```
    Sets the user language and country preference so that a ResourceBundle can be loaded to assist the getText() function.
    
    Parameters:
    
    userLocale - Locale object containing the desired language and country. A properties file is needed to support the choice.
    
    Returns:
    
    boolean indicating if the preference was valid and could be set.
  - checkLocaleAvailable
```
public static boolean checkLocaleAvailable(Locale userLocale)
```
    Checks if a Locale preference is supported by this toolkit.
    
    Parameters:
    
    userLocale - Locale to check to see if a bundle exists.
    
    Returns:
    
    boolean indicating if this Locale is available.
  - generalErrorPrefix
```
public static String generalErrorPrefix()
```
    Retrieves the internationalized version of the ERROR prefix used for exception and log messages.
    
    Returns:
    
    String containing the error text with a colon and space after.
  - generalWarningPrefix
```
public static String generalWarningPrefix()
```
    Retrieves the internationalized version of the Warning prefix used for exception and log messages.
    
    Returns:
    
    String containing the error text with a colon and space after.
  - xmlPrettyPrint
```
public static String xmlPrettyPrint(NodeList nodes)
                             throws XTCEDatabaseException
```
    Method to format and "beautify" the XML text from a provided DOM NodeList object. This function passes the nodes through the DOM Transformer using a stylesheet embedded in this package to format the output.
    
    Parameters:
    
    nodes - NodeList containing XML nodes to format into ASCII text.
    
    Returns:
    
    String containing the text.
    
    Throws:
    
    XTCEDatabaseException - thrown in the event that the Transformer cannot convert the NodeList to XML text.
  - xmlPrettyPrint
```
public static String xmlPrettyPrint(String xmlText)
                             throws XTCEDatabaseException
```
    Method to format and "beautify" the XML text from a provided String object containing XML ASCII text. This function passes the nodes through the DOM Transformer using a stylesheet embedded in this package to format the output.
    
    Parameters:
    
    xmlText - String containing XML text.
    
    Returns:
    
    String containing the text passed through the transformer.
    
    Throws:
    
    XTCEDatabaseException - thrown in the event that the Transformer cannot convert the convert the ASCII text.
  - getMemoryUsageStatistics
```
public static String getMemoryUsageStatistics()
```
    Creates a string with the current memory usage statistics from the Java Virtual Machine.
    
    Returns:
    
    String containing a memory usage description suitable for a log line.
  - makeRepeatString
```
public static String makeRepeatString(long count,
                                      long total)
```
    This function makes the repeat parameter/argument string, taking into account the internationalization.
    
    Parameters:
    
    count - long containing the current item count.
    
    total - long total number of items.
    
    Returns:
    
    String containing the internationalized text.

Class XTCEFunctions

Method Summary

Methods inherited from class java.lang.Object

Method Detail

registerAbsoluteTimeHandler

getAbsoluteTimeHandler

getBitSetFromByteArray

getStreamByteArrayFromBitSet

getBitSetFromStreamByteArray

bitSetToHex

resolvePathReference

getPathNameFromReferenceString

getNameFromPathReferenceString

makeAliasDisplayString

getCleanHexString

getBytesFromHexString

matchesUsingGlob

getText

setLocalePreference

checkLocaleAvailable

generalErrorPrefix

generalWarningPrefix

xmlPrettyPrint

xmlPrettyPrint

getMemoryUsageStatistics

makeRepeatString