Module org.apache.sis.metadata
Package org.apache.sis.util.iso

# Class DefaultRecordSchema

Object
DefaultRecordSchema

All Implemented Interfaces:
  `RecordSchema`

public class DefaultRecordSchema extends Object implements RecordSchema
A collection of record types in a given namespace. This class works also as a factory for creating `RecordType` and `Record` instances. The factory methods are:

- `createRecordType(CharSequence, Map)`

Subclasses can modify the characteristics of the records to be created by overriding the following methods:

- `DefaultNameFactory​.toTypeName(Class)` if the factory given to the constructor.

## Thread safety

The same `DefaultRecordSchema` instance can be safely used by many threads without synchronization on the part of the caller if the `NameFactory` given to the constructor is also thread-safe. Subclasses should make sure that any overridden methods remain safe to call from multiple threads.

## Limitations

This class is currently not serializable because `RecordSchema` contain an arbitrary number of record types in its description map. Since each `RecordType` has a reference to its schema, serializing a single `RecordType` could imply serializing all of them. In order to reduce the risk of unexpected behavior, serialization is currently left to subclasses. For example, a subclass may define a `Object readResolve()` method (as documented in the `Serializable` interface) returning a system-wide static constant for their schema.

Since:
  0.5
See Also:
  - `DefaultRecordType`
  - `DefaultRecord`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final DefaultNameFactory`
  `nameFactory`
  The factory to use for creating names.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultRecordSchema(DefaultNameFactory nameFactory, NameSpace parent, CharSequence schemaName)`
  Creates a new schema of the given name.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `RecordType`
  `createRecordType(CharSequence typeName, Map<CharSequence,Class<?>> fields)`
  Creates a new record type of the given name, which will contain the given fields.
  `TypeName`
  `createRecordTypeName(CharSequence typeName)`
  Creates the name of a record.
  `Map<TypeName,RecordType>`
  `getDescription()`
  Returns the dictionary of all (name, record type) pairs in this schema.
  `LocalName`
  `getSchemaName()`
  Returns the schema name.
  `RecordType`
  `locate(TypeName name)`
  Returns the record type for the given name.
  `String`
  `toString()`
  Returns a string representation of this schema for debugging purpose only.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### nameFactory

    protected final DefaultNameFactory nameFactory
    The factory to use for creating names. This is the factory given at construction time.
    Upcoming API change — generalization
    This field type will be changed to the `NameFactory` interface when that interface will provide a `createMemberName(…)` method (tentatively in GeoAPI 3.1).

- ## Constructor Details

  - ### DefaultRecordSchema

    public DefaultRecordSchema(DefaultNameFactory nameFactory, NameSpace parent, CharSequence schemaName)
    Creates a new schema of the given name.
    Upcoming API change — generalization
    This type of the first argument will be changed to the `NameFactory` interface when that interface will provide a `createMemberName(…)` method (tentatively in GeoAPI 3.1).
    Parameters:
      `nameFactory` - the factory to use for creating names, or `null` for the default factory.
      `parent` - the parent namespace, or `null` if none.
      `schemaName` - the name of the new schema.

- ## Method Details

  - ### getSchemaName

    public LocalName getSchemaName()
    Returns the schema name.
    Specified by:
      `getSchemaName` in interface `RecordSchema`
    Returns:
      the schema name.

  - ### createRecordTypeName

    public TypeName createRecordTypeName(CharSequence typeName)
    Creates the name of a record.
    Parameters:
      `typeName` - name of the record type to create.
    Returns:
      name of a record type.
    Since:
      1.3

  - ### createRecordType

    public RecordType createRecordType(CharSequence typeName, Map<CharSequence,Class<?>> fields) throws IllegalArgumentException
    Creates a new record type of the given name, which will contain the given fields. Fields are declared in iteration order.
    Parameters:
      `typeName` - name of the record type to create.
      `fields` - the name of each record field, together with the expected value types.
    Returns:
      a record type of the given name and fields.
    Throws:
      `IllegalArgumentException` - if a record already exists for the given name but with different fields.

  - ### getDescription

    public Map<TypeName,RecordType> getDescription()
    Returns the dictionary of all (name, record type) pairs in this schema.
    Specified by:
      `getDescription` in interface `RecordSchema`
    Returns:
      all (name, record type) pairs in this schema.

  - ### locate

    public RecordType locate(TypeName name)
    Returns the record type for the given name. If the type name is not defined within this schema, then this method returns `null`.
    Specified by:
      `locate` in interface `RecordSchema`
    Parameters:
      `name` - the name of the type to lookup.
    Returns:
      the type for the given name, or `null` if none.

  - ### toString

    public String toString()
    Returns a string representation of this schema for debugging purpose only.
    Overrides:
      `toString` in class `Object`