Package com.inductiveautomation.ignition.common

Class TypeUtilities

  • public class TypeUtilities
extends java.lang.Object

    • Constructor Summary

      Constructors 
      Constructor Description
      TypeUtilities()  

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static <T> boolean anyEqual​(T value, T... others)
      Determines if the value is equal to any of the other values
      static java.lang.Object coerce​(java.lang.Object value, java.lang.Class destType)
      Attempts to coerce the Object value into an instance of the Class type.
      static java.lang.Object coerceForLocale​(java.lang.Object value, java.lang.Class target, java.util.Locale valueLocale)
      A version of coerce intended to go from String to Number, where the source string is formatted for a certain locale.
      static <T> T coerceGeneric​(java.lang.Object value, java.lang.Class<? extends T> destType)
      Performs the same operation as coerce, but with generic typing.
      static java.lang.Object coerceLocaleSafe​(java.lang.String str, java.lang.Class type)
      Special version of coerce that has explicit handling for String-to-Number coersions that don't depend on the current locale.
      static java.lang.Object coerceNullSafe​(java.lang.Object value, java.lang.Class destType)
      Like coerce, except that if value is null, null will be returned instead of the "default" value for the desired type.
      static java.lang.Object coerceNumberNullSafe​(java.lang.Object value, java.lang.Class destType, java.util.Locale locale)
      Like coerce, except that if value is null, null will be returned instead of the "default" value for the desired type.
      static java.lang.String colorToHex​(java.awt.Color c)
      Returns the color as a web-compatible hex string.
      static int compareInts​(int foo, int bar)  
      static <T extends java.lang.Comparable<T>>
      int      		 compareNullHigh​(T c1, T c2)
      Null-safe compare.
      static <T extends java.lang.Comparable<T>>
      int      		 compareNullLow​(T c1, T c2)
      Null-safe compare.
      static Dataset datasetFromJSON​(JSONObject json)  
      static Dataset datasetFromJsonString​(java.lang.String jsonStr)
      Use when you only have JSON in the form of a String
      static com.inductiveautomation.ignition.common.gson.JsonElement datasetToGson​(Dataset data)  
      static com.inductiveautomation.ignition.common.gson.JsonElement datasetToGson​(Dataset data, com.inductiveautomation.ignition.common.gson.Gson gson)  
      static JSONObject datasetToJSON​(Dataset data)  
      static boolean deepEquals​(java.lang.Object o1, java.lang.Object o2, boolean checkArrayTypes)
      Like equals(Object, Object), but if the objects are arrays it delegates to Objects.deepEquals(Object, Object).
      static boolean equals​(double val1, double val2, double tolerance)
      A special form of equals for doubles, that takes a provider tolerance into account.
      static boolean equals​(java.lang.Object o1, java.lang.Object o2)
      This implementation of equals is useful in the following ways: Null-safe: null==null Number-safe: (new Long(0))==(new Integer(0)) and Boolean.TRUE == new Integer(1) Enum-safe: enums will be compared to their integer equivalent or their name Other than that, it delegates to the argument's .equals functions.
      static boolean equalsIgnoreCase​(java.lang.Object o1, java.lang.Object o2)
      Equivalent semantics to equals(Object, Object), but if both arguments are Strings, case insensitive equality will be used
      static java.lang.Object fromString​(java.lang.String value, java.lang.Class<?> dest, java.util.Locale locale)
      A special version of coerce, knowing that the source is a string in the given locale.
      static java.awt.Color getColorFromString​(java.lang.String color)
      Tries to parse a Color from the given string.
      static <T> T getFirstOrNull​(java.util.List<T> list)
      Takes a list and returns the first element.
      static java.lang.Object getInitValueForClass​(java.lang.Class<?> c)  
      static java.lang.String getLastNameComponent​(java.lang.String name)
      Tags a string that represents a series of elements seperated by period (".") and returns the last portion.
      static java.lang.Class<?> getPrimitiveType​(java.lang.Class<?> c)  
      static java.lang.Class<?> getWrapperType​(java.lang.Class<?> c)  
      static org.python.core.PyObject gsonToPy​(com.inductiveautomation.ignition.common.gson.JsonElement element)
      Attempt to encode a given JsonElement into base Python data structures - dictionaries for objects, lists for arrays, etc.
      static boolean hasPrimitiveType​(java.lang.Class<?> c)  
      static boolean hasValueChanged​(QualifiedValue currentValue, QualifiedValue previousValue, DataType expectedType, java.lang.Double deadband)
      Checks whether the value and/or quality have change compared to the current value, taking into account the deadband.
      static boolean isAssignable​(java.lang.Class<?> dest, java.lang.Class<?> source)
      This will return true if the setValue(Object o) knows how to coerce an object of type 'source' to an object of type 'dest'
      static boolean isBoolean​(java.lang.Class<?> cls)
      True if cls == boolean.class || cls==Boolean.class
      static boolean isDirectlyAssignable​(java.lang.Class<?> dest, java.lang.Class<?> source)
      Two classes are 'directly assignable' if reflection won't complain when you pass an object of type 'source' to a method which expects as an argument an object of type 'dest' For example, using reflection you can invoke the method setIntValue(int i) with an Integer object (instead of an 'int' primitive)
      static boolean isFractional​(java.lang.Class<?> cls)  
      static boolean isNullOrEmpty​(java.lang.String s)
      Returns true if the String s is null or zero-length
      static boolean isNumber​(java.lang.Class<?> cls)
      Returns true if the class is boolean or is a proper number.
      static boolean isPrimitive​(java.lang.Class c)
      Returns true if the class is one of the java primitive classes
      static boolean isProperNumber​(java.lang.Class<?> cls)
      Returns true if the given class represents a subclass of Number, or any of the numeric primitives.
      static boolean neq​(java.lang.Object o1, java.lang.Object o2)
      Convenience for: !TypeUtilities.equals(o1,o2)
      static com.inductiveautomation.ignition.common.gson.JsonElement pyToGson​(org.python.core.PyObject pyObject)
      Make a best effort to convert a PyObject into some Gson structure.
      static com.inductiveautomation.ignition.common.gson.JsonElement pyToGson​(org.python.core.PyObject pyObject, com.inductiveautomation.ignition.common.gson.Gson customGson)
      Make a best effort to convert a PyObject into some Gson structure.
      static java.lang.Object pyToJava​(org.python.core.PyObject pyObject)
      Takes a PyObject and returns a java object, with a bit of additional logic.
      static QualityCode setArrayValue​(java.lang.Object arrayValue, java.lang.Object newVal, int pos)
      Sets a value in an array, with support for QualifiedValues and conversion of the newVal to the target type.
      static void setClassInitializer​(TypeUtilities.ClassInitializer init)
      Overrides the default class initializer.
      static java.lang.Boolean toBool​(java.lang.Object value)  
      static byte[] toByteArray​(java.util.UUID uuid)  
      static java.awt.Color toColor​(java.lang.Object color)  
      static Dataset toDataset​(java.lang.Object value)  
      static java.util.Date toDate​(java.lang.Object value)  
      static DocumentElement toDocument​(java.lang.Object value)  
      static java.lang.Double toDouble​(java.lang.Object value)  
      static <T extends java.lang.Enum>
      T      		 toEnum​(java.lang.Class<T> enumType, java.lang.String value)  
      static java.lang.Float toFloat​(java.lang.Object value)  
      static java.lang.Integer toInteger​(java.lang.Object value)  
      static java.lang.Long toLong​(java.lang.Object value)  
      static java.lang.Number toNumber​(java.lang.Object value)
      Coerces the value to a number.
      static java.lang.Number toNumber​(java.lang.String value, java.util.Locale locale)  
      static java.lang.Short toShort​(java.lang.Object value)  
      static java.lang.String toStr​(java.lang.Object value)
      Deprecated.
      use Object.toString() instead
      static java.lang.String toString​(java.lang.Object value)
      Returns the string form of a value.
      static java.lang.String toStringLocalized​(java.lang.Object value)  
      static java.lang.String toStringLocalized​(java.lang.Object value, java.util.Locale locale)
      Performs a localized stringifying/formatting of an object.
      static java.lang.String toStringOnlyNumberLocalized​(java.lang.Object value, java.util.Locale locale)
      A version of toString that only localizes numbers.
      static java.util.UUID toUUID​(byte[] barr)
      Uses a 16-byte long bytearray to create a new UUID.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • DATE_FORMAT_STRING

        public static final java.lang.String DATE_FORMAT_STRING
        See Also:
        Constant Field Values

      • _DATE_FORMATTER

        public static final java.text.DateFormat _DATE_FORMATTER
        yyyyMMdd.HHmmssSSSZ

      • NULL_SAFE_CASE_INSENSITIVE_ORDER

        public static final java.util.Comparator<java.lang.String> NULL_SAFE_CASE_INSENSITIVE_ORDER

    • Constructor Detail

      • TypeUtilities

        public TypeUtilities()

    • Method Detail

      • setClassInitializer

        public static void setClassInitializer​(TypeUtilities.ClassInitializer init)
        Overrides the default class initializer. A Class initializer knows how to create default, empty versions of various classes.

      • isProperNumber

        public static boolean isProperNumber​(java.lang.Class<?> cls)
        Returns true if the given class represents a subclass of Number, or any of the numeric primitives. Booleans are not considered proper numbers.

      • isPrimitive

        public static boolean isPrimitive​(java.lang.Class c)
        Returns true if the class is one of the java primitive classes

      • isFractional

        public static boolean isFractional​(java.lang.Class<?> cls)

      • isBoolean

        public static boolean isBoolean​(java.lang.Class<?> cls)
        True if cls == boolean.class || cls==Boolean.class

      • isNumber

        public static boolean isNumber​(java.lang.Class<?> cls)
        Returns true if the class is boolean or is a proper number.

      • isAssignable

        public static boolean isAssignable​(java.lang.Class<?> dest,
                                   java.lang.Class<?> source)
        This will return true if the setValue(Object o) knows how to coerce an object of type 'source' to an object of type 'dest'

      • isDirectlyAssignable

        public static boolean isDirectlyAssignable​(java.lang.Class<?> dest,
                                           java.lang.Class<?> source)
        Two classes are 'directly assignable' if reflection won't complain when you pass an object of type 'source' to a method which expects as an argument an object of type 'dest' For example, using reflection you can invoke the method setIntValue(int i) with an Integer object (instead of an 'int' primitive)

      • isNullOrEmpty

        public static boolean isNullOrEmpty​(java.lang.String s)
        Returns true if the String s is null or zero-length

      • compareNullHigh

        public static <T extends java.lang.Comparable<T>> int compareNullHigh​(T c1,
                                                                      T c2)
        Null-safe compare. Null is the largest value possible.

      • compareNullLow

        public static <T extends java.lang.Comparable<T>> int compareNullLow​(T c1,
                                                                     T c2)
        Null-safe compare. Null is the lowest value possible.

      • hasValueChanged

        public static boolean hasValueChanged​(QualifiedValue currentValue,
                                      QualifiedValue previousValue,
                                      DataType expectedType,
                                      java.lang.Double deadband)
        Checks whether the value and/or quality have change compared to the current value, taking into account the deadband. If expectedType is null, it will try to derive the type based on the value. Non numeric types will use straight equality.

      • equals

        public static boolean equals​(java.lang.Object o1,
                             java.lang.Object o2)
        This implementation of equals is useful in the following ways:
        • Null-safe: null==null
        • Number-safe: (new Long(0))==(new Integer(0)) and Boolean.TRUE == new Integer(1)
        • Enum-safe: enums will be compared to their integer equivalent or their name
        Other than that, it delegates to the argument's .equals functions.

      • deepEquals

        public static boolean deepEquals​(java.lang.Object o1,
                                 java.lang.Object o2,
                                 boolean checkArrayTypes)
        Like equals(Object, Object), but if the objects are arrays it delegates to Objects.deepEquals(Object, Object).

        If checkArrayTypes is true then o1 and o2 are not equal unless they are also the same type. Objects.deepEquals(Object, Object) considers two empty arrays to be equal regardless of type.

        Parameters:
        o1 - an object.
        o2 - an object to be compared to o2 for equality.
        checkArrayTypes - true if arrays must be of the same type to be considered equal.
        Returns:
        true if o1 equals o2, with consideration for arrays and checkArrayTypes.

      • equals

        public static boolean equals​(double val1,
                             double val2,
                             double tolerance)
        A special form of equals for doubles, that takes a provider tolerance into account.

      • neq

        public static boolean neq​(java.lang.Object o1,
                          java.lang.Object o2)
        Convenience for: !TypeUtilities.equals(o1,o2)

      • anyEqual

        public static <T> boolean anyEqual​(T value,
                                   T... others)
        Determines if the value is equal to any of the other values
        Parameters:
        others - vararg values to compare the the value
        Returns:
        true if the value is equal to any of the other values provided.

      • equalsIgnoreCase

        public static boolean equalsIgnoreCase​(java.lang.Object o1,
                                       java.lang.Object o2)
        Equivalent semantics to equals(Object, Object), but if both arguments are Strings, case insensitive equality will be used

      • toStringLocalized

        public static java.lang.String toStringLocalized​(@Nullable
                                                 java.lang.Object value)

      • toStringLocalized

        @Nonnull
