Class MetadataStandard

Object
MetadataStandard
All Implemented Interfaces:
Serializable
public class MetadataStandard extends Object implements Serializable
Enumeration of some metadata standards. A standard is defined by a set of Java interfaces in a specific package or sub-packages. For example, the ISO 19115 standard is defined by GeoAPI interfaces in the org​.opengis​.metadata package and sub-packages.

This class provides some methods operating on metadata instances through Java reflection. The following rules are assumed:

  • Metadata properties are defined by the collection of following getter methods found in the interface, ignoring implementation methods:
    • get*() methods with arbitrary return type;
    • or is*() methods with boolean return type.
  • All properties are readable.
  • A property is also writable if a set*(…) method is defined in the implementation class for the corresponding getter method. The setter method does not need to be defined in the interface.
An instance of Metadata­Standard is associated with every Abstract­Metadata objects. The Abstract­Metadata base class usually form the basis of ISO 19115 implementations but can also be used for other standards.

Defining new Metadata­Standard instances

Users should use the predefined constants when applicable. However if new instances need to be defined, then there is a choice:
  • For read-only metadata, Metadata­Standard can be instantiated directly. Only getter methods will be used and all operations that modify the metadata properties will throw an Unmodifiable­Metadata­Exception.
  • For read/write metadata, the get­Implementation(Class) method must be overridden in a Metadata­Standard subclass.

Thread safety

