sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1398720 - in /sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml: IdentifiedObject.java IdentifierMap.java
Date Tue, 16 Oct 2012 10:29:14 GMT
Author: desruisseaux
Date: Tue Oct 16 10:29:14 2012
New Revision: 1398720

URL: http://svn.apache.org/viewvc?rev=1398720&view=rev
Log:
Added IdentifiedObject interface and its dependency.

Added:
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifiedObject.java 
 (with props)
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifierMap.java   (with
props)

Added: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifiedObject.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifiedObject.java?rev=1398720&view=auto
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifiedObject.java (added)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifiedObject.java Tue
Oct 16 10:29:14 2012
@@ -0,0 +1,131 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.xml;
+
+import java.util.Collection;
+import org.opengis.metadata.Identifier;
+import org.opengis.metadata.citation.Citation;
+
+
+/**
+ * The interface for all SIS objects having identifiers. Identifiers are {@link String} in
+ * a namespace identified by a {@link Citation}. The namespace can be some organization like
+ * <a href="http://www.epsg.org">EPSG</a> for Coordinate Reference System objects,
or a
+ * well-known acronym like ISBN for <cite>International Standard Book Number</cite>.
+ * <p>
+ * When an identified object is marshalled in a ISO 19139 compliant XML document, some identifiers
+ * are handled in a special way: they appear as {@code gml:id}, {@code gco:uuid} or {@code
xlink:href}
+ * attributes of the XML element. Those identifiers can be specified using the {@link IdentifierSpace}
+ * enum values as below:
+ *
+ * {@preformat java
+ *     IdentifiedObject object = ...;
+ *     object.getIdentifierMap().put(IdentifierSpace.ID, "myID");
+ * }
+ *
+ * {@section Relationship with GeoAPI}
+ * Identifiers exist also in some (not all) GeoAPI objects. Some GeoAPI objects
+ * ({@link org.opengis.metadata.acquisition.Instrument}, {@link org.opengis.metadata.acquisition.Platform},
+ * {@link org.opengis.metadata.acquisition.Operation}, {@link org.opengis.metadata.lineage.Processing},
+ * <i>etc.</i>) have an explicit single identifier attribute, while other GeoAPI
objects
+ * ({@link org.opengis.metadata.citation.Citation}, {@link org.opengis.metadata.acquisition.Objective},
+ * referencing {@link org.opengis.referencing.IdentifiedObject}, <i>etc.</i>)
allow an arbitrary
+ * number of identifiers. However GeoAPI does not define explicit methods for handling the
{@code id},
+ * {@code uuid} or {@code href} attributes, since they are specific to XML marshalling (they
do not
+ * appear in OGC/ISO abstract specifications). This {@code IdentifiedObject} interface provides
a
+ * way to handle those identifiers.
+ * <p>
+ * Note that GeoAPI defines a similar interface, also named {@link org.opengis.referencing.IdentifiedObject}.
+ * However that GeoAPI interface is not of general use, since it contains methods like
+ * {@link org.opengis.referencing.IdentifiedObject#toWKT() toWKT()} that are specific to
referencing
+ * or geometric objects. In addition, the GeoAPI interface defines some attributes
+ * ({@linkplain org.opengis.referencing.IdentifiedObject#getName() name},
+ * {@linkplain org.opengis.referencing.IdentifiedObject#getAlias() alias},
+ * {@linkplain org.opengis.referencing.IdentifiedObject#getRemarks() remarks}) that are not
needed
+ * for the purpose of handling XML {@code id}, {@code uuid} or {@code href} attributes.
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @since   0.3 (derived from geotk-3.18)
+ * @version 0.3
+ * @module
+ *
+ * @see IdentifierSpace
+ * @see org.geotoolkit.metadata.iso.MetadataEntity
+ * @see ObjectLinker#newIdentifiedObject(Class, Identifier[])
+ */
+public interface IdentifiedObject {
+    /**
+     * Returns all identifiers associated to this object. Each {@linkplain Identifier#getCode()
+     * identifier code} shall be unique in the {@linkplain Identifier#getAuthority() identifier
+     * authority} name space. Examples of namespace are:
+     * <p>
+     * <ul>
+     *   <li>{@linkplain org.geotoolkit.metadata.iso.citation.Citations#EPSG EPSG}
codes</li>
+     *   <li><cite>Universal Product Code</cite> (UPC)</li>
+     *   <li><cite>National Stock Number</cite> (NSN)</li>
+     *   <li><cite>International Standard Book Number</cite>
+     *       ({@linkplain org.geotoolkit.metadata.iso.citation.Citations#ISBN ISBN})</li>
+     *   <li><cite>International Standard Serial Number</cite>
+     *       ({@linkplain org.geotoolkit.metadata.iso.citation.Citations#ISSN ISSN})</li>
+     *   <li><cite>Universally Unique Identifier</cite> ({@linkplain java.util.UUID})</li>
+     *   <li>XML {@linkplain IdentifierSpace#ID ID} attribute</li>
+     *   <li>{@linkplain XLink} ({@code href}, {@code role}, {@code arcrole}, {@code
title},
+     *       {@code show} and {@code actuate} attributes)</li>
+     * </ul>
+     *
+     * <p>Note that XML ID attribute are actually unique only in the scope of the XML
document
+     * being processed.</p>
+     *
+     * @return All identifiers associated to this object, or an empty collection if none.
+     *
+     * @see org.geotoolkit.metadata.iso.citation.DefaultCitation#getIdentifiers()
+     * @see org.geotoolkit.metadata.iso.acquisition.DefaultObjective#getIdentifiers()
+     * @see org.geotoolkit.referencing.AbstractIdentifiedObject#getIdentifiers()
+     */
+    Collection<? extends Identifier> getIdentifiers();
+
+    /**
+     * A map view of {@linkplain #getIdentifiers() identifiers}.
+     * Each {@linkplain java.util.Map.Entry map entry} is associated
+     * to an element from the above identifier collection in which the
+     * {@linkplain java.util.Map.Entry#getKey() key} is the
+     * {@linkplain Identifier#getAuthority() identifier authority} and the
+     * {@linkplain java.util.Map.Entry#getValue() value} is the
+     * {@linkplain Identifier#getCode() identifier code}.
+     *
+     * <p>There is usually a one-to-one relationship between the map entries and the
identifier
+     * elements, but not always:</p>
+     * <ul>
+     *   <li><p>The map view may contain less entries, because the map interface
allows only one
+     *   entry per authority. If the {@linkplain #getIdentifiers() identifier collection}
contains
+     *   many identifiers for the same authority, then only the first occurrence is visible
through
+     *   this {@code Map} view.</p></li>
+     *
+     *   <li><p>The map view may also contain more entries than the {@linkplain
#getIdentifiers()
+     *   identifier collection}. For example the {@link org.opengis.metadata.citation.Citation}
+     *   interface defines separated attributes for ISBN, ISSN and other identifiers. This
map
+     *   view may choose to unify all those attributes in a single view.</p></li>
+     * </ul>
+     *
+     * <p>The map supports {@link IdentifierMap#put(Object, Object) put} operations
+     * if and only if this {@code IdentifiedObject} is modifiable.</p>
+     *
+     * @return The identifiers as a map of (<var>authority</var>, <var>code</var>)
entries,
+     *         or an empty map if none.
+     */
+    IdentifierMap getIdentifierMap();
+}