public static java.lang.String toStringLocalized​(@Nullable
                                                 java.lang.Object value,
                                                 @Nullable
                                                 java.util.Locale locale)
        Performs a localized stringifying/formatting of an object.

        • null becomes empty string.
        • Dates use the default DateFormat for the locale
        • Numbers use NumberFormat.getInstance()
        • Colors use their hex formatting

      • toString

        @Nullable
public static java.lang.String toString​(@Nullable
                                        java.lang.Object value)
        Returns the string form of a value. Not adjusted for locale. Dates are returned in SQL format. Numbers are returned in java lang spec format. If the value is null, then null is returned.

      • fromString

        public static java.lang.Object fromString​(java.lang.String value,
                                          java.lang.Class<?> dest,
                                          java.util.Locale locale)
        A special version of coerce, knowing that the source is a string in the given locale.

      • toNumber

        public static java.lang.Number toNumber​(java.lang.Object value)
        Coerces the value to a number. If the value is already a number, it is returned like it is. If it is null, null is returned. If the value is a string, it is attempted to be parsed into a Double. Otherwise, a ClassCastException is thrown.

      • toNumber

        public static java.lang.Number toNumber​(@Nullable
                                        java.lang.String value,
                                        java.util.Locale locale)
                                 throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • coerceNumberNullSafe

        public static java.lang.Object coerceNumberNullSafe​(java.lang.Object value,
                                                    java.lang.Class destType,
                                                    java.util.Locale locale)
                                             throws java.lang.ClassCastException
        Like coerce, except that if value is null, null will be returned instead of the "default" value for the desired type. Only numbers will be localized.
        Throws:
        java.lang.ClassCastException

      • coerceNullSafe

        @Nullable
