Package com.google.api.client.util

Class Data

java.lang.Object

com.google.api.client.util.Data

public class Data
extends java.lang.Object

Utilities for working with key/value data based on the Key annotation.

Since:

1.4

Field Summary

Fields

Modifier and Type	Field	Description
static java.math.BigDecimal	NULL_BIG_DECIMAL	The single instance of the magic null object for a BigDecimal.
static java.math.BigInteger	NULL_BIG_INTEGER	The single instance of the magic null object for a BigInteger.
static java.lang.Boolean	NULL_BOOLEAN	The single instance of the magic null object for a Boolean.
static java.lang.Byte	NULL_BYTE	The single instance of the magic null object for a Byte.
private static java.util.concurrent.ConcurrentHashMap<java.lang.Class<?>,java.lang.Object>	NULL_CACHE	Cache of the magic null object for the given Java class.
static java.lang.Character	NULL_CHARACTER	The single instance of the magic null object for a Character.
static DateTime	NULL_DATE_TIME	The single instance of the magic null object for a DateTime.
static java.lang.Double	NULL_DOUBLE	The single instance of the magic null object for a Double.
static java.lang.Float	NULL_FLOAT	The single instance of the magic null object for a Float.
static java.lang.Integer	NULL_INTEGER	The single instance of the magic null object for a Integer.
static java.lang.Long	NULL_LONG	The single instance of the magic null object for a Long.
static java.lang.Short	NULL_SHORT	The single instance of the magic null object for a Short.
static java.lang.String	NULL_STRING	The single instance of the magic null object for a String.

Constructor Summary

Constructors

Constructor	Description
Data()

Method Summary

Modifier and Type	Method	Description
static <T> T	clone(T data)	Returns a deep clone of the given key/value data, such that the result is a completely independent copy.
static void	deepCopy(java.lang.Object src, java.lang.Object dest)	Makes a deep copy of the given source object into the destination object that is assumed to be constructed using Object.clone().
static boolean	isNull(java.lang.Object object)	Returns whether the given object is the magic object that represents the null value of its class.
static boolean	isPrimitive(java.lang.reflect.Type type)	Returns whether the given type is one of the supported primitive classes like number and date/time, or is a wildcard of one.
static boolean	isValueOfPrimitiveType(java.lang.Object fieldValue)	Returns whether to given value is null or its class is primitive as defined by isPrimitive(Type).
static java.util.Map<java.lang.String,java.lang.Object>	mapOf(java.lang.Object data)	Returns the map to use for the given data that is treated as a map from string key to some value.
static java.util.Collection<java.lang.Object>	newCollectionInstance(java.lang.reflect.Type type)	Returns a new collection instance for the given type.
static java.util.Map<java.lang.String,java.lang.Object>	newMapInstance(java.lang.Class<?> mapClass)	Returns a new instance of a map based on the given field class.
static <T> T	nullOf(java.lang.Class<?> objClass)	Returns the single instance of the magic object that represents the "null" value for the given Java class (including array or enum).
static java.lang.Object	parsePrimitiveValue(java.lang.reflect.Type type, java.lang.String stringValue)	Parses the given string value based on the given primitive type.
static java.lang.reflect.Type	resolveWildcardTypeOrTypeVariable(java.util.List<java.lang.reflect.Type> context, java.lang.reflect.Type type)	Aggressively resolves the given type in such a way that the resolved type is not a wildcard type or a type variable, returning Object.class if the type variable cannot be resolved.

Methods inherited from class java.lang.Object

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

Field Detail

NULL_BOOLEAN

public static final java.lang.Boolean NULL_BOOLEAN

The single instance of the magic null object for a Boolean.

NULL_STRING

public static final java.lang.String NULL_STRING

The single instance of the magic null object for a String.

NULL_CHARACTER

public static final java.lang.Character NULL_CHARACTER

The single instance of the magic null object for a Character.

NULL_BYTE

public static final java.lang.Byte NULL_BYTE

The single instance of the magic null object for a Byte.

NULL_SHORT

public static final java.lang.Short NULL_SHORT

The single instance of the magic null object for a Short.

NULL_INTEGER

public static final java.lang.Integer NULL_INTEGER

The single instance of the magic null object for a Integer.

NULL_FLOAT

public static final java.lang.Float NULL_FLOAT

The single instance of the magic null object for a Float.

NULL_LONG

public static final java.lang.Long NULL_LONG

The single instance of the magic null object for a Long.

NULL_DOUBLE

public static final java.lang.Double NULL_DOUBLE

The single instance of the magic null object for a Double.

NULL_BIG_INTEGER

public static final java.math.BigInteger NULL_BIG_INTEGER

The single instance of the magic null object for a BigInteger.

NULL_BIG_DECIMAL

public static final java.math.BigDecimal NULL_BIG_DECIMAL

The single instance of the magic null object for a BigDecimal.

NULL_DATE_TIME

public static final DateTime NULL_DATE_TIME

The single instance of the magic null object for a DateTime.

NULL_CACHE

private static final java.util.concurrent.ConcurrentHashMap<java.lang.Class<?>,java.lang.Object> NULL_CACHE

Cache of the magic null object for the given Java class.

Constructor Detail

Data

public Data()

Method Detail

nullOf

public static <T> T nullOf(java.lang.Class<?> objClass)

Returns the single instance of the magic object that represents the "null" value for the given Java class (including array or enum).

Parameters:

objClass - class of the object needed

Returns:

magic object instance that represents the "null" value (not Java null)

Throws:

java.lang.IllegalArgumentException - if unable to create a new instance