The same Metadata­Standard instance can be safely used by many threads without synchronization on the part of the caller. Subclasses shall make sure that any overridden methods remain safe to call from multiple threads, because the same Metadata­Standard instances are typically referenced by a large number of Modifiable­Metadata instances.
Since:
0.3
See Also:

  • Field Details

    • ISO_19115

      public static final MetadataStandard ISO_19115
      An instance working on ISO 19115 standard as defined by GeoAPI interfaces in the org​.opengis​.metadata package and sub-packages, except quality.

    • ISO_19157

      public static final MetadataStandard ISO_19157
      An instance working on ISO 19157 standard as defined by GeoAPI interfaces in the org​.opengis​.metadata​.quality package.
      Since:
      1.3

    • ISO_19111

      public static final MetadataStandard ISO_19111
      An instance working on ISO 19111 standard as defined by GeoAPI interfaces in the org​.opengis​.referencing package and sub-packages.

    • ISO_19123

      public static final MetadataStandard ISO_19123
      An instance working on ISO 19123 standard as defined by GeoAPI interfaces in the org​.opengis​.coverage package and sub-packages.

  • Constructor Details

    • MetadataStandard

      public MetadataStandard(Citation citation, Package interfacePackage, MetadataStandard... dependencies)
      Creates a new instance working on implementation of interfaces defined in the specified package. If this Metadata­Standard does not support a given class, then the dependencies will be tested in the order declared to this constructor. Consequently, if is­Metadata(Class) may return true for two or more dependencies, then the dependency which should have precedence should be declared first.

      Example

      For the ISO 19157 standard reflected by GeoAPI interfaces, interface­Package shall be the org​.opengis​.metadata​.quality package. Its dependency is ISO_19115 in the org​.opengis​.metadata package.
      Parameters:
      citation - bibliographical reference to the international standard.
      interface­Package - the root package for metadata interfaces.
      dependencies - the dependencies to other metadata standards.

  • Method Details

    • forClass

      public static MetadataStandard forClass(Class<?> type)
      Returns the metadata standard for the given class. The argument given to this method can be either an interface defined by the standard, or a class implementing such interface. If the class implements more than one interface, then the first interface recognized by this method, in declaration order, will be retained.

      The current implementation recognizes only the standards defined by the public static constants defined in this class. A future SIS version may recognize user-defined constants.

      Parameters:
      type - the metadata standard interface, or an implementation class.
      Returns:
      the metadata standard for the given type, or null if not found.

    • getCitation

      public Citation getCitation()
      Returns a bibliographical reference to the international standard. The default implementation return the citation given at construction time.
      Returns:
      bibliographical reference to the international standard.

    • isMetadata

      public boolean isMetadata(Class<?> type)
      Returns true if the given type is assignable to a type from this standard or one of its dependencies. If this method returns true, then a call to get­Interface(Class) with the same argument will not throw Class­Cast­Exception. Note however that get­Interface(type) may throw Illegal­Argument­Exception if the given type is ambiguous.
      Parameters:
      type - the implementation class (can be null).
      Returns:
      true if the given class is an interface of this standard, or is a subtype of at least one interface of this standard.

    • getInterface

      public <T> Class<? super T> getInterface(Class<T> type)
      Returns the metadata interface implemented by the specified implementation class. If the given type is already an interface from this standard, then that type is returned directly. If the given type does not implement an interface from this standard, then a Class­Cast­Exception is thrown. If the given type implements more than one interface from this standard, then an Illegal­Argument­Exception is thrown because of the ambiguity.
      Note: in this context, "interface" should be understood as "the type which is defining the public API". This is usually an interface in the Java sense, but not always.
      Type Parameters:
      T - the compile-time type.
      Parameters:
      type - the implementation class.
      Returns:
      the interface implemented by the given implementation class.
      Throws:
      Class­Cast­Exception - if the given type does not implement an interface of this standard.
      Illegal­Argument­Exception - if the given type implements more than one interface of this standard.
      See Also:

    • getInterface

      public <T> Class<? super T> getInterface(Class<T> type, Class<?> baseType)
      Returns the metadata interface by choosing in a subset of the interfaces implemented by the given class. This method does the same work as get­Interface(Class) except that it ignores all interfaces that are not assignable to base­Type. This filtering can avoid some ambiguities when the same class implements many interfaces.
      Type Parameters:
      T - the compile-time type.
      Parameters:
      type - the implementation class.
      base­Type - base type of the metadata of interest, or null if unspecified.
      Returns:
      the interface implemented by the given implementation class.
      Throws:
      Class­Cast­Exception - if type is not assignable to base­Type.
      No­Such­Element­Exception - if the given type does not implement a standard subtype of base­Type.
      Illegal­Argument­Exception - if the given type implements more than one standard subtype of base­Type.
      Since:
      1.7

    • getImplementation

      @OptionalCandidate public <T> Class<? extends T> getImplementation(Class<T> type)
      Returns the implementation class for the given interface, or null if none. If non-null, the returned class must have a public no-argument constructor and the metadata instance created by that constructor must be initially empty (no default value). That no-argument constructor should never throw any checked exception.

      The default implementation returns null in every cases. Subclasses shall override this method in order to map GeoAPI interfaces to their implementation.

      Type Parameters:
      T - the compile-time type.
      Parameters:
      type - the interface, typically from the org​.opengis​.metadata package.
      Returns:
      the implementation class, or null if none.

    • getTitle

      public Optional<Object> getTitle(Object metadata)
      Returns the value of the property that summarizes the given metadata object. The property is specified by the Title­Property annotation on the implementation class. This method first searches for Title­Property in the implementation class of the given metadata. If the implementation class is not annotated, then this method searches in the implementation class managed by this standard.

      If the property value is itself another metadata annotated with Title­Property, then the search for a title continues recursively in the other metadata. If a cyclic graph is detected, this method returns the last value before the cycle.

      Parameters:
      metadata - the metadata for which to get the title property, or null.
      Returns:
      the title property value of the given metadata, or empty if none.
      Since:
      1.7
      See Also:

    • asNameMap

      public Map<String,String> asNameMap(Class<?> type, KeyNamePolicy keyPolicy, KeyNamePolicy valuePolicy)
      Returns the names of all properties defined in the given metadata type. The property names appears both as keys and as values, but may be written differently. The names may be standard identifiers (e.g. as defined by ISO 19115), JavaBeans names, method names or sentences (usually in English).

      Example

      The following code prints "alternate­Titles" (note the plural): 
      MetadataStandard standard = MetadataStandard.ISO_19115;
Map<String, String> names = standard.asNameMap(Citation.class, UML_IDENTIFIER, JAVABEANS_PROPERTY);
String value = names.get("alternateTitle");
System.out.println(value);                   // alternateTitles
      The key­Policy argument specify only the string representation of keys returned by the iterators. No matter the key name policy, the key argument given to any Map method can be any of the above-cited forms of property names.
      Parameters:
      type - the interface or implementation class of a metadata.
      key­Policy - determines the string representation of map keys.
      value­Policy - determines the string representation of map values.
      Returns:
      the names of all properties defined by the given metadata type.
      Throws:
      Class­Cast­Exception - if the metadata class does not implement a metadata interface of this standard.
      Illegal­Argument­Exception - if the metadata class implements more than one metadata interface of this standard.

    • asTypeMap

      public Map<String,Class<?>> asTypeMap(Class<?> type, KeyNamePolicy keyPolicy, TypeValuePolicy valuePolicy)
      Returns the type of all properties, or their declaring type, defined in the given metadata type. The keys in the returned map are the same as the keys in the above name map. The values are determined by the value­Policy argument, which can be element type or the declaring interface among others.

      Example

      the following code prints the International­String class name: 
      MetadataStandard standard = MetadataStandard.ISO_19115;
