ForewordMany metadata standards exist, including Dublin core, ISO 19115 and the Image I/O metadata defined in
javax.imageio.metadata. The SIS implementation focuses on ISO 19115 (including its ISO 19115-2 extension), but the classes are designed in a way that allow the usage of different standards. This genericity goal should be keep in mind in the discussion below.
How Metadata are definedA metadata standard is defined by a set of Java interfaces belonging to a specific package and its sub-packages. For example, the ISO 19115 standard is defined by the GeoAPI interfaces defined in the
org.opengis.metadatapackage and sub-packages. That standard is identified in SIS by the
MetadataStandard.ISO_19115constant. Other standards are defined as well, for example the
MetadataStandard.ISO_19123constant stands for the standards defined by the interfaces in the
org.opengis.coveragepackage and sub-packages.
For each interface, the collection of declared getter methods defines its properties
(or attributes). If a
UML annotation is attached to the getter method,
the identifier declared in that annotation is taken as the property name. This is typically the name defined by the
International Standard from which the interface is derived. Otherwise (if there is no
the property name is inferred from the method name like what the Java Beans framework does.
The implementation classes, if they exist, are defined in different packages than the interfaces.
For example, the ISO 19115 interfaces, declared in
org.opengis.metadata, are implemented by
org.apache.sis.metadata.iso. The sub-packages hierarchy is the same, and the names
of implementation classes are the name of the implemented interfaces prefixed with
Abstractprefix means that the class is abstract in the sense of the implemented standard. It it not necessarily abstract in the sense of Java. Because incomplete metadata are common in practice, sometimes we wish to instantiate an "abstract" class despite the lack of knowledge about the exact sub-type.
- The properties are determined by the getter methods declared in the interfaces. Getter methods declared in the implementation classes are ignored.
- Setter methods, if any, can be declared in the implementation classes without the need for declarations in the interfaces. In other words, interfaces are assumed read-only unless a specific implementation provide setter methods.
- The implementation is not required to exist as source code. They can be generated on the fly with
Proxy. This is the approach taken by the
org.apache.sis.metadata.sqlpackage for generating metadata implementations backed by the content of a database.
How Metadata are handledMetadata objects in SIS are mostly containers: they provide getter and setter methods for manipulating the values associated to properties (for example the
titleproperty of a
Citationobject), but provide few logic. The package
org.apache.sis.metadata.isoand its sub-packages are the main examples of such containers.
In addition, the metadata modules provide support methods for handling the metadata objects through Java Reflection. This is an approach similar to Java Beans, in that users are encouraged to use directly the API of Plain Old Java objects (actually interfaces) every time their type is known at compile time, and fallback on the reflection technic when the type is known only at runtime.
Using Java reflection, a metadata can be viewed in many different ways:
- As a
MetadataStandardclass provides various methods returning a view of an arbitrary metadata implementation as a
Map, where the key are the property names and the values are the return values, types or descriptions of getter methods. The map is writable if the underlying metadata implementation has setter methods, otherwise attempts to set a value throw an
- As a
The metadata are organized as a tree. For example, the
Citationmetadata contains one or many
ResponsiblePartyelements, each of them containing a
Contactelement, which contains a
Telephoneelement, etc. For each node, there is many information that can be displayed in columns:
- A description of the element.
- The type of values (
- The range of valid values (if the type is numeric), or an enumeration of valid values (if the type is a code list).
- The value stored in the element, or the default value.
- As a table record in a database (using
It is possible to establish the following mapping between metadata and a SQL database:
- Each metadata interface maps to a table of the same name in the database.
- Each property in the above interface maps to a column of the same name in the above table.
- Each instance of the above interface is a record in the above table.
How Metadata are marshalledThe ISO 19115-3 standard defines how ISO 19115-1 metadata shall be represented in XML. The SIS library supports XML marshalling and unmarshalling with JAXB annotations.
Only the implementation classes defined in the
org.apache.sis.metadata.iso packages and sub-packages
are annotated for JAXB marshalling. If a metadata is implemented by another package (for example
org.apache.sis.metadata.sql), then it shall be converted to an annotated class before to be marshalled.
All SIS annotated classes provide a copy constructor for this purpose. A shallow copy is sufficient;
JAXB adapters will convert the elements on-the-fly when needed.
The annotated classes can be given to a JAXB
Marshaller. For best results, it shall be a marshaller
obtained from the
MarshallerPool, otherwise some XML outputs may be incomplete
(missing namespaces for instance). The
XML class provides convenience methods
for this purpose.
ClassDescriptionProvides basic operations using Java reflection for metadata implementations.Thrown when a metadata is in a invalid state or has illegal property values.The name of the keys included in a
Mapof metadata.Performs deep copies of given metadata instances.Enumeration of some metadata standards.Base class of metadata having an editable content.Whether the metadata is still editable or has been made final.Identifies the name of a property to use for summarizing in one line the content of a metadata object.The kind of values in the
MetadataStandard.asTypeMap(…).Thrown on attempt to set a read-only value in a metadata object.