org.geotoolkit.metadata
Class MetadataStandard

Object
  MetadataStandard

@ThreadSafe
public final class MetadataStandard
extends Object

Enumeration of some metadata standards. A standard is defined by a set of Java interfaces in a specific package or subpackages. For example the ISO 19115 standard is defined by GeoAPI interfaces in the org.opengis.metadata package and subpackages.

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

• Properties (or metadata attributes) are defined by the collection of get*() method with arbitrary return type, or is*() method with boolean return type, found in the interface. Getters declared only in the implementation are ignored.

• Every properties are readable.

• A property is writable if a set*(...) method is defined in the implementation class for the corresponding get*() method. The setter doesn't need to be defined in the interface.

An instance of MetadataStandard is associated to every AbstractMetadata objects. The AbstractMetadata base class usually form the basis of ISO 19115 implementations but can also be used for other standards. An instance of MetadataStandard is also associated with Image I/O SpatialMetadataFormat in order to define the tree of XML nodes to be associated with raster data.

Since:

2.4

Version:

3.20

Author:

Martin Desruisseaux (Geomatys)

Module:

metadata/geotk-metadata (download)

View source code for this class

Field Summary

static MetadataStandard	ISO_19111 An instance working on ISO 19111 standard as defined by GeoAPI interfaces in the org.opengis.referencing package and subpackages.
static MetadataStandard	ISO_19115 An instance working on ISO 19115 standard as defined by GeoAPI interfaces in the org.opengis.metadata package and subpackages.
static MetadataStandard	ISO_19119 An instance working on ISO 19119 standard as defined by GeoAPI interfaces in the org.opengis.service package and subpackages.
static MetadataStandard	ISO_19123 An instance working on ISO 19123 standard as defined by GeoAPI interfaces in the org.opengis.coverage package and subpackages.

Constructor Summary

MetadataStandard(String interfacePackage)
Creates a new instance working on implementation of interfaces defined in the specified package.

Method Summary

Map<String,String>	asDescriptionMap(Class<?> type, Locale locale, KeyNamePolicy keyNames) Returns a view as a map of the property descriptions for the specified metadata type.
Map<String,Object>	asMap(Object metadata) Returns a view as a map of the specified metadata object.
Map<String,Object>	asMap(Object metadata, NullValuePolicy content, KeyNamePolicy keyNames) Returns a view of the specified metadata object as a map.
Map<String,String>	asNameMap(Class<?> type, KeyNamePolicy valueNames, KeyNamePolicy keyNames) Returns a view as a map of the property names for the specified metadata type.
Map<String,ValueRestriction>	asRestrictionMap(Object metadata, NullValuePolicy content, KeyNamePolicy keyNames) Returns a view as a map of the restrictions for the specified metadata.
TreeModel	asTree(Object metadata) Returns a view of the specified metadata as a tree.
TreeTableNode	asTreeTable(Object metadata) Returns a view of the specified metadata as a tree table.
Map<String,Class<?>>	asTypeMap(Class<?> type, TypeValuePolicy typeValues, KeyNamePolicy keyNames) Returns a view as a map of the property types for the specified metadata type.
static MetadataStandard	forClass(Class<?> type) Returns the metadata standard for the given class.
Class<?>	getInterface(Class<?> type) Returns the metadata interface implemented by the specified implementation class.
int	hashCode(Object metadata) Computes a hash code for the specified metadata.
boolean	isMetadata(Class<?> type) Returns true if the given type is assignable to a type from this standard.
void	shallowCopy(Object source, Object target, boolean skipNulls) Copies all metadata from source to target.
boolean	shallowEquals(Object metadata1, Object metadata2, ComparisonMode mode, boolean skipNulls) Compares the two specified metadata objects.
String	toString() Returns a string representation of this metadata standard.
String	toString(Object metadata) Returns a string representation of the specified metadata.

Methods inherited from class Object

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