public static java.lang.Object coerceNullSafe​(java.lang.Object value,
                                              java.lang.Class destType)
                                       throws java.lang.ClassCastException
        Like coerce, except that if value is null, null will be returned instead of the "default" value for the desired type.
        Throws:
        java.lang.ClassCastException

      • coerceLocaleSafe

        public static java.lang.Object coerceLocaleSafe​(java.lang.String str,
                                                java.lang.Class type)
                                         throws java.lang.ClassCastException
        Special version of coerce that has explicit handling for String-to-Number coersions that don't depend on the current locale. If type isn't a float, double, byte, short, int, or long, it will fall back to normal coersion.
        Throws:
        java.lang.ClassCastException

      • toStringOnlyNumberLocalized

        public static java.lang.String toStringOnlyNumberLocalized​(java.lang.Object value,
                                                           java.util.Locale locale)
        A version of toString that only localizes numbers. If locale is null, the default locale will be used.

      • coerceForLocale

        public static java.lang.Object coerceForLocale​(java.lang.Object value,
                                               java.lang.Class target,
                                               java.util.Locale valueLocale)
                                        throws java.lang.ClassCastException
        A version of coerce intended to go from String to Number, where the source string is formatted for a certain locale. If locale is null, the default locale will be used.
        Throws:
        java.lang.ClassCastException

      • coerceGeneric

        public static <T> T coerceGeneric​(java.lang.Object value,
                                  java.lang.Class<? extends T> destType)
        Performs the same operation as coerce, but with generic typing.

      • coerce

        @Nonnull