Map<String, Class<?>> types = standard.asTypeMap(Citation.class, UML_IDENTIFIER, ELEMENT_TYPE);
Class<?> value = types.get("alternateTitle");
System.out.println(value);                       // class org.opengis.util.InternationalString
      Parameters:
      type - the interface or implementation class of a metadata.
      key­Policy - determines the string representation of map keys.
      value­Policy - whether the values shall be property types, the element types (same as property types except for collections) or the declaring interface or class.
      Returns:
      the types or declaring type of all properties defined in the given metadata type.
      Throws:
      Class­Cast­Exception - if the metadata class does not implement a metadata interface of this standard.
      Illegal­Argument­Exception - if the metadata class implements more than one metadata interface of this standard.

    • asInformationMap

      public Map<String, ExtendedElementInformation> asInformationMap(Class<?> type, KeyNamePolicy keyPolicy)
      Returns information about all properties defined in the given metadata type. The keys in the returned map are the same as the keys in the above name map. The values contain information inferred from the ISO names, the Obligation enumeration and the Value­Range annotations.

      In the particular case of Apache SIS implementation, all values in the information map additionally implement the following interfaces:

      Note: the rational for implementing Checked­Container is to consider each Extended­Element­Information instance as the set of all possible values for the property. If the information had a contains(E) method, it would return true if the given value is valid for that property.
      In addition, for each map entry the value returned by Extended­Element­Information​.get­Domain­Value() may optionally be an instance of any of the following classes:
      • Number­Range if the valid values are constrained to some specific range.
      Parameters:
      type - the metadata interface or implementation class.
      key­Policy - determines the string representation of map keys.
      Returns:
      information about all properties defined in the given metadata type.
      Throws:
      Class­Cast­Exception - if the metadata class does not implement a metadata interface of this standard.
      Illegal­Argument­Exception - if the metadata class implements more than one metadata interface of this standard.
      See Also:

    • asIndexMap

      public Map<String,Integer> asIndexMap(Class<?> type, KeyNamePolicy keyPolicy)
      Returns indices for all properties defined in the given metadata type. The keys in the returned map are the same as the keys in the above name map. The values are arbitrary indices numbered from 0 inclusive to n exclusive, where n is the number of properties declared in the given metadata type.

      Property indices may be used as an alternative to property names by some applications doing their own storage. Such index usages are fine for temporary storage during the Java Virtual Machine lifetime, but indices should not be used in permanent storage. The indices are stable as long as the metadata implementation does not change, but may change when the implementation is upgraded to a newer version.

      Parameters:
      type - the interface or implementation class of a metadata.
      key­Policy - determines the string representation of map keys.
      Returns:
      indices of all properties defined by the given metadata type.
      Throws:
      Class­Cast­Exception - if the metadata class does not implement a metadata interface of this standard.
      Illegal­Argument­Exception - if the metadata class implements more than one metadata interface of this standard.

    • asValueMap

      public Map<String,Object> asValueMap(Object metadata, Class<?> baseType, KeyNamePolicy keyPolicy, ValueExistencePolicy valuePolicy)
      Returns a view of the specified metadata object as a Map. The map is backed by the metadata object using Java reflection, so changes in the underlying metadata object are immediately reflected in the map and conversely.

      The map content is determined by the arguments: metadata determines the set of keys, key­Policy determines their String representations of those keys and value­Policy determines whether entries having a null value or an empty collection shall be included in the map.

      Supported operations

      The map supports the put(…) and remove(…) operations if the underlying metadata object contains setter methods. The remove(…) method is implemented by a call to put(…, null). Note that whether the entry appears as effectively removed from the map or just cleared (i.e. associated with a null value) depends on the value­Policy argument.

      Keys and values

      The keys are case-insensitive and can be either the JavaBeans property name, the getter method name or the UML identifier. The value given to a call to the put(…) method shall be an instance of the type expected by the corresponding setter method, or an instance of a type convertible to the expected type.

      Multi-values entries

      Calls to put(…) replace the previous value, with one noticeable exception: if the metadata property associated with the given key is a Collection but the given value is a single element (not a collection), then the given value is added to the existing collection. In other words, the returned map behaves as a multi-values map for the properties that allow multiple values. If the intent is to unconditionally discard all previous values, then make sure that the given value is a collection when the associated metadata property expects such collection.

      Disambiguating instances that implement more than one metadata interface

      It is some time convenient to implement more than one interface by the same class. For example, an implementation interested only in extents defined by geographic bounding boxes could implement Extent and Geographic­Bounding­Box by the same class. In such case, it is necessary to tell to this method which one of those two interfaces shall be reflected in the returned map. This information can be provided by the base­Type argument. That argument needs to be non-null only in situations where an ambiguity can arise; base­Type can be null if the given metadata implements only one interface recognized by this Metadata­Standard instance.
      Parameters:
      metadata - the metadata object to view as a map.
      base­Type - base type of the metadata of interest, or null if unspecified.
      key­Policy - determines the string representation of map keys.
      value­Policy - whether the entries having null value or empty collection shall be included in the map.
      Returns:
      a map view over the metadata object.
      Throws:
      Class­Cast­Exception - if the metadata object does not implement a metadata interface of this standard.
      Illegal­Argument­Exception - if the metadata object implements more than one metadata interface of this standard.
      Since:
      0.8
      See Also:

    • asNilReasonMap

      public Map<String, NilReason> asNilReasonMap(Object metadata, Class<?> baseType, KeyNamePolicy keyPolicy)
      Returns the reasons for all missing values of mandatory properties. The map is backed by the metadata object using Java reflection, so changes in the underlying metadata object are immediately reflected in the map and conversely. Nil reasons are determined by calls to Nil­Reason​.for­Object(Object), potentially completed by an internal storage for
      invalid reference 
      unsupported value types
      .

      Mandatory and optional properties

      If a mandatory property has no value, then the property will have an entry in the map even if the associated Nil­Reason is null. By contrast, optional properties have entries in the map only if they have a non-null Nil­Reason.

      Supported operations

      The map supports the put(…) and remove(…) operations if the underlying metadata object contains setter methods. The remove(…) method is implemented by a call to put(…, null).
      Parameters:
      metadata - the metadata object to view as a map.
      base­Type - base type of the metadata of interest, or null if unspecified.
      key­Policy - determines the string representation of map keys.
      Returns:
      a map view over the metadata object.
      Throws:
      Class­Cast­Exception - if the metadata object does not implement a metadata interface of this standard.
      Illegal­Argument­Exception - if the metadata object implements more than one metadata interface of this standard.
      Since:
      1.5
      See Also:

    • asTreeTable

      public TreeTable asTreeTable(Object metadata, Class<?> baseType, ValueExistencePolicy valuePolicy)
      Returns the specified metadata object as a tree table. The tree table is backed by the metadata object using Java reflection, so changes in the underlying metadata object are immediately reflected in the tree table and conversely.

      The returned Tree­Table instance contains the columns listed below. The (IDENTIFIER, INDEX) pair of columns can be used as a primary key for uniquely identifying a node in a list of children. That uniqueness is guaranteed only for the children of a given node. The same keys may appear in the children of any other nodes.

      • Table­Column​.IDENTIFIER
        The UML identifier if any, or the Java Beans property name otherwise, of a metadata property. For example in a tree table view of Default­Citation, there is a node having the "title" identifier.
      • Table­Column​.INDEX
        If the metadata property is a collection, then the zero-based index of the element in that collection. Otherwise null. For example, in a tree table view of Default­Citation, if the "alternate­Title" collection contains two elements, then there is a node with index 0 for the first element and another node with index 1 for the second element.
      • Table­Column​.NAME
        A human-readable name for the node, derived from the identifier and the index. This is the column shown in the default to­String() implementation and may be localizable.
      • Table­Column​.TYPE
        The base type of the value (usually an interface).
      • Table­Column​.OBLIGATION
        Whether the property is mandatory, optional or conditional.
      • Table­Column​.VALUE
        The metadata value for the node. Values in this column are writable if the underlying metadata class have a setter method for the property represented by the node.
      • NIL_REASON
        If the property is mandatory and nevertheless absent, the reason why. This column is included only if value­Policy accepts nil values. Values are instances of Nil­Reason.
      • Table­Column​.REMARKS
        Remarks or warning on the property value. This is rarely present. It is provided when the value may look surprising, for example the longitude values in a geographic bounding box crossing the anti-meridian.

      Write operations

      Only the VALUE column may be writable, with one exception: newly created children need to have their IDENTIFIER set before any other operation. For example, the following code adds a title to a citation: 
      TreeTable.Node node = ...;                               // The node for a DefaultCitation.
