Package com.inductiveautomation.ignition.common

Class TypeUtilities

java.lang.Object

com.inductiveautomation.ignition.common.TypeUtilities

public class TypeUtilities
extends Object

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	TypeUtilities.ClassInitializer
protected static class	TypeUtilities.DefaultClassInitializer	Initializes most basic classes.

Field Summary

Fields

Modifier and Type	Field	Description
static final DateFormat	_DATE_FORMATTER	yyyyMMdd.HHmmssSSSZ
static final String	DATE_FORMAT_STRING
static final Comparator<String>	NULL_SAFE_CASE_INSENSITIVE_ORDER
static final String	RFC_2339_LOCAL_DATETIME	A fully specified date & time, without timezone.

Constructor Summary

Constructors

Constructor	Description
TypeUtilities()

Method Summary

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 Object	coerce(Object value, Class destType)	Attempts to coerce the Object value into an instance of the Class type.
static Date	coerceDateForLocale(String value, Locale locale)
static Object	coerceForLocale(Object value, Class target, Locale valueLocale)	A version of coerce intended to go from String to Number, where the source string is formatted for a certain locale.
static Object	coerceFromDataset(Dataset dataset, Class<?> destType)
static <T> T	coerceGeneric(Object value, Class<? extends T> destType)	Performs the same operation as coerce, but with generic typing.
static Object	coerceLocaleSafe(String str, Class type)	Special version of coerce that has explicit handling for String-to-Number coersions that don't depend on the current locale.
static Object	coerceNullSafe(Object value, Class destType)	Like coerce, except that if value is null, null will be returned instead of the "default" value for the desired type.
static Object	coerceNumberForLocale(Object value, Class destType, Locale locale)	Delegates to coerce(Object, Class) if the destType is a number and the value is null or a blank String, otherwise delegates to coerceForLocale(Object, Class, Locale)
static Object	coerceNumberNullSafe(Object value, Class destType, Locale locale)	Like coerce, except that if value is null, null will be returned instead of the "default" value for the desired type.
static Object	coerceTimestamp(Timestamp value, Class<?> destType)
static String	colorToHex(Color c)	Returns the color as a web-compatible hex string.
static int	compareInts(int foo, int bar)
static <T extends Comparable<T>> int	compareNullHigh(T c1, T c2)	Null-safe compare.
static <T extends Comparable<T>> int	compareNullLow(T c1, T c2)	Null-safe compare.
static Dataset	datasetFromJSON(JSONObject json)
static Dataset	datasetFromJsonString(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(Object o1, 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(Object o1, 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(Object o1, Object o2)	Equivalent semantics to equals(Object, Object), but if both arguments are Strings, case insensitive equality will be used
static Object	fromString(String value, Class<?> dest, Locale locale)	A special version of coerce, knowing that the source is a string in the given locale.
static Color	getColorFromString(String color)	Tries to parse a Color from the given string.
static <T> T	getFirstOrNull(List<T> list)	Takes a list and returns the first element.
static Object	getInitValueForClass(Class<?> c)
static String	getLastNameComponent(String name)	Tags a string that represents a series of elements seperated by period (".") and returns the last portion.
static Class<?>	getPrimitiveType(Class<?> c)
static Class<?>	getWrapperType(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(Class<?> c)
static boolean	hasValueChanged(QualifiedValue currentValue, QualifiedValue previousValue, DataType expectedType, Double deadband)	Checks whether the value and/or quality have change compared to the current value, taking into account the deadband.
static boolean	isAssignable(Class<?> dest, 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(Class<?> cls)	True if cls == boolean.class || cls==Boolean.class
static boolean	isDirectlyAssignable(Class<?> dest, 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(Class<?> cls)
static boolean	isNullOrEmpty(String s)	Returns true if the String s is null or zero-length
static boolean	isNumber(Class<?> cls)	Returns true if the class is boolean or is a proper number.
static boolean	isPrimitive(Class c)	Returns true if the class is one of the java primitive classes
static boolean	isProperNumber(Class<?> cls)	Returns true if the given class represents a subclass of Number, or any of the numeric primitives.
static boolean	neq(Object o1, 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 Object	pyToJava(org.python.core.PyObject pyObject)	Takes a PyObject and returns a java object, with a bit of additional logic.
static QualityCode	setArrayValue(Object arrayValue, 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 Boolean	toBool(Object value)
static byte[]	toByteArray(UUID uuid)
static Color	toColor(Object color)
static Dataset	toDataset(Object value)
static Date	toDate(Object value)
static DocumentElement	toDocument(Object value)
static Double	toDouble(Object value)
static <T extends Enum> T	toEnum(Class<T> enumType, String value)
static Float	toFloat(Object value)
static Integer	toInteger(Object value)
static Long	toLong(Object value)
static Number	toNumber(Object value)	Coerces the value to a number.
static Number	toNumber(String value, Locale locale)
static Short	toShort(Object value)
static String	toStr(Object value)	Deprecated. use Object.toString() instead
static String	toString(Object value)	Returns the string form of a value.
static String	toStringLocalized(Object value)
static String	toStringLocalized(Object value, Locale locale)	Performs a localized stringifying/formatting of an object.
static String	toStringOnlyNumberLocalized(Object value, Locale locale)	A version of toString that only localizes numbers.
static 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 Details

DATE_FORMAT_STRING

public static final String DATE_FORMAT_STRING

See Also:

• Constant Field Values

_DATE_FORMATTER

public static final DateFormat _DATE_FORMATTER

yyyyMMdd.HHmmssSSSZ

RFC_2339_LOCAL_DATETIME

public static final String RFC_2339_LOCAL_DATETIME

A fully specified date & time, without timezone.
yyyy-MM-dd HH:mm:ss.SSS

See Also:

• Constant Field Values

NULL_SAFE_CASE_INSENSITIVE_ORDER

public static final Comparator<String> NULL_SAFE_CASE_INSENSITIVE_ORDER

Constructor Details

TypeUtilities

public TypeUtilities()

Method Details

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(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(Class c)

Returns true if the class is one of the java primitive classes

isFractional

public static boolean isFractional(Class<?> cls)

isBoolean

public static boolean isBoolean(Class<?> cls)

True if cls == boolean.class || cls==Boolean.class

isNumber

public static boolean isNumber(Class<?> cls)

Returns true if the class is boolean or is a proper number.

isAssignable

public static boolean isAssignable(Class<?> dest,
 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(Class<?> dest,
 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(String s)

Returns true if the String s is null or zero-length

compareNullHigh

public static <T extends Comparable<T>> int compareNullHigh(T c1,
 T c2)

Null-safe compare. Null is the largest value possible.

compareNullLow

public static <T extends 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,
 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(Object o1,
 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(Object o1,
 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(Object o1,
 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(Object o1,
 Object o2)

Equivalent semantics to equals(Object, Object), but if both arguments are Strings, case insensitive equality will be used

toStringLocalized

public static String toStringLocalized(@Nullable
 Object value)

toStringLocalized

@Nonnull
public static String toStringLocalized(@Nullable
 Object value,
 @Nullable
 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 String toString(@Nullable
 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 Object fromString(String value,
 Class<?> dest,
 Locale locale)

A special version of coerce, knowing that the source is a string in the given locale.

toNumber

public static Number toNumber(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 Number toNumber(@Nullable
 String value,
 Locale locale)
                       throws ClassCastException

Throws:

ClassCastException

coerceNumberNullSafe

public static Object coerceNumberNullSafe(Object value,
 Class destType,
 Locale locale)
                                   throws 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:

ClassCastException

coerceNumberForLocale

public static Object coerceNumberForLocale(Object value,
 Class destType,
 Locale locale)

Delegates to coerce(Object, Class) if the destType is a number and the value is null or a blank String, otherwise delegates to coerceForLocale(Object, Class, Locale)

coerceNullSafe

@Nullable
public static Object coerceNullSafe(Object value,
 Class destType)
                             throws ClassCastException

Like coerce, except that if value is null, null will be returned instead of the "default" value for the desired type.

Throws:

ClassCastException

coerceLocaleSafe

public static Object coerceLocaleSafe(String str,
 Class type)
                               throws 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:

ClassCastException

toStringOnlyNumberLocalized

public static String toStringOnlyNumberLocalized(Object value,
 Locale locale)

A version of toString that only localizes numbers. If locale is null, the default locale will be used.

coerceForLocale

public static Object coerceForLocale(Object value,
 Class target,
 Locale valueLocale)
                              throws 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:

ClassCastException

coerceDateForLocale

public static Date coerceDateForLocale(String value,
 Locale locale)
                                throws ClassCastException

Throws:

ClassCastException

coerceGeneric

public static <T> T coerceGeneric(Object value,
 Class<? extends T> destType)

Performs the same operation as coerce, but with generic typing.

coerceTimestamp

public static Object coerceTimestamp(Timestamp value,
 Class<?> destType)
                              throws ClassCastException

Throws:

ClassCastException

coerceFromDataset

public static Object coerceFromDataset(Dataset dataset,
 Class<?> destType)
                                throws ClassCastException

Throws:

ClassCastException

coerce

@Nonnull
public static Object coerce(Object value,
 Class destType)
                     throws 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:

ClassCastException

toEnum

public static <T extends Enum> T toEnum(Class<T> enumType,
 String value)

compareInts

public static int compareInts(int foo,
 int bar)

toByteArray

public static byte[] toByteArray(UUID uuid)

toUUID

public static UUID toUUID(byte[] barr)
                   throws ClassCastException

Uses a 16-byte long bytearray to create a new UUID.

Throws:

ClassCastException - if the byte array isn't exactly 16 bytes long

NullPointerException - if barr is null

toInteger

@Nonnull
public static Integer toInteger(Object value)
                         throws ClassCastException

Throws:

ClassCastException

toLong

@Nonnull
public static Long toLong(Object value)
                   throws ClassCastException

Throws:

ClassCastException

toBool

@Nonnull
public static Boolean toBool(Object value)
                      throws ClassCastException

Throws:

ClassCastException

toDouble

@Nonnull
public static Double toDouble(Object value)
                       throws ClassCastException

Throws:

ClassCastException

toFloat

@Nonnull
public static Float toFloat(Object value)
                     throws ClassCastException

Throws:

ClassCastException

toShort

@Nonnull
public static Short toShort(Object value)
                     throws ClassCastException

Throws:

ClassCastException

toDate

@Nonnull
public static Date toDate(Object value)
                   throws ClassCastException

Throws:

ClassCastException

toDataset

@Nonnull
public static Dataset toDataset(Object value)
                         throws ClassCastException

Throws:

ClassCastException

toDocument

@Nullable
public static DocumentElement toDocument(Object value)
                                  throws ClassCastException

Throws:

ClassCastException

toStr

@Deprecated
public static String toStr(Object value)
                    throws ClassCastException

Deprecated.

use Object.toString() instead

Throws:

ClassCastException

getColorFromString

public static Color getColorFromString(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 Color toColor(Object color)

colorToHex

public static String colorToHex(Color c)

Returns the color as a web-compatible hex string. Does not include the hash sign (#) in front.

pyToJava

@Nullable
public static 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 Class<?> getWrapperType(Class<?> c)
                               throws ClassCastException

Throws:

ClassCastException

getPrimitiveType

public static Class<?> getPrimitiveType(Class<?> c)
                                 throws ClassCastException

Throws:

ClassCastException

hasPrimitiveType

public static boolean hasPrimitiveType(Class<?> c)

getLastNameComponent

public static String getLastNameComponent(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(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(Object arrayValue,
 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 Object getInitValueForClass(Class<?> c)
                                   throws ClassCastException

Throws:

ClassCastException

datasetToJSON

public static JSONObject datasetToJSON(Dataset data)

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(String jsonStr)
                                     throws Exception

Use when you only have JSON in the form of a String

Throws:

Exception

datasetFromJSON

public static Dataset datasetFromJSON(JSONObject json)
                               throws Exception

Throws:

Exception