Field Detail

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 subpackages.

Since:

2.5

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 subpackages.

ISO_19119

public static final MetadataStandard ISO_19119

An instance working on ISO 19119 standard as defined by GeoAPI interfaces in the org.opengis.service package and subpackages.

Since:

2.5

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 subpackages.

Since:

3.06

Constructor Detail

MetadataStandard

public MetadataStandard(String interfacePackage)

Creates a new instance working on implementation of interfaces defined in the specified package. For the ISO 19115 standard reflected by GeoAPI interfaces, it should be the org.opengis.metadata package.

Parameters:

interfacePackage - The root package for metadata interfaces.

Method Detail

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 Geotk 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.

Since:

3.20

isMetadata

public boolean isMetadata(Class<?> type)

Returns true if the given type is assignable to a type from this standard. If this method returns true, then invoking getInterface(Class) is guaranteed to succeed without throwing an exception.

Parameters:

type - The implementation class (can be null).

Returns:

true if the given class is an interface of this standard, or implements an interface of this standard.

Since:

3.03

getInterface

public Class<?> getInterface(Class<?> type)
                      throws ClassCastException

Returns the metadata interface implemented by the specified implementation class. If the given type is already an interface from this standard, then it is returned unchanged.

Note: The word "interface" may be taken in a looser sense than the usual Java sense because if the given type is defined in this standard package, then it is returned unchanged. The standard package is usually made of interfaces and code lists only, but this is not verified by this method.

Parameters:

type - The implementation class.

Returns:

The interface implemented by the given implementation class.

Throws:

ClassCastException - if the specified implementation class does not implement an interface of this standard.

See Also:

AbstractMetadata.getInterface()

asTypeMap

public Map<String,Class<?>> asTypeMap(Class<?> type,
                                      TypeValuePolicy typeValues,
                                      KeyNamePolicy keyNames)
                               throws ClassCastException

Returns a view as a map of the property types for the specified metadata type. The keys are the property names as determined by the list of getFoo() methods declared in the metadata interface, or the UML identifier associated to those methods. The values are determined by the TypeValuePolicy argument.

Example: The following code returns InternationalString.class.

ISO_19115.asTypeMap(Citation.class, ELEMENT_TYPE, UML_IDENTIFIER).get("alternateTitle");

Parameters:

type - The interface or implementation class.

typeValues - Whatever the values should be property types, the element types (same as property types except for collections) or the declaring class.

keyNames - Determines the string representation of map keys.

Returns:

The types for the the properties of the given class.

Throws:

ClassCastException - if the specified interface or implementation class does not extend or implement a metadata interface of the expected package.

Since:

3.03

asNameMap

public Map<String,String> asNameMap(Class<?> type,
                                    KeyNamePolicy valueNames,
                                    KeyNamePolicy keyNames)
                             throws ClassCastException

Returns a view as a map of the property names for the specified metadata type. The keys are the property names as determined by the list of getFoo() methods declared in the metadata interface, or the UML identifier associated to those methods. The values are determined by the KeyNamePolicy argument.

Example: The following code returns "alternateTitles" (note the plural).

ISO_19115.asNameMap(Citation.class, JAVABEANS_PROPERTY, UML_IDENTIFIER).get("alternateTitle");

Note: The KeyNamePolicy type may seem a bit strange for the valueNames parameter, but this method is used for mapping a namespace to an other namespace. In each namespace, the names are unique.

Parameters:

type - The interface or implementation class.

valueNames - Determines the string representation of map values.

keyNames - Determines the string representation of map keys.

Returns:

The names for the properties of the given class.

Throws:

ClassCastException - if the specified interface or implementation class does not extend or implement a metadata interface of the expected package.

Since:

3.04

asDescriptionMap

public Map<String,String> asDescriptionMap(Class<?> type,
                                           Locale locale,
                                           KeyNamePolicy keyNames)
                                    throws ClassCastException