Propchange: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifiedObject.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifiedObject.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifierMap.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifierMap.java?rev=1398720&view=auto
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifierMap.java (added)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifierMap.java Tue
Oct 16 10:29:14 2012
@@ -0,0 +1,70 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.xml;
+
+import java.util.Map;
+import org.opengis.metadata.Identifier;
+import org.opengis.metadata.citation.Citation;
+
+
+/**
+ * A map view of some or all identifiers in an {@linkplain IdentifiedObject identified object}.
+ * Each {@linkplain java.util.Map.Entry map entry} is associated to an {@link Identifier}
where
+ * {@linkplain java.util.Map.Entry#getKey() key} is the {@linkplain Identifier#getAuthority()
+ * identifier authority} and the {@linkplain java.util.Map.Entry#getValue() value} is the
+ * {@linkplain Identifier#getCode() identifier code}.
+ * <p>
+ * Some XML identifiers are difficult to handle as {@link Identifier} objects. Those identifiers
are
+ * rather handled using specialized classes like {@link XLink}. This {@code IdentifierMap}
interface
+ * mirrors the standard {@link Map#get(Object) get} and {@link Map#put(Object, Object) put}
methods
+ * with specialized methods, in order to fetch and store identifiers as objects of the specialized
+ * class.
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @since   0.3 (derived from geotk-3.19)
+ * @version 0.3
+ * @module
+ *
+ * @see IdentifiedObject#getIdentifierMap()
+ */
+public interface IdentifierMap extends Map<Citation,String> {
+    /**
+     * Returns the identifier associated to the given namespace,
+     * or {@code null} if this map contains no mapping of the
+     * specialized type for the namespace.
+     *
+     * @param  <T> The identifier type.
+     * @param  authority The namespace whose associated identifier is to be returned.
+     * @return The identifier to which the given namespace is mapped, or
+     *         {@code null} if this map contains no mapping for the namespace.
+     */
+    <T> T getSpecialized(IdentifierSpace<T> authority);
+
+    /**
+     * Associates the given identifier with the given namespace in this map
+     * (optional operation). If the map previously contained a mapping for
+     * the namespace, then the old value is replaced by the specified value.
+     *
+     * @param  <T> The identifier type.
+     * @param  authority The namespace with which the given identifier is to be associated.
+     * @param  value The identifier to be associated with the given namespace.
+     * @return The previous identifier associated with {@code authority}, or {@code null}
+     *         if there was no mapping of the specialized type for {@code authority}.
+     * @throws UnsupportedOperationException If the identifier map is unmodifiable.
+     */
+    <T> T putSpecialized(IdentifierSpace<T> authority, T value) throws UnsupportedOperationException;
+}

Propchange: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifierMap.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/IdentifierMap.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain



Mime
View raw message