Package org.xtce.toolkit

Class 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 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​(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.