Package nz.org.riskscape.engine

Class Tuple

java.lang.Object
nz.org.riskscape.engine.Tuple
public class Tuple extends Object

Offers quick, efficient, Map-like storage (populating the map is 100% quicker than a HashMap where the keys are defined according to a Struct. Random access to values is slightly slower (~30%) than with a standard HashMap. Does not guarantee type correctness in the same way that the Value class does

Tuples are used to store user data as it flows through the pipeline. A tuple is a set of attributes (e.g. a row of input data), but tuples can also be comprised of other tuples (e.g. the 'exposure' tuple contains all the exposure-layer attributes). When a tuple is passed to a user's Python function, it gets converted into a Python dictionary.

  • Field Details

    • EMPTY_TUPLE

      public static final Tuple EMPTY_TUPLE

      'Helpful' constant for an empty tuple - built from Struct.EMPTY_STRUCT

  • Constructor Details

  • Method Details

    • of

      public static Tuple of(Struct type)

      Convenience constructor for building an empty tuple of this type

    • of

      public static Tuple of(Struct type, String key, Object value)

      Convenience constructor for building a tuple with a single key/value

    • of

      public static Tuple of(Struct type, String key1, Object value1, String key2, Object value2)

      Convenience constructor for building a tuple with two keys/values

    • ofValues

      public static Tuple ofValues(Struct type, Object... values)

      Convenience constructor for building a tuple from an ordered (wrt to the struct) set of values

    • coerce

      public static Tuple coerce(Struct type, Map<?,?> rawValues)

    • coerce

      public static Tuple coerce(Struct type, Map<?,?> rawValues, EnumSet<Tuple.CoerceOptions> options)

      Build a tuple from the given map, applying the type's coercion to the result.

      Parameters:
      type - The type to coerce the map to
      rawValues - A map of uncoerced values
      options - Options for error handling
      Returns:
      a fresh tuple

    • set

      public Tuple set(@NonNull @NonNull String key, Object value)

      Set a value by its key

      Returns:
      this to allow tuple.set("foo", bar).set("baz", foo)...
      Throws:
      NoSuchMemberException - if no member named key in underlying struct

    • set

      public Tuple set(@NonNull @NonNull Struct.StructMember key, Object value)

      Set a value using a Struct.StructMember as a key

      Returns:
      this to allow tuple.set("foo", bar).set("baz", foo)...
      Throws:
      IllegalArgumentException - if key doesn't belong to struct this tuple is of

    • set

      public Tuple set(int index, Object value)

      Set a value using its struct index

    • setAll

      public void setAll(List<Object> values)

      Populate this tuple with the given values

    • setAll

      public void setAll(int destOffset, Tuple source)

      Copies (appends) the values from the given source tuple into this tuple. Useful when merging or combining tuples together

      Parameters:
      source - Tuple containing the values to copy
      destOffset - The struct index in this tuple to start copying into

    • setAll

      public void setAll(Tuple source)

      Copies the values from the given source tuple into this tuple.

    • remove

      public void remove(@NonNull @NonNull String key)

      Clears a value from the tuple

    • remove

      public void remove(@NonNull @NonNull Struct.StructMember key)

      Clears a value from the tuple

    • fetch

      public <T> T fetch(String key)

      Return a value from the tuple, with an implicit cast to the receiving type

    • fetch

      public <T> T fetch(Struct.StructMember entry)

      Return a value from the tuple, with an implicit cast to the receiving type

      Parameters:
      entry - the member of the struct we're fetching. Slightly more efficient than lookup by key

    • fetch

      public <T> T fetch(int index)

    • fetchChild

      public Tuple fetchChild(String key)

      TBD is this actually necessary?

    • getType

      public Type getType(String key)

      Shortcut for accessing the type of a member

      Parameters:
      key -
      Returns:
      Type of member

    • clone

      public Tuple clone()

      Perform a tuple-aware clone of this tuple, performing a shallow copy of the entry array, unless the entry is itself a tuple, which will be recursively cloned

      Overrides:
      clone in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object rhs)
      Overrides:
      equals in class Object

    • size

      public int size()

    • hasNulls

      public boolean hasNulls()
      Returns:
      if any of this tuples entries are null.

    • hasRequiredNulls

      public boolean hasRequiredNulls()
      Returns:
      if any of this tuples non-nullable entries are null.

    • estimateSize

      public int estimateSize()

      Estimate the number of bytes used to store this Tuple when serialized.

      Returns:
      the number of bytes.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getValues

      public List<Object> getValues()
      Returns:
      a read-only view on to the underlying values that back this tuple

    • toMap

      public Map<String,Object> toMap()

    • toArray

      public Object[] toArray()

    • getStruct

      public Struct getStruct()

      The struct defines the shape of the data - the attribute keys and what RiskScape Type they are.