public static java.lang.Object coerce​(java.lang.Object value,
                                      java.lang.Class destType)
                               throws java.lang.ClassCastException
        Attempts to coerce the Object value into an instance of the Class type. If value is null, a default instance of the type is returned. If no coercion is known, a ClassCastException is thrown.

        If coercing to a String, it is better to call toStringLocalized(val,Locale), if the locale is known.

        Throws:
        java.lang.ClassCastException

      • toEnum

        public static <T extends java.lang.Enum> T toEnum​(java.lang.Class<T> enumType,
                                                  java.lang.String value)

      • compareInts

        public static int compareInts​(int foo,
                              int bar)

      • toByteArray

        public static byte[] toByteArray​(java.util.UUID uuid)

      • toUUID

        public static java.util.UUID toUUID​(byte[] barr)
                             throws java.lang.ClassCastException
        Uses a 16-byte long bytearray to create a new UUID.
        Throws:
        java.lang.ClassCastException - if the byte array isn't exactly 16 bytes long
        java.lang.NullPointerException - if barr is null

      • toInteger

        @Nonnull
public static java.lang.Integer toInteger​(java.lang.Object value)
                                   throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • toLong

        @Nonnull
public static java.lang.Long toLong​(java.lang.Object value)
                             throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • toBool

        @Nonnull