TreeTable.Node child = node.newChild();
child.setValue(TableColumn.IDENTIFIER, "title");
child.setValue(TableColumn.VALUE, "Le petit prince");
// Nothing else to do - the child node has been added.
      Nodes can be removed by invoking the Iterator​.remove() method on the children iterator. Note that whether the child appears as effectively removed from the node or just cleared (i.e. associated with a null value) depends on the value­Policy argument.

      Disambiguating instances that implement more than one metadata interface

      If the given metadata instance implements more than one interface recognized by this Metadata­Standard, then the base­Type argument need to be non-null in order to specify which interface to reflect in the tree.
      Parameters:
      metadata - the metadata object to view as a tree table.
      base­Type - base type of the metadata of interest, or null if unspecified.
      value­Policy - whether the property having null value or empty collection shall be included in the tree.
      Returns:
      a tree table representation of the specified metadata.
      Throws:
      Class­Cast­Exception - if the metadata object does not implement a metadata interface of this standard.
      Illegal­Argument­Exception - if the metadata object implements more than one metadata interface of this standard.
      Since:
      0.8
      See Also:

    • equals

      @Deprecated(since="1.7", forRemoval=true) public boolean equals(Object metadata1, Object metadata2, ComparisonMode mode)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Replaced by equals(Object, Object, Class, Comparison­Mode) because this method is ambiguous when one of the given metadata instances implements more than one metadata interface.
      Compares the two specified metadata objects for equality. The two metadata arguments shall be implementations of a metadata interface defined by this Metadata­Standard, otherwise an exception will be thrown. However, the two arguments do not need to be instances of the same implementation class except for Comparison­Mode​.STRICT.
      Parameters:
      metadata1 - the first metadata object to compare, or null.
      metadata2 - the second metadata object to compare, or null.
      mode - the strictness level of the comparison.
      Returns:
      true if the given metadata objects are equal or if the two arguments are null.

    • equals

      public Boolean equals(Object metadata1, Object metadata2, Class<?> baseType, ComparisonMode criteria)
      Compares the two specified metadata instances for equality. The two metadata arguments should be implementations of a metadata interface defined by this Metadata­Standard. However, they do not need to be of the exact same class unless criteria is Comparison­Mode​.STRICT. If the equality cannot be determined in a non-ambiguous way, for example because the given metadata instances do not implement exactly one interface assignable to base­Type, then this method returns null.

      Resolution of type ambiguity

      Because some metadata standards define hundreds of interfaces, some metadata classes may implement many interfaces at once for convenience. For avoiding ambiguity, the interface of interest, or a non-ambiguous super-type of the interface of interest, should be specified in the base­Type argument. This information can be obtained, for example, from the return type of the method that provided the metadata. Only properties inherited from interfaces that are assignable to base­Type will be compared. If base­Type is null, then this method tries to find the base type automatically. The latter is not always equivalent to specifying Object​.class as the base type.
      Parameters:
      metadata1 - the first metadata object to compare, or null.
      metadata2 - the second metadata object to compare, or null.
      base­Type - base type of the metadata of interest, or null if unspecified.
      criteria - the strictness level of the comparison.
      Returns:
      whether the given metadata objects are equal, or null if undetermined.
      Throws:
      Class­Cast­Exception - if metadata1 is non-null and not an instance of base­Type.
      Since:
      1.7
      See Also:

    • hashCode

      public int hashCode(Object metadata)
      Computes a hash code for the specified metadata. The hash code is defined as the sum of hash code values of all non-empty properties, plus the hash code of the interface. This is a similar contract than Set​.hash­Code() (except for the interface) and ensures that the hash code value is insensitive to the ordering of properties.
      Parameters:
      metadata - the metadata object to compute hash code.
      Returns:
      a hash code value for the specified metadata, or 0 if the given metadata is null.
      Throws:
      Class­Cast­Exception - if the metadata object does not implement a metadata interface of this standard.
      Illegal­Argument­Exception - if the metadata object implements more than one metadata interface of this standard.
      See Also:

    • toString

      public String toString()
      Returns a string representation of this metadata standard. This is for debugging purpose only and may change in any future version.
      Overrides:
      to­String in class Object
      Returns:
      a string representation for debugging purposes.