Returns a view as a map of the property descriptions for the specified metadata type. The keys are the same than asNameMap, except that only the keys for which a description is available are declared in the map. The values are descriptions localized in the given locale if possible, or in the default locale otherwise.

Example: The following code returns "Short name or other language name by which the cited information is known."

ISO_19115.asDescriptionMap(Citation.class, Locale.ENGLISH, UML_IDENTIFIER).get("alternateTitle");

As a special case, the "class" value can be used for fetching the description of the class rather than a specific method of that class.

Note: We could have provided a method without Locale argument and returning a map with InternationalString values. However the method defined below is slightly more efficient if the descriptions are going to be asked for more than one property, because it fetches the ResourceBundle only once.

Parameters:

type - The interface or implementation class.

locale - Determines the locale of map values.

keyNames - Determines the string representation of map keys.

Returns:

The descriptions for the properties of the given class, or an empty map if there is no description for the given class in this metadata standard.

Throws:

ClassCastException - if the specified interface or implementation class does not extend or implement a metadata interface of the expected package.

Since:

3.05

asRestrictionMap

public Map<String,ValueRestriction> asRestrictionMap(Object metadata,
                                                     NullValuePolicy content,
                                                     KeyNamePolicy keyNames)
                                              throws ClassCastException

Returns a view as a map of the restrictions for the specified metadata. The restrictions are inferred from the Obligation and ValueRange annotated on the getter methods.

The metadata argument can be either a Class, or an instance of a metadata object:

• If the metadata argument is a Class, then this method returns all restrictions that applied on metadata of the given type.
• Otherwise if metadata is an instance of a metadata object, then this method returns non-null values only for restrictions that are violated by the given instance. In this case, the returned map is live: changes to any metadata value will be immediately reflected in the restriction map.

Parameters:

metadata - The metadata instance for which to get the map of violated restrictions, or the Class of a metadata object for listing all restrictions.

content - Whatever the entries having no restriction or no violation (null value) should be included in the map.

keyNames - Determines the string representation of map keys.

Returns:

The restrictions that are violated by the given metadata instance, or all restrictions if metadata is a Class.

Throws:

ClassCastException - if the metadata object doesn't implement a metadata interface of the expected package.

Since:

3.04

asMap

public Map<String,Object> asMap(Object metadata,
                                NullValuePolicy content,
                                KeyNamePolicy keyNames)
                         throws ClassCastException

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.

The content of the key set is determined by the arguments: metadata determines the set of keys, content determines whatever the keys for entries having a null value or an empty collection should be included, and keyNames determines their String representations.

The map supports the put operations if the underlying metadata object contains setFoo(...) methods. The keys are case-insensitive and can be either the javabeans property name, or the UML identifier.

Parameters:

metadata - The metadata object to view as a map.

content - Whatever the entries having null value or empty collection should be included in the map. The default is NON_EMPTY.

keyNames - Determines the string representation of map keys. The default is JAVABEANS_PROPERTY.

Returns:

A map view over the metadata object.

Throws:

ClassCastException - if the metadata object doesn't implement a metadata interface of the expected package.

Since:

3.03

asMap

public Map<String,Object> asMap(Object metadata)
                         throws ClassCastException

Returns a view as a map of the specified metadata object. The map is backed by the metadata object using Java reflection, so changes in the underlying metadata object are immediately reflected in the map. The keys are the property names as determined by the list of getFoo() methods declared in the metadata interface, and only the entries with a non-null or non-empty value are listed.

The map supports the put operations if the underlying metadata object contains setFoo(...) methods. The keys are case-insensitive and can be either the javabeans property name, or the UML identifier.

Parameters:

metadata - The metadata object to view as a map.

Returns:

A map view over the metadata object.

Throws:

ClassCastException - if the metadata object doesn't implement a metadata interface of the expected package.

See Also:

AbstractMetadata.asMap()

asTreeTable

public TreeTableNode asTreeTable(Object metadata)
                          throws ClassCastException

Returns a view of the specified metadata as a tree table. Note that while TreeTableNode is defined in a org.geotoolkit.gui.swing sub-package, it can be seen as a data structure independent of Swing. It will not force class loading of Swing framework.

In current implementation, the tree is not live (i.e. changes in metadata are not reflected in the tree). However it may be improved in a future Geotk implementation.

Parameters:

metadata - The metadata object to formats as a tree table.

Returns:

A tree table representation of the specified metadata.

Throws:

ClassCastException - if the metadata object doesn't implement a metadata interface of the expected package.

Since:

3.19

See Also:

AbstractMetadata.asTreeTable()

asTree

public TreeModel asTree(Object metadata)
                 throws ClassCastException

Returns a view of the specified metadata as a tree. Note that while TreeModel is defined in the javax.swing.tree package, it can be seen as a data structure independent of Swing. It will not force class loading of Swing framework.

In current implementation, the tree is not live (i.e. changes in metadata are not reflected in the tree). However it may be improved in a future Geotk implementation.

Parameters:

metadata - The metadata object to formats as a tree.

Returns:

A tree representation of the specified metadata.

Throws:

ClassCastException - if the metadata object doesn't implement a metadata interface of the expected package.

See Also:

AbstractMetadata.asTree()

shallowCopy

public void shallowCopy(Object source,
                        Object target,
                        boolean skipNulls)
                 throws ClassCastException,
                        UnmodifiableMetadataException

Copies all metadata from source to target. The source must implements the same metadata interface than the target.

Parameters:

source - The metadata to copy.

target - The target metadata.

skipNulls - If true, only non-null values will be copied.

Throws:

ClassCastException - if the source or target object don't implements a metadata interface of the expected package.

UnmodifiableMetadataException - if the target metadata is unmodifiable, or if at least one setter method was required but not found.

See Also:

ModifiableMetadata.clone()

shallowEquals

public boolean shallowEquals(Object metadata1,
                             Object metadata2,
                             ComparisonMode mode,
                             boolean skipNulls)
                      throws ClassCastException

Compares the two specified metadata objects. The comparison is shallow, i.e. all metadata attributes are compared using the LenientComparable.equals(Object, ComparisonMode) method if possible, or the Object.equals(Object) method otherwise, without explicit recursive call to this shallowEquals(...) method for child metadata.

This method can optionally excludes null values from the comparison. In metadata, null value often means "don't know", so in some occasion we want to consider two metadata as different only if a property value is know for sure to be different.

The first arguments must be an implementation of a metadata interface, otherwise an exception will be thrown. The two arguments do not need to be the same implementation however.

Parameters:

metadata1 - The first metadata object to compare.

metadata2 - The second metadata object to compare.

mode - The strictness level of the comparison.

skipNulls - If true, only non-null values will be compared.

Returns:

true if the given metadata objects are equals.

Throws:

ClassCastException - if at least one metadata object don't implements a metadata interface of the expected package.

See Also:

AbstractMetadata.equals(Object, ComparisonMode)

hashCode

public int hashCode(Object metadata)
             throws ClassCastException

Computes a hash code for the specified metadata. The hash code is defined as the sum of hash code values of all non-null properties. This is the same contract than Set.hashCode() and ensure 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.

Throws:

ClassCastException - if the metadata object doesn't implement a metadata interface of the expected package.

See Also:

AbstractMetadata.hashCode()

toString

public String toString(Object metadata)
                throws ClassCastException

Returns a string representation of the specified metadata.

Parameters:

metadata - The metadata object to formats as a string.

Returns:

A string representation of the specified metadata.

Throws:

ClassCastException - if the metadata object doesn't implement a metadata interface of the expected package.

See Also:

AbstractMetadata.toString()

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:

toString in class Object