Package org.apache.sis.util.iso

## Class DefaultRecordType

- Object
- - DefaultRecordType

- All Implemented Interfaces:
    `Serializable`, `RecordType`, `Type`

      public class DefaultRecordType
      extends Object
      implements RecordType, Serializable

  An immutable definition of the type of a record. A `RecordType` is identified by a type name and contains an arbitrary amount of members as (name, type) pairs. A `RecordType` may therefore contain another `RecordType` as a member.
  Comparison with Java reflection: `RecordType` instances can be though as equivalent to instances of the Java `Class` class. The set of members in a `RecordType` can be though as equivalent to the set of fields in a class.
  Instantiation
  The easiest way to create `DefaultRecordType` instances is to use the `DefaultRecordSchema​.createRecordType(CharSequence, Map)` method. Example:

  >     DefaultRecordSchema schema = new DefaultRecordSchema(null, null, "MySchema");
  >     // The same instance can be reused for all records to create in that schema.

  >     Map<CharSequence,Class<?>> members = new LinkedHashMap<>();
  >     members.put("city",        String .class);
  >     members.put("latitude",    Double .class);
  >     members.put("longitude",   Double .class);
  >     members.put("population",  Integer.class);
  >     RecordType record = schema.createRecordType("MyRecordType", members);

  Immutability and thread safety
  This class is immutable and thus inherently thread-safe if the `TypeName`, the `RecordSchema` and all (`MemberName`, `Type`) entries in the map given to the constructor are also immutable. Subclasses shall make sure that any overridden methods remain safe to call from multiple threads and do not change any public `RecordType` state.
  Serialization
  This class is serializable if all elements given to the constructor are also serializable. Note in particular that `DefaultRecordSchema` is currently not serializable, so users wanting serialization may need to provide their own schema.
  Since:
    0.3
  See Also:
    `DefaultRecord`, `DefaultRecordSchema`, `DefaultMemberName`, Serialized Form

  Defined in the `sis-metadata` module

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DefaultRecordType​(RecordType other)` | Creates a new record with the same names and members than the given one.
    `DefaultRecordType​(TypeName typeName, RecordSchema container, Map<? extends MemberName,​? extends Type> members)` | Creates a new record in the given schema.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static DefaultRecordType` | `castOrCopy​(RecordType other)` | Returns a SIS implementation with the name and members of the given arbitrary implementation.
    `boolean` | `equals​(Object other)` | Compares the given object with this `RecordType` for equality.
    `RecordSchema` | `getContainer()` | Returns the schema that contains this record type.
    `Set<MemberName>` | `getMembers()` | Returns the set of attribute names defined in this `RecordType`'s dictionary.
    `Map<MemberName,​Type>` | `getMemberTypes()` | Returns the dictionary of all (name, type) pairs in this record type.
    `TypeName` | `getTypeName()` | Returns the name that identifies this record type.
    `int` | `hashCode()` | Returns a hash code value for this `RecordType`.
    `boolean` | `isInstance​(Record record)` | Determines if the given record is compatible with this record type.
    `TypeName` | `locate​(MemberName memberName)` | Returns the type associated to the given attribute name, or `null` if none.
    `String` | `toString()` | Returns a string representation of this object.

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### DefaultRecordType

          public DefaultRecordType​(RecordType other)

      Creates a new record with the same names and members than the given one.
      Parameters:
        `other` - the `RecordType` to copy.

    - #### DefaultRecordType

          public DefaultRecordType​(TypeName typeName,
                                   RecordSchema container,
                                   Map<? extends MemberName,​? extends Type> members)

      Creates a new record in the given schema. It is caller responsibility to add the new `RecordType` in the container description map, if desired.

      This constructor is provided mostly for developers who want to create `DefaultRecordType` instances in their own `RecordSchema` implementation. Otherwise if the default record schema implementation is sufficient, the `DefaultRecordSchema​.createRecordType(CharSequence, Map)` method provides an easier alternative.

      Parameters:
        `typeName` - the name that identifies this record type.
        `container` - the schema that contains this record type.
        `members` - the name and type of the members to be included in this record type.
      See Also:
        `DefaultRecordSchema​.createRecordType(CharSequence, Map)`

  - ### Method Detail

    - #### castOrCopy

          public static DefaultRecordType castOrCopy​(RecordType other)

      Returns a SIS implementation with the name and members of the given arbitrary implementation. This method performs the first applicable action in the following choices:
      - If the given object is `null`, then this method returns `null`.
      - Otherwise if the given object is already an instance of `DefaultRecordType`, then it is returned unchanged.
      - Otherwise a new `DefaultRecordType` instance is created using the copy constructor and returned. Note that this is a shallow copy operation, since the members contained in the given object are not recursively copied.
      Parameters:
        `other` - the object to get as a SIS implementation, or `null` if none.
      Returns:
        a SIS implementation containing the members of the given object (may be the given object itself), or `null` if the argument was `null`.

    - #### getTypeName

          public TypeName getTypeName()

      Returns the name that identifies this record type. If this `RecordType` is contained in a record schema, then the record type name shall be valid in the name space of the record schema:

      >     NameSpace namespace = getContainer().getSchemaName().scope()

      Comparison with Java reflection: If we think about this `RecordType` as equivalent to a `Class` instance, then this method can be think as the equivalent of the Java `Class​.getName()` method.
      Specified by:
        `getTypeName` in interface `RecordType`
      Specified by:
        `getTypeName` in interface `Type`
      Returns:
        the name that identifies this record type.

    - #### getContainer

          public RecordSchema getContainer()

      Returns the schema that contains this record type.
      Specified by:
        `getContainer` in interface `RecordType`
      Returns:
        the schema that contains this record type.

    - #### getMemberTypes

          public Map<MemberName,​Type> getMemberTypes()

      Returns the dictionary of all (name, type) pairs in this record type. The returned map is unmodifiable.
      Comparison with Java reflection: If we think about this `RecordType` as equivalent to a `Class` instance, then this method can be though as the related to the Java `Class​.getFields()` method.
      Specified by:
        `getMemberTypes` in interface `RecordType`
      Returns:
        the dictionary of (name, type) pairs, or an empty map if none.

    - #### getMembers

          public Set<MemberName> getMembers()

      Returns the set of attribute names defined in this `RecordType`'s dictionary. This method is functionally equivalent to:

      >     getMemberTypes().keySet();

      Specified by:
        `getMembers` in interface `RecordType`
      Returns:
        the set of attribute names, or an empty set if none.

    - #### locate

          public TypeName locate​(MemberName memberName)

      Returns the type associated to the given attribute name, or `null` if none. This method is functionally equivalent to (omitting the check for null value):

      >     getMemberTypes().get(memberName).getTypeName();

      Comparison with Java reflection: If we think about this `RecordType` as equivalent to a `Class` instance, then this method can be though as related to the Java `Class​.getField(String)` method.
      Specified by:
        `locate` in interface `RecordType`
      Parameters:
        `memberName` - the attribute name for which to get the associated type name.
      Returns:
        the associated type name, or `null` if none.

    - #### isInstance

          public boolean isInstance​(Record record)

      Determines if the given record is compatible with this record type. This method returns `true` if the given `record` argument is non-null and the following condition holds:

      >     Set<MemberName> attributeNames = record.getAttributes().keySet();
      >     boolean isInstance = getMembers().containsAll(attributeNames);

      Implementation note: We do not require that `record​.getRecordType() == this` in order to allow record "sub-types" to define additional fields, in a way similar to Java sub-classing.
      Specified by:
        `isInstance` in interface `RecordType`
      Parameters:
        `record` - the record to test for compatibility.
      Returns:
        `true` if the given record is compatible with this `RecordType`.

    - #### equals

          public boolean equals​(Object other)

      Compares the given object with this `RecordType` for equality.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `other` - the object to compare with this `RecordType`.
      Returns:
        `true` if both objects are equal.

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this `RecordType`.
      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Returns a string representation of this object. The string representation is for debugging purpose and may change in any future SIS version.
      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of this record type.