public static java.lang.Boolean toBool​(java.lang.Object value)
                                throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • toDouble

        @Nonnull
public static java.lang.Double toDouble​(java.lang.Object value)
                                 throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • toFloat

        @Nonnull
public static java.lang.Float toFloat​(java.lang.Object value)
                               throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • toShort

        @Nonnull
public static java.lang.Short toShort​(java.lang.Object value)
                               throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • toDate

        @Nonnull
public static java.util.Date toDate​(java.lang.Object value)
                             throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • toDataset

        @Nonnull
public static Dataset toDataset​(java.lang.Object value)
                         throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • toDocument

        @Nullable
public static DocumentElement toDocument​(java.lang.Object value)
                                  throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • toStr

        @Deprecated
public static java.lang.String toStr​(java.lang.Object value)
                              throws java.lang.ClassCastException
        Deprecated.
        use Object.toString() instead
        Throws:
        java.lang.ClassCastException

      • getColorFromString

        public static java.awt.Color getColorFromString​(java.lang.String color)
        Tries to parse a Color from the given string. First it looks to see if the string is a named color in the NAMED_COLORS map. Then it tries to parse it as a web-style hex color, then it looks for RGB[A] values. If all of these attempts fail, a ClassCastException is thrown.

      • toColor

        public static java.awt.Color toColor​(java.lang.Object color)

      • colorToHex

        public static java.lang.String colorToHex​(java.awt.Color c)
        Returns the color as a web-compatible hex string. Does not include the hash sign (#) in front.

      • pyToJava

        @Nullable
public static java.lang.Object pyToJava​(@Nullable
                                        org.python.core.PyObject pyObject)
        Takes a PyObject and returns a java object, with a bit of additional logic. For example, BigInt is converted to Long, and BigDecimal is converted to Double.
        Parameters:
        pyObject - incoming value, if null, returns null.

      • gsonToPy

        public static org.python.core.PyObject gsonToPy​(@Nullable
                                                com.inductiveautomation.ignition.common.gson.JsonElement element)
        Attempt to encode a given JsonElement into base Python data structures - dictionaries for objects, lists for arrays, etc. Uses JsonUtilities.json2Java(JsonElement) to unwrap primitive values before converting to PyObjects.

      • pyToGson

        public static com.inductiveautomation.ignition.common.gson.JsonElement pyToGson​(@Nullable
                                                                                org.python.core.PyObject pyObject)
        Make a best effort to convert a PyObject into some Gson structure. Recurses, so make sure your data structure is sane.
        Parameters:
        pyObject - object to convert

      • pyToGson

        public static com.inductiveautomation.ignition.common.gson.JsonElement pyToGson​(@Nullable
                                                                                org.python.core.PyObject pyObject,
                                                                                @Nullable
                                                                                com.inductiveautomation.ignition.common.gson.Gson customGson)
        Make a best effort to convert a PyObject into some Gson structure. Recurses, so make sure your data structure is sane.
        Parameters:
        pyObject - object to convert
        customGson - A specific Gson instance to use for conversion.

      • getWrapperType

        public static java.lang.Class<?> getWrapperType​(java.lang.Class<?> c)
                                         throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • getPrimitiveType

        public static java.lang.Class<?> getPrimitiveType​(java.lang.Class<?> c)
                                           throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • hasPrimitiveType

        public static boolean hasPrimitiveType​(java.lang.Class<?> c)

      • getLastNameComponent

        public static java.lang.String getLastNameComponent​(java.lang.String name)
        Tags a string that represents a series of elements seperated by period (".") and returns the last portion.

      • getFirstOrNull

        @Nullable
public static <T> T getFirstOrNull​(java.util.List<T> list)
        Takes a list and returns the first element. If list is null or empty, returns null.
        Returns:
        the first element of the list, or null if the list is null or contains no elements.

      • setArrayValue

        public static QualityCode setArrayValue​(java.lang.Object arrayValue,
                                        java.lang.Object newVal,
                                        int pos)
        Sets a value in an array, with support for QualifiedValues and conversion of the newVal to the target type. Returns a helpful error code if the assignment isn't possible.
        Returns:
        the result of the assignment- good if successful, other quality if an error occured.

      • getInitValueForClass

        public static java.lang.Object getInitValueForClass​(java.lang.Class<?> c)
                                             throws java.lang.ClassCastException
        Throws:
        java.lang.ClassCastException

      • datasetToGson

        public static com.inductiveautomation.ignition.common.gson.JsonElement datasetToGson​(Dataset data)

      • datasetToGson

        public static com.inductiveautomation.ignition.common.gson.JsonElement datasetToGson​(Dataset data,
                                                                                     com.inductiveautomation.ignition.common.gson.Gson gson)

      • datasetFromJsonString

        public static Dataset datasetFromJsonString​(java.lang.String jsonStr)
                                     throws java.lang.Exception
        Use when you only have JSON in the form of a String
        Throws:
        java.lang.Exception

      • datasetFromJSON

        public static Dataset datasetFromJSON​(JSONObject json)
                               throws java.lang.Exception
        Throws:
        java.lang.Exception