isNull

public static boolean isNull(java.lang.Object object)

Returns whether the given object is the magic object that represents the null value of its class.

Parameters:

object - object or null

Returns:

whether it is the magic null value or false for null input

mapOf

public static java.util.Map<java.lang.String,java.lang.Object> mapOf(java.lang.Object data)

Returns the map to use for the given data that is treated as a map from string key to some value.

If the input is null, it returns an empty map. If the input is a map, it simply returns the input. Otherwise, it will create a map view using reflection that is backed by the object, so that any changes to the map will be reflected on the object. The map keys of that map view are based on the Key annotation, and null is not a possible map value, although the magic null instance is possible (see nullOf(Class) and isNull(Object)). Iteration order of the data keys is based on the sorted (ascending) key names of the declared fields. Note that since the map view is backed by the object, and that the object may change, many methods in the map view must recompute the field values using reflection, for example Map.size() must check the number of non-null fields.

Parameters:

data - any key value data, represented by an object or a map, or null

Returns:

key/value map to use

clone

public static <T> T clone(T data)

Returns a deep clone of the given key/value data, such that the result is a completely independent copy.

This should not be used directly in the implementation of Object.clone(). Instead use deepCopy(Object, Object) for that purpose.

Final fields cannot be changed and therefore their value won't be copied.

Parameters:

data - key/value data object or map to clone or null for a null return value

Returns:

deep clone or null for null input

deepCopy

public static void deepCopy(java.lang.Object src,
                            java.lang.Object dest)

Makes a deep copy of the given source object into the destination object that is assumed to be constructed using Object.clone().

Example usage of this method in Object.clone():

  @Override
  public MyObject clone() {
    try {
      @SuppressWarnings("unchecked")
      MyObject result = (MyObject) super.clone();
      Data.deepCopy(this, result);
      return result;
    } catch (CloneNotSupportedException e) {
      throw new IllegalStateException(e);
    }
  }
 

Final fields cannot be changed and therefore their value won't be copied.

Parameters:

src - source object

dest - destination object of identical type as source object, and any contained arrays must be the same length

isPrimitive

public static boolean isPrimitive(java.lang.reflect.Type type)

Returns whether the given type is one of the supported primitive classes like number and date/time, or is a wildcard of one.

A primitive class is any class for whom Class.isPrimitive() is true, as well as any classes of type: Character, String, Integer, Long, Short, Byte, Float, Double, BigInteger, BigDecimal, Boolean, and DateTime.

Parameters:

type - type or null for false result

Returns:

whether it is a primitive

isValueOfPrimitiveType

public static boolean isValueOfPrimitiveType(java.lang.Object fieldValue)

Returns whether to given value is null or its class is primitive as defined by isPrimitive(Type).

parsePrimitiveValue

public static java.lang.Object parsePrimitiveValue(java.lang.reflect.Type type,
                                                   java.lang.String stringValue)

Parses the given string value based on the given primitive type.

Types are parsed as follows:

• Void: null
• null or is assignable from String (like Object): no parsing
• char or Character: String.charAt(0) (requires length to be exactly 1)
• boolean or Boolean: Boolean.valueOf(String)
• byte or Byte: Byte.valueOf(String)
• short or Short: Short.valueOf(String)
• int or Integer: Integer.valueOf(String)
• long or Long: Long.valueOf(String)
• float or Float: Float.valueOf(String)
• double or Double: Double.valueOf(String)
• BigInteger: BigInteger(String)
• BigDecimal: BigDecimal(String)
• DateTime: DateTime.parseRfc3339(String)

Note that this may not be the right behavior for some use cases.

Parameters:

type - primitive type or null to parse as a string

stringValue - string value to parse or null for null result

Returns:

parsed object or null for null input

Throws:

java.lang.IllegalArgumentException - if the given class is not a primitive class

newCollectionInstance

public static java.util.Collection<java.lang.Object> newCollectionInstance(java.lang.reflect.Type type)

Returns a new collection instance for the given type.

Creates a new collection instance specified for the first input collection class that matches as follows:

• null or an array or assignable from ArrayList (like List or Collection or Object): returns an ArrayList
• assignable from HashSet: returns a HashSet
• assignable from TreeSet: returns a TreeSet
• else: calls Types.newInstance(Class)

Parameters:

type - type or null for ArrayList.

Returns:

new collection instance

Throws:

java.lang.ClassCastException - if result is does not extend Collection

newMapInstance

public static java.util.Map<java.lang.String,java.lang.Object> newMapInstance(java.lang.Class<?> mapClass)

Returns a new instance of a map based on the given field class.

Creates a new map instance specified for the first input map class that matches as follows:

• null or assignable from ArrayMap (like Map or Object): returns an ArrayMap
• assignable from TreeMap (like SortedMap): returns a TreeMap
• else: calls Types.newInstance(Class)

Parameters:

mapClass - field class

Throws:

java.lang.ClassCastException - if result is does not extend Map

resolveWildcardTypeOrTypeVariable

public static java.lang.reflect.Type resolveWildcardTypeOrTypeVariable(java.util.List<java.lang.reflect.Type> context,
                                                                       java.lang.reflect.Type type)

Aggressively resolves the given type in such a way that the resolved type is not a wildcard type or a type variable, returning Object.class if the type variable cannot be resolved.

Parameters:

context - context list, ordering from least specific to most specific type context, for example container class and then its field

type - type or null for null result

Returns:

resolved type (which may be class, parameterized type, or generic array type, but not wildcard type or type variable) or null for null input