| /* |
| * 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.metadata; |
| |
| import java.util.Set; |
| import java.util.Map; |
| import java.util.LinkedHashSet; |
| import java.util.Collection; |
| import java.util.Iterator; |
| import java.util.concurrent.ConcurrentMap; |
| import java.util.concurrent.ConcurrentHashMap; |
| import java.io.IOException; |
| import java.io.Serializable; |
| import java.io.ObjectInputStream; |
| import java.io.InvalidClassException; |
| import java.security.AccessController; |
| import org.opengis.metadata.Identifier; |
| import org.opengis.metadata.citation.Citation; |
| import org.opengis.metadata.ExtendedElementInformation; |
| import org.apache.sis.util.Classes; |
| import org.apache.sis.util.ComparisonMode; |
| import org.apache.sis.util.collection.TreeTable; |
| import org.apache.sis.util.collection.CheckedContainer; |
| import org.apache.sis.internal.system.Modules; |
| import org.apache.sis.internal.system.Semaphores; |
| import org.apache.sis.internal.system.SystemListener; |
| import org.apache.sis.internal.simple.SimpleCitation; |
| import org.apache.sis.internal.util.FinalFieldSetter; |
| import org.apache.sis.internal.util.Strings; |
| |
| import static org.apache.sis.util.ArgumentChecks.ensureNonNull; |
| import static org.apache.sis.util.ArgumentChecks.ensureNonNullElement; |
| |
| |
| /** |
| * 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 {@linkplain #ISO_19115 ISO 19115} |
| * standard is defined by <a href="http://www.geoapi.org">GeoAPI</a> interfaces in the |
| * {@link org.opengis.metadata} package and sub-packages. |
| * |
| * <p>This class provides some methods operating on metadata instances through |
| * {@linkplain java.lang.reflect Java reflection}. The following rules are assumed:</p> |
| * |
| * <ul> |
| * <li>Metadata properties are defined by the collection of following getter methods found |
| * <strong>in the interface</strong>, ignoring implementation methods: |
| * <ul> |
| * <li>{@code get*()} methods with arbitrary return type;</li> |
| * <li>or {@code is*()} methods with boolean return type.</li> |
| * </ul></li> |
| * <li>All properties are <cite>readable</cite>.</li> |
| * <li>A property is also <cite>writable</cite> if a {@code set*(…)} method is defined |
| * <strong>in the implementation class</strong> for the corresponding getter method. |
| * The setter method doesn't need to be defined in the interface.</li> |
| * </ul> |
| * |
| * An instance of {@code MetadataStandard} is associated to every {@link AbstractMetadata} objects. |
| * The {@code AbstractMetadata} base class usually form the basis of ISO 19115 implementations but |
| * can also be used for other standards. |
| * |
| * <h2>Defining new {@code MetadataStandard} instances</h2> |
| * Users should use the pre-defined constants when applicable. |
| * However if new instances need to be defined, then there is a choice: |
| * |
| * <ul> |
| * <li>For <em>read-only</em> metadata, {@code MetadataStandard} can be instantiated directly. |
| * Only getter methods will be used and all operations that modify the metadata properties |
| * will throw an {@link UnmodifiableMetadataException}.</li> |
| * <li>For <em>read/write</em> metadata, the {@link #getImplementation(Class)} |
| * method must be overridden in a {@code MetadataStandard} subclass.</li> |
| * </ul> |
| * |
| * <h2>Thread safety</h2> |
| * The same {@code MetadataStandard} 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 {@code MetadataStandard} instances are typically referenced |
| * by a large amount of {@link ModifiableMetadata}. |
| * |
| * @author Martin Desruisseaux (Geomatys) |
| * @version 1.0 |
| * |
| * @see AbstractMetadata |
| * |
| * @since 0.3 |
| * @module |
| */ |
| public class MetadataStandard implements Serializable { |
| /** |
| * For cross-version compatibility. |
| */ |
| private static final long serialVersionUID = 7549790450195184843L; |
| |
| /** |
| * {@code true} if implementations can alter the API defined in the interfaces by |
| * adding or removing properties. If {@code true}, then {@link PropertyAccessor} |
| * will check for {@link Deprecated} and {@link org.opengis.annotation.UML} |
| * annotations in the implementation classes in addition to the interfaces. |
| * |
| * <p>A value of {@code true} is useful when Apache SIS implements a newer standard |
| * than GeoAPI, but have a slight performance cost at construction time. Performance |
| * after construction should be the same.</p> |
| */ |
| static final boolean IMPLEMENTATION_CAN_ALTER_API = false; |
| |
| /** |
| * Metadata instances defined in this class. The current implementation does not yet |
| * contains the user-defined instances. However this may be something we will need to |
| * do in the future. |
| */ |
| private static final MetadataStandard[] INSTANCES; |
| |
| /** |
| * An instance working on ISO 19111 standard as defined by GeoAPI interfaces |
| * in the {@link org.opengis.referencing} package and sub-packages. |
| */ |
| public static final MetadataStandard ISO_19111; |
| |
| /** |
| * An instance working on ISO 19115 standard as defined by GeoAPI interfaces |
| * in the {@link org.opengis.metadata} package and sub-packages. |
| */ |
| public static final MetadataStandard ISO_19115; |
| |
| /** |
| * An instance working on ISO 19123 standard as defined by GeoAPI interfaces |
| * in the {@link org.opengis.coverage} package and sub-packages. |
| */ |
| public static final MetadataStandard ISO_19123; |
| static { |
| final String[] acronyms = {"CoordinateSystem", "CS", "CoordinateReferenceSystem", "CRS"}; |
| |
| // If new StandardImplementation instances are added below, please update StandardImplementation.readResolve(). |
| ISO_19115 = new StandardImplementation("ISO 19115", "org.opengis.metadata.", "org.apache.sis.metadata.iso.", null, null); |
| ISO_19111 = new StandardImplementation("ISO 19111", "org.opengis.referencing.", "org.apache.sis.referencing.", acronyms, new MetadataStandard[] {ISO_19115}); |
| ISO_19123 = new MetadataStandard ("ISO 19123", "org.opengis.coverage.", new MetadataStandard[] {ISO_19111}); |
| INSTANCES = new MetadataStandard[] { |
| ISO_19111, |
| ISO_19115, |
| ISO_19123 |
| }; |
| SystemListener.add(new SystemListener(Modules.METADATA) { |
| @Override protected void classpathChanged() { |
| clearCache(); |
| } |
| }); |
| } |
| |
| /** |
| * Bibliographical reference to the international standard. |
| * |
| * @see #getCitation() |
| */ |
| final Citation citation; |
| |
| /** |
| * The root package for metadata interfaces. Must have a trailing {@code '.'}. |
| */ |
| final String interfacePackage; |
| |
| /** |
| * The dependencies, or {@code null} if none. |
| * |
| * Note: the {@code null} value is for serialization compatibility. |
| */ |
| private final MetadataStandard[] dependencies; |
| |
| /** |
| * Accessors for the specified implementation classes. |
| * The only legal value types are: |
| * |
| * <ul> |
| * <li>{@link MetadataStandard} if type is handled by {@linkplain #dependencies} rather than this standard.</li> |
| * <li>{@link Class} if we found the interface for the type but did not yet created the {@link PropertyAccessor}.</li> |
| * <li>{@link PropertyAccessor} otherwise.</li> |
| * </ul> |
| */ |
| private final transient ConcurrentMap<CacheKey,Object> accessors; // written by reflection on deserialization. |
| |
| /** |
| * Creates a new instance working on implementation of interfaces defined in the specified package. |
| * |
| * <div class="note"><b>Example:</b>: For the ISO 19115 standard reflected by GeoAPI interfaces, |
| * {@code interfacePackage} shall be the {@link org.opengis.metadata} package.</div> |
| * |
| * @param citation bibliographical reference to the international standard. |
| * @param interfacePackage the root package for metadata interfaces. |
| * @param dependencies the dependencies to other metadata standards. |
| */ |
| public MetadataStandard(final Citation citation, final Package interfacePackage, MetadataStandard... dependencies) { |
| ensureNonNull("citation", citation); |
| ensureNonNull("interfacePackage", interfacePackage); |
| ensureNonNull("dependencies", dependencies); |
| this.citation = citation; |
| this.interfacePackage = interfacePackage.getName() + '.'; |
| this.accessors = new ConcurrentHashMap<>(); // Also defined in readObject(…) |
| if (dependencies.length == 0) { |
| this.dependencies = null; |
| } else { |
| this.dependencies = dependencies = dependencies.clone(); |
| for (int i=0; i<dependencies.length; i++) { |
| ensureNonNullElement("dependencies", i, dependencies[i]); |
| } |
| } |
| } |
| |
| /** |
| * Creates a new instance working on implementation of interfaces defined in the |
| * specified package. This constructor is used only for the pre-defined constants. |
| * |
| * @param citation bibliographical reference to the international standard. |
| * @param interfacePackage the root package for metadata interfaces. |
| * @param dependencies the dependencies to other metadata standards, or {@code null} if none. |
| */ |
| MetadataStandard(final String citation, final String interfacePackage, final MetadataStandard[] dependencies) { |
| this.citation = new SimpleCitation(citation); |
| this.interfacePackage = interfacePackage; |
| this.accessors = new ConcurrentHashMap<>(); |
| this.dependencies = dependencies; // No clone, since this constructor is for internal use only. |
| } |
| |
| /** |
| * Returns {@code true} if class or interface of the given name is supported by this standard. |
| * This method verifies if the class is a member of the package given at construction time or |
| * a sub-package. This method does not verify if the type is supported by a dependency. |
| * |
| * @param classname the name of the type to verify. |
| * @return {@code true} if the given type is supported by this standard. |
| */ |
| final boolean isSupported(final String classname) { |
| return classname.startsWith(interfacePackage); |
| } |
| |
| /** |
| * 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. |
| * |
| * <p>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.</p> |
| * |
| * @param type the metadata standard interface, or an implementation class. |
| * @return the metadata standard for the given type, or {@code null} if not found. |
| */ |
| public static MetadataStandard forClass(final Class<?> type) { |
| String classname = type.getName(); |
| for (final MetadataStandard candidate : INSTANCES) { |
| if (candidate.isSupported(classname)) { |
| return candidate; |
| } |
| } |
| for (final Class<?> interf : Classes.getAllInterfaces(type)) { |
| classname = interf.getName(); |
| for (final MetadataStandard candidate : INSTANCES) { |
| if (candidate.isSupported(classname)) { |
| return candidate; |
| } |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * Clears the cache of accessors. This method is invoked when the classpath changed, |
| * in order to discard the references to classes that may need to be unloaded. |
| */ |
| static void clearCache() { |
| for (final MetadataStandard standard : INSTANCES) { |
| standard.accessors.clear(); |
| } |
| } |
| |
| /** |
| * Returns a bibliographical reference to the international standard. |
| * The default implementation return the citation given at construction time. |
| * |
| * @return bibliographical reference to the international standard. |
| */ |
| public Citation getCitation() { |
| return citation; |
| } |
| |
| /** |
| * Returns a key for use in {@link #getAccessor(CacheKey, boolean)} for the given type. |
| * The type may be an interface (typically a GeoAPI interface) or an implementation class. |
| */ |
| private CacheKey createCacheKey(Class<?> type) { |
| final Class<?> implementation = getImplementation(type); |
| if (implementation != null) { |
| type = implementation; |
| } |
| return new CacheKey(type); |
| } |
| |
| /** |
| * Returns the accessor for the specified implementation class, or {@code null} if none. |
| * The given class shall not be the standard interface, unless the metadata is read-only. |
| * More specifically, the given {@code type} shall be one of the following: |
| * |
| * <ul> |
| * <li>The value of {@code metadata.getClass()};</li> |
| * <li>The value of {@link #getImplementation(Class)} after check for non-null value.</li> |
| * </ul> |
| * |
| * @param key the implementation class together with the type declared by the property. |
| * @param mandatory whether this method shall throw an exception or return {@code null} |
| * if no accessor is found for the given implementation class. |
| * @return the accessor for the given implementation, or {@code null} if the given class does not |
| * implement a metadata interface of the expected package and {@code mandatory} is {@code false}. |
| * @throws ClassCastException if the specified class does not implement a metadata interface |
| * of the expected package and {@code mandatory} is {@code true}. |
| */ |
| final PropertyAccessor getAccessor(final CacheKey key, final boolean mandatory) { |
| /* |
| * Check for accessors created by previous calls to this method. |
| * Values are added to this cache but never cleared. |
| */ |
| final Object value = accessors.get(key); |
| if (value instanceof PropertyAccessor) { |
| return (PropertyAccessor) value; |
| } |
| /* |
| * Check if we started some computation that we can finish. A partial computation exists |
| * when we already found the Class<?> for the interface, but didn't created the accessor. |
| */ |
| final Class<?> type; |
| if (value instanceof Class<?>) { |
| type = (Class<?>) value; // Stored result of previous call to findInterface(…). |
| assert type == findInterface(key) : key; |
| } else if (key.isValid()) { |
| /* |
| * Nothing was computed, we need to start from scratch. The first step is to find |
| * the interface implemented by the given class. If we can not find an interface, |
| * we will delegate to the dependencies and store the result for avoiding redoing |
| * this search next time. |
| */ |
| type = findInterface(key); |
| if (type == null) { |
| if (dependencies != null) { |
| for (final MetadataStandard dependency : dependencies) { |
| final PropertyAccessor accessor = dependency.getAccessor(key, false); |
| if (accessor != null) { |
| accessors.put(key, accessor); // Ok to overwrite existing instance here. |
| return accessor; |
| } |
| } |
| } |
| if (mandatory) { |
| throw new ClassCastException(key.unrecognized()); |
| } |
| return null; |
| } |
| } else { |
| throw new ClassCastException(key.invalid()); |
| } |
| /* |
| * Found the interface for which to create an accessor. Creates the accessor now, unless an accessor |
| * has been created concurrently in another thread in which case the later will be returned. |
| */ |
| return (PropertyAccessor) accessors.compute(key, (k, v) -> { |
| if (v instanceof PropertyAccessor) { |
| return v; |
| } |
| final Class<?> standardImpl = getImplementation(type); |
| final PropertyAccessor accessor; |
| if (SpecialCases.isSpecialCase(type)) { |
| accessor = new SpecialCases(type, k.type, standardImpl); |
| } else { |
| accessor = new PropertyAccessor(type, k.type, standardImpl); |
| } |
| return accessor; |
| }); |
| } |
| |
| /** |
| * Returns {@code true} if the given type is assignable to a type from this standard or one of its dependencies. |
| * If this method returns {@code true}, then invoking {@link #getInterface(Class)} is guaranteed to succeed |
| * without throwing an exception. |
| * |
| * @param type the implementation class (can be {@code null}). |
| * @return {@code true} if the given class is an interface of this standard, |
| * or implements an interface of this standard. |
| */ |
| public boolean isMetadata(final Class<?> type) { |
| return (type != null) && !type.isPrimitive() && isMetadata(new CacheKey(type)); |
| } |
| |
| /** |
| * Implementation of {@link #isMetadata(Class)} with the possibility to specify the property type. |
| * We do not provide the additional functionality of this method in public API on the assumption |
| * that if the user know the base metadata type implemented by the value, then (s)he already know |
| * that the value is a metadata instance. |
| * |
| * @see #getInterface(CacheKey) |
| */ |
| private boolean isMetadata(final CacheKey key) { |
| assert key.isValid() : key; |
| if (accessors.containsKey(key)) { |
| return true; |
| } |
| if (dependencies != null) { |
| for (final MetadataStandard dependency : dependencies) { |
| if (dependency.isMetadata(key)) { |
| accessors.putIfAbsent(key, dependency); |
| return true; |
| } |
| } |
| } |
| /* |
| * At this point, all cached values (including those in dependencies) have been checked. |
| * Performs the 'findInterface' computation only in last resort. Current implementation |
| * does not store negative results in order to avoid filling the cache with unrelated classes. |
| */ |
| final Class<?> standardType = findInterface(key); |
| if (standardType != null) { |
| accessors.putIfAbsent(key, standardType); |
| return true; |
| } |
| return false; |
| } |
| |
| /** |
| * Returns {@code true} if the given implementation class, normally rejected by {@link #findInterface(CacheKey)}, |
| * should be accepted as a pseudo-interface. We use this undocumented feature when Apache SIS experiments a new |
| * API which is not yet published in GeoAPI. This happen for example when upgrading Apache SIS public API from |
| * the ISO 19115:2003 standard to the ISO 19115:2014 version, but GeoAPI interfaces are still the old version. |
| * In such case, API that would normally be present in GeoAPI interfaces are temporarily available only in |
| * Apache SIS implementation classes. |
| */ |
| boolean isPendingAPI(final Class<?> type) { |
| return false; |
| } |
| |
| /** |
| * Returns the metadata interface implemented by the specified implementation. |
| * Only one metadata interface can be implemented. If the given type is already |
| * an interface from the standard, then it is returned directly. |
| * |
| * <p>If the given class is the return value of a property, then the type of that property should be specified |
| * in the {@code key.propertyType} argument. This information allows this method to take in account only types |
| * that are assignable to {@code propertyType}, so we can handle classes that implement many metadata interfaces. |
| * For example the {@link org.apache.sis.internal.simple} package have various examples of implementing more than |
| * one interface for convenience.</p> |
| * |
| * <p>This method ignores dependencies. Fallback on metadata standard dependencies shall be done by the caller.</p> |
| * |
| * @param key the standard interface or the implementation class. |
| * @return the single interface, or {@code null} if none where found. |
| */ |
| private Class<?> findInterface(final CacheKey key) { |
| assert key.isValid() : key; |
| if (key.type.isInterface()) { |
| if (isSupported(key.type.getName())) { |
| return key.type; |
| } |
| } else { |
| /* |
| * Gets every interfaces from the supplied package in declaration order, |
| * including the ones declared in the super-class. |
| */ |
| final Set<Class<?>> interfaces = new LinkedHashSet<>(); |
| for (Class<?> t=key.type; t!=null; t=t.getSuperclass()) { |
| getInterfaces(t, key.propertyType, interfaces); |
| } |
| /* |
| * If we found more than one interface, removes the |
| * ones that are sub-interfaces of the other. |
| */ |
| for (final Iterator<Class<?>> it=interfaces.iterator(); it.hasNext();) { |
| final Class<?> candidate = it.next(); |
| for (final Class<?> child : interfaces) { |
| if (candidate != child && candidate.isAssignableFrom(child)) { |
| it.remove(); |
| break; |
| } |
| } |
| } |
| final Iterator<Class<?>> it = interfaces.iterator(); |
| if (it.hasNext()) { |
| final Class<?> candidate = it.next(); |
| if (!it.hasNext()) { |
| return candidate; |
| } |
| /* |
| * Found more than one interface; we don't know which one to pick. |
| * Returns 'null' for now; the caller will thrown an exception. |
| */ |
| } else if (IMPLEMENTATION_CAN_ALTER_API) { |
| /* |
| * Found no interface. According to our method contract we should return null. |
| * However we make an exception if the implementation class has a UML annotation. |
| * The reason is that when upgrading API from ISO 19115:2003 to ISO 19115:2014, |
| * implementations are provided in Apache SIS before the corresponding interfaces |
| * are published on GeoAPI. The reason why GeoAPI is slower to upgrade is that we |
| * have to go through a voting process inside the Open Geospatial Consortium (OGC). |
| * So we use those implementation classes as a temporary substitute for the interfaces. |
| */ |
| if (isPendingAPI(key.type)) { |
| return key.type; |
| } |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * Puts every interfaces for the given type in the specified collection. |
| * This method invokes itself recursively for scanning parent interfaces. |
| * |
| * <p>If the given class is the return value of a property, then the type of that property should be specified |
| * in the {@code propertyType} argument. This information allows this method to take in account only the types |
| * that are assignable to {@code propertyType}, so we can handle classes that implement many metadata interfaces. |
| * For example the {@link org.apache.sis.internal.simple} package have various examples of implementing more than |
| * one interface for convenience.</p> |
| * |
| * @see Classes#getAllInterfaces(Class) |
| */ |
| private void getInterfaces(final Class<?> type, final Class<?> propertyType, final Collection<Class<?>> interfaces) { |
| for (final Class<?> candidate : type.getInterfaces()) { |
| if (propertyType.isAssignableFrom(candidate)) { |
| if (isSupported(candidate.getName())) { |
| interfaces.add(candidate); |
| } |
| getInterfaces(candidate, propertyType, interfaces); |
| } else if (IMPLEMENTATION_CAN_ALTER_API) { |
| /* |
| * If a GeoAPI interface is not assignable to the property type, maybe it is because the property type |
| * did not existed at the time current GeoAPI version was published. In such case, the implementation |
| * class may be a placeholder (pending API) for the not-yet-published GeoAPI interfaces. In that case |
| * we skip the `isAssignableFrom` check, but without recursive addition of parent interfaces since we |
| * would not know when to stop. |
| */ |
| if (isPendingAPI(propertyType)) { |
| if (isSupported(candidate.getName())) { |
| interfaces.add(candidate); |
| } |
| // No recursive call here. |
| } |
| } |
| } |
| } |
| |
| /** |
| * 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. |
| * |
| * <div class="note"><b>Note:</b> |
| * 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.</div> |
| * |
| * @param <T> the compile-time {@code type}. |
| * @param type the implementation class. |
| * @return the interface implemented by the given implementation class. |
| * @throws ClassCastException if the specified implementation class does not implement an interface of this standard. |
| * |
| * @see AbstractMetadata#getInterface() |
| */ |
| public <T> Class<? super T> getInterface(final Class<T> type) throws ClassCastException { |
| ensureNonNull("type", type); |
| return getInterface(new CacheKey(type)); |
| } |
| |
| /** |
| * Implementation of {@link #getInterface(Class)} with the possibility to specify the property type. |
| * We do not provide the additional functionality of this method in public API on the assumption that |
| * users who want to invoke a {@code getInterface(…)} method does not know what that interface is. |
| * In Apache SIS case, we invoke this method when we almost know what the interface is but want to |
| * check if the actual value is a subtype. |
| * |
| * @see #isMetadata(CacheKey) |
| */ |
| @SuppressWarnings("unchecked") |
| final <T> Class<? super T> getInterface(final CacheKey key) throws ClassCastException { |
| final Class<?> interf; |
| final Object value = accessors.get(key); |
| if (value instanceof PropertyAccessor) { |
| interf = ((PropertyAccessor) value).type; |
| } else if (value instanceof Class<?>) { |
| interf = (Class<?>) value; |
| } else if (value instanceof MetadataStandard) { |
| interf = ((MetadataStandard) value).getInterface(key); |
| } else if (key.isValid()) { |
| interf = findInterface(key); |
| if (interf != null) { |
| accessors.putIfAbsent(key, interf); |
| } else { |
| if (dependencies != null) { |
| for (final MetadataStandard dependency : dependencies) { |
| if (dependency.isMetadata(key)) { |
| accessors.putIfAbsent(key, dependency); |
| return dependency.getInterface(key); |
| } |
| } |
| } |
| throw new ClassCastException(key.unrecognized()); |
| } |
| } else { |
| throw new ClassCastException(key.invalid()); |
| } |
| assert interf.isAssignableFrom(key.type) : key; |
| return (Class<? super T>) interf; |
| } |
| |
| /** |
| * Returns the implementation class for the given interface, or {@code 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. |
| * |
| * <p>The default implementation returns {@code null} in every cases. Subclasses shall |
| * override this method in order to map GeoAPI interfaces to their implementation.</p> |
| * |
| * @param <T> the compile-time {@code type}. |
| * @param type the interface, typically from the {@code org.opengis.metadata} package. |
| * @return the implementation class, or {@code null} if none. |
| */ |
| public <T> Class<? extends T> getImplementation(final Class<T> type) { |
| return null; |
| } |
| |
| /** |
| * Returns a value of the "title" property of the given metadata object. |
| * The title property is defined by {@link TitleProperty} annotation on the implementation class. |
| * |
| * @param metadata the metadata for which to get the title property, or {@code null}. |
| * @return the title property value of the given metadata, or {@code null} if none. |
| * |
| * @see TitleProperty |
| * @see ValueExistencePolicy#COMPACT |
| */ |
| final Object getTitle(final Object metadata) { |
| if (metadata != null) { |
| final Class<?> type = metadata.getClass(); |
| final PropertyAccessor accessor = getAccessor(createCacheKey(type), false); |
| if (accessor != null) { |
| TitleProperty an = type.getAnnotation(TitleProperty.class); |
| if (an != null || (an = accessor.implementation.getAnnotation(TitleProperty.class)) != null) { |
| return accessor.get(accessor.indexOf(an.name(), false), metadata); |
| } |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * 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 {@linkplain KeyNamePolicy#UML_IDENTIFIER standard identifiers} (e.g. |
| * as defined by ISO 19115), {@linkplain KeyNamePolicy#JAVABEANS_PROPERTY JavaBeans names}, |
| * {@linkplain KeyNamePolicy#METHOD_NAME method names} or {@linkplain KeyNamePolicy#SENTENCE |
| * sentences} (usually in English). |
| * |
| * <div class="note"><b>Example:</b> |
| * The following code prints <code>"alternateTitle<u>s</u>"</code> (note the plural): |
| * |
| * {@preformat java |
| * 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 |
| * } |
| * </div> |
| * |
| * The {@code keyPolicy} argument specify only the string representation of keys returned by the iterators. |
| * No matter the key name policy, the {@code key} argument given to any {@link Map} method can be any of the |
| * above-cited forms of property names. |
| * |
| * @param type the interface or implementation class of a metadata. |
| * @param keyPolicy determines the string representation of map keys. |
| * @param valuePolicy determines the string representation of map values. |
| * @return the names of all properties defined by the given metadata type. |
| * @throws ClassCastException if the specified interface or implementation class does |
| * not extend or implement a metadata interface of the expected package. |
| */ |
| public Map<String,String> asNameMap(final Class<?> type, final KeyNamePolicy keyPolicy, |
| final KeyNamePolicy valuePolicy) throws ClassCastException |
| { |
| ensureNonNull("type", type); |
| ensureNonNull("keyPolicy", keyPolicy); |
| ensureNonNull("valuePolicy", valuePolicy); |
| return new NameMap(getAccessor(createCacheKey(type), true), keyPolicy, 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 than the keys in the above {@linkplain #asNameMap name map}. |
| * The values are determined by the {@code valuePolicy} argument, which can be |
| * {@linkplain TypeValuePolicy#ELEMENT_TYPE element type} or the |
| * {@linkplain TypeValuePolicy#DECLARING_INTERFACE declaring interface} among others. |
| * |
| * <div class="note"><b>Example:</b> |
| * the following code prints the {@link org.opengis.util.InternationalString} class name: |
| * |
| * {@preformat java |
| * 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 |
| * } |
| * </div> |
| * |
| * @param type the interface or implementation class of a metadata. |
| * @param keyPolicy determines the string representation of map keys. |
| * @param valuePolicy whether the values shall be property types, the element types |
| * (same as property types except for collections) or the declaring interface or class. |
| * @return the types or declaring type of all properties defined in the given metadata type. |
| * @throws ClassCastException if the specified interface or implementation class does |
| * not extend or implement a metadata interface of the expected package. |
| */ |
| public Map<String,Class<?>> asTypeMap(final Class<?> type, final KeyNamePolicy keyPolicy, |
| final TypeValuePolicy valuePolicy) throws ClassCastException |
| { |
| ensureNonNull("type", type); |
| ensureNonNull("keyPolicy", keyPolicy); |
| ensureNonNull("valuePolicy", valuePolicy); |
| return new TypeMap(getAccessor(createCacheKey(type), true), keyPolicy, valuePolicy); |
| } |
| |
| /** |
| * Returns information about all properties defined in the given metadata type. |
| * The keys in the returned map are the same than the keys in the above |
| * {@linkplain #asNameMap name map}. The values contain information inferred from |
| * the ISO names, the {@link org.opengis.annotation.Obligation} enumeration and the |
| * {@link org.apache.sis.measure.ValueRange} annotations. |
| * |
| * <p>In the particular case of Apache SIS implementation, all values in the information map |
| * additionally implement the following interfaces:</p> |
| * <ul> |
| * <li>{@link Identifier} with the following properties: |
| * <ul> |
| * <li>The {@linkplain Identifier#getAuthority() authority} is this metadata standard {@linkplain #getCitation() citation}.</li> |
| * <li>The {@linkplain Identifier#getCodeSpace() codespace} is the standard name of the interface that contain the property.</li> |
| * <li>The {@linkplain Identifier#getCode() code} is the standard name of the property.</li> |
| * </ul> |
| * </li> |
| * <li>{@link CheckedContainer} with the following properties: |
| * <ul> |
| * <li>The {@linkplain CheckedContainer#getElementType() element type} is the type of property values |
| * as defined by {@link TypeValuePolicy#ELEMENT_TYPE}.</li> |
| * </ul> |
| * </li> |
| * </ul> |
| * |
| * <div class="note"><b>Note:</b> |
| * the rational for implementing {@code CheckedContainer} is to consider each {@code ExtendedElementInformation} |
| * instance as the set of all possible values for the property. If the information had a {@code contains(E)} method, |
| * it would return {@code true} if the given value is valid for that property.</div> |
| * |
| * In addition, for each map entry the value returned by {@link ExtendedElementInformation#getDomainValue()} |
| * may optionally be an instance of any of the following classes: |
| * |
| * <ul> |
| * <li>{@link org.apache.sis.measure.NumberRange} if the valid values are constrained to some specific range.</li> |
| * </ul> |
| * |
| * @param type the metadata interface or implementation class. |
| * @param keyPolicy determines the string representation of map keys. |
| * @return information about all properties defined in the given metadata type. |
| * @throws ClassCastException if the given type does not implement a metadata interface of the expected package. |
| * |
| * @see org.apache.sis.metadata.iso.DefaultExtendedElementInformation |
| */ |
| public Map<String,ExtendedElementInformation> asInformationMap(final Class<?> type, final KeyNamePolicy keyPolicy) |
| throws ClassCastException |
| { |
| ensureNonNull("type", type); |
| ensureNonNull("keyNames", keyPolicy); |
| return new InformationMap(citation, getAccessor(createCacheKey(type), true), keyPolicy); |
| } |
| |
| /** |
| * Returns indices for all properties defined in the given metadata type. |
| * The keys in the returned map are the same than the keys in the above {@linkplain #asNameMap name map}. |
| * The values are arbitrary indices numbered from 0 inclusive to <var>n</var> exclusive, where <var>n</var> |
| * is the number of properties declared in the given metadata type. |
| * |
| * <p>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.</p> |
| * |
| * @param type the interface or implementation class of a metadata. |
| * @param keyPolicy determines the string representation of map keys. |
| * @return indices of all properties defined by the given metadata type. |
| * @throws ClassCastException if the specified interface or implementation class does |
| * not extend or implement a metadata interface of the expected package. |
| */ |
| public Map<String,Integer> asIndexMap(final Class<?> type, final KeyNamePolicy keyPolicy) |
| throws ClassCastException |
| { |
| ensureNonNull("type", type); |
| ensureNonNull("keyPolicy", keyPolicy); |
| return new IndexMap(getAccessor(createCacheKey(type), true), keyPolicy); |
| } |
| |
| /** |
| * Returns a view of the specified metadata object as a {@link 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. |
| * |
| * <p>The map content is determined by the arguments: {@code metadata} determines the set of |
| * keys, {@code keyPolicy} determines their {@code String} representations of those keys and |
| * {@code valuePolicy} determines whether entries having a null value or an empty collection |
| * shall be included in the map.</p> |
| * |
| * <h4>Supported operations</h4> |
| * The map supports the {@link Map#put(Object, Object) put(…)} and {@link Map#remove(Object) |
| * remove(…)} operations if the underlying metadata object contains setter methods. |
| * The {@code remove(…)} method is implemented by a call to {@code put(…, null)}. |
| * Note that whether the entry appears as effectively removed from the map or just cleared |
| * (i.e. associated to a null value) depends on the {@code valuePolicy} argument. |
| * |
| * <h4>Keys and values</h4> |
| * The keys are case-insensitive and can be either the JavaBeans property name, the getter method name |
| * or the {@linkplain org.opengis.annotation.UML#identifier() UML identifier}. The value given to a call |
| * to the {@code put(…)} method shall be an instance of the type expected by the corresponding setter method, |
| * or an instance of a type {@linkplain org.apache.sis.util.ObjectConverters#find(Class, Class) convertible} |
| * to the expected type. |
| * |
| * <h4>Multi-values entries</h4> |
| * Calls to {@code put(…)} replace the previous value, with one noticeable exception: if the metadata |
| * property associated to the given key is a {@link java.util.Collection} but the given value is a single |
| * element (not a collection), then the given value is {@linkplain java.util.Collection#add(Object) added} |
| * to the existing collection. In other words, the returned map behaves as a <cite>multi-values map</cite> |
| * 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. |
| * |
| * <h4>Disambiguating instances that implement more than one metadata interface</h4> |
| * 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 |
| * {@link org.opengis.metadata.extent.Extent} and {@link org.opengis.metadata.extent.GeographicBoundingBox} |
| * 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 {@code baseType} argument. |
| * That argument needs to be non-null only in situations where an ambiguity can arise; {@code baseType} can be null |
| * if the given metadata implements only one interface recognized by this {@code MetadataStandard} instance. |
| * |
| * @param metadata the metadata object to view as a map. |
| * @param baseType base type of the metadata of interest, or {@code null} if unspecified. |
| * @param keyPolicy determines the string representation of map keys. |
| * @param valuePolicy whether the entries having null value or empty collection shall be included in the map. |
| * @return a map view over the metadata object. |
| * @throws ClassCastException if the metadata object does not implement a metadata interface of the expected package. |
| * |
| * @see AbstractMetadata#asMap() |
| * |
| * @since 0.8 |
| */ |
| public Map<String,Object> asValueMap(final Object metadata, final Class<?> baseType, |
| final KeyNamePolicy keyPolicy, final ValueExistencePolicy valuePolicy) throws ClassCastException |
| { |
| ensureNonNull("metadata", metadata); |
| ensureNonNull("keyPolicy", keyPolicy); |
| ensureNonNull("valuePolicy", valuePolicy); |
| return new ValueMap(metadata, getAccessor(new CacheKey(metadata.getClass(), baseType), true), keyPolicy, 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. |
| * |
| * <p>The returned {@code TreeTable} instance contains the following columns:</p> |
| * <ul class="verbose"> |
| * <li>{@link org.apache.sis.util.collection.TableColumn#IDENTIFIER}<br> |
| * The {@linkplain org.opengis.annotation.UML#identifier() UML identifier} if any, |
| * or the Java Beans property name otherwise, of a metadata property. For example |
| * in a tree table view of {@link org.apache.sis.metadata.iso.citation.DefaultCitation}, |
| * there is a node having the {@code "title"} identifier.</li> |
| * |
| * <li>{@link org.apache.sis.util.collection.TableColumn#INDEX}<br> |
| * If the metadata property is a collection, then the zero-based index of the element in that collection. |
| * Otherwise {@code null}. For example in a tree table view of {@code DefaultCitation}, if the |
| * {@code "alternateTitle"} collection contains two elements, then there is a node with index 0 |
| * for the first element and an other node with index 1 for the second element. |
| * |
| * <div class="note"><b>Note:</b> |
| * The {@code (IDENTIFIER, INDEX)} pair 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.</div></li> |
| * |
| * <li>{@link org.apache.sis.util.collection.TableColumn#NAME}<br> |
| * A human-readable name for the node, derived from the identifier and the index. |
| * This is the column shown in the default {@link #toString()} implementation and |
| * may be localizable.</li> |
| * |
| * <li>{@link org.apache.sis.util.collection.TableColumn#TYPE}<br> |
| * The base type of the value (usually an interface).</li> |
| * |
| * <li>{@link org.apache.sis.util.collection.TableColumn#VALUE}<br> |
| * 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.</li> |
| * |
| * <li>{@link org.apache.sis.util.collection.TableColumn#REMARKS}<br> |
| * 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 spanning the anti-meridian.</li> |
| * </ul> |
| * |
| * <h4>Write operations</h4> |
| * Only the {@code VALUE} column may be writable, with one exception: newly created children need |
| * to have their {@code IDENTIFIER} set before any other operation. For example the following code |
| * adds a title to a citation: |
| * |
| * {@preformat java |
| * 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 {@link java.util.Iterator#remove()} method on the |
| * {@linkplain org.apache.sis.util.collection.TreeTable.Node#getChildren() children} iterator. |
| * Note that whether the child appears as effectively removed from the node or just cleared |
| * (i.e. associated to a null value) depends on the {@code valuePolicy} argument. |
| * |
| * <h4>Disambiguating instances that implement more than one metadata interface</h4> |
| * If the given {@code metadata} instance implements more than one interface recognized by this |
| * {@code MetadataStandard}, then the {@code baseType} argument need to be non-null in order to |
| * specify which interface to reflect in the tree. |
| * |
| * @param metadata the metadata object to view as a tree table. |
| * @param baseType base type of the metadata of interest, or {@code null} if unspecified. |
| * @param valuePolicy whether the property having null value or empty collection shall be included in the tree. |
| * @return a tree table representation of the specified metadata. |
| * @throws ClassCastException if the metadata object does not implement a metadata interface of the expected package. |
| * |
| * @see AbstractMetadata#asTreeTable() |
| * |
| * @since 0.8 |
| */ |
| public TreeTable asTreeTable(final Object metadata, Class<?> baseType, final ValueExistencePolicy valuePolicy) |
| throws ClassCastException |
| { |
| ensureNonNull("metadata", metadata); |
| ensureNonNull("valuePolicy", valuePolicy); |
| if (baseType == null) { |
| baseType = getInterface(metadata.getClass()); |
| } |
| return new TreeTableView(this, metadata, baseType, valuePolicy); |
| } |
| |
| /** |
| * Compares the two specified metadata objects. |
| * The two metadata arguments shall be implementations of a metadata interface defined by |
| * this {@code MetadataStandard}, otherwise an exception will be thrown. However the two |
| * arguments do not need to be the same implementation class. |
| * |
| * <h4>Shallow or deep comparisons</h4> |
| * This method implements a <cite>shallow</cite> comparison in that properties are compared by |
| * invoking their {@code properties.equals(…)} method without <em>explicit</em> recursive call |
| * to this {@code standard.equals(…)} method for children metadata. However the comparison will |
| * do <em>implicit</em> recursive calls if the {@code properties.equals(…)} implementations |
| * delegate their work to this {@code standard.equals(…)} method, as {@link AbstractMetadata} does. |
| * In the later case, the final result is a deep comparison. |
| * |
| * @param metadata1 the first metadata object to compare. |
| * @param metadata2 the second metadata object to compare. |
| * @param mode the strictness level of the comparison. |
| * @return {@code true} if the given metadata objects are equals. |
| * @throws ClassCastException if at least one metadata object does not |
| * implement a metadata interface of the expected package. |
| * |
| * @see AbstractMetadata#equals(Object, ComparisonMode) |
| */ |
| public boolean equals(final Object metadata1, final Object metadata2, |
| final ComparisonMode mode) throws ClassCastException |
| { |
| if (metadata1 == metadata2) { |
| return true; |
| } |
| if (metadata1 == null || metadata2 == null) { |
| return false; |
| } |
| final Class<?> type1 = metadata1.getClass(); |
| final Class<?> type2 = metadata2.getClass(); |
| if (type1 != type2 && mode == ComparisonMode.STRICT) { |
| return false; |
| } |
| final PropertyAccessor accessor = getAccessor(new CacheKey(type1), true); |
| if (type1 != type2 && (!accessor.type.isAssignableFrom(type2) |
| || accessor.type != getAccessor(new CacheKey(type2), false).type)) |
| { |
| /* |
| * Note: the check for (accessor.type != getAccessor(…).type) would have been enough, but checking |
| * for isAssignableFrom(…) first can avoid the (relatively costly) creation of new PropertyAccessor. |
| */ |
| return false; |
| } |
| /* |
| * At this point, we have to perform the actual property-by-property comparison. |
| * Cycle may exist in metadata tree, so we have to keep trace of pair in process |
| * of being compared for avoiding infinite recursivity. |
| */ |
| final ObjectPair pair = new ObjectPair(metadata1, metadata2); |
| final Set<ObjectPair> inProgress = ObjectPair.CURRENT.get(); |
| if (inProgress.add(pair)) { |
| /* |
| * The NULL_COLLECTION semaphore prevents creation of new empty collections by getter methods |
| * (a consequence of lazy instantiation). The intent is to avoid creation of unnecessary objects |
| * for all unused properties. Users should not see behavioral difference, except if they override |
| * some getters with an implementation invoking other getters. However in such cases, users would |
| * have been exposed to null values at XML marshalling time anyway. |
| */ |
| final boolean allowNull = Semaphores.queryAndSet(Semaphores.NULL_COLLECTION); |
| try { |
| return accessor.equals(metadata1, metadata2, mode); |
| } finally { |
| inProgress.remove(pair); |
| if (!allowNull) { |
| Semaphores.clear(Semaphores.NULL_COLLECTION); |
| } |
| } |
| } else { |
| /* |
| * If we get here, a cycle has been found. Returns 'true' in order to allow the caller to continue |
| * comparing other properties. It is okay because someone else is comparing those two same objects, |
| * and that later comparison will do the actual check for property values. |
| */ |
| return true; |
| } |
| } |
| |
| /** |
| * 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 {@link java.util.Set#hashCode()} (except for the interface) |
| * and ensures that the hash code value is insensitive to the ordering of properties. |
| * |
| * @param metadata the metadata object to compute hash code. |
| * @return a hash code value for the specified metadata, or 0 if the given metadata is null. |
| * @throws ClassCastException if the metadata object does not implement a metadata interface of the expected package. |
| * |
| * @see AbstractMetadata#hashCode() |
| */ |
| public int hashCode(final Object metadata) throws ClassCastException { |
| if (metadata != null) { |
| final Integer hash = HashCode.getOrCreate().walk(this, null, metadata, true); |
| if (hash != null) return hash; |
| /* |
| * 'hash' may be null if a cycle has been found. Example: A depends on B which depends on A, |
| * in which case the null value is returned for the second occurrence of A (not the first one). |
| * We can not compute a hash code value here, but it should be okay since that metadata is part |
| * of a bigger metadata object, and that enclosing object should have other properties for computing |
| * its hash code. |
| */ |
| } |
| return 0; |
| } |
| |
| /** |
| * Returns a string representation of this metadata standard. |
| * This is for debugging purpose only and may change in any future version. |
| */ |
| @Override |
| public String toString() { |
| return Strings.bracket(getClass(), citation.getTitle()); |
| } |
| |
| /** |
| * Assigns a {@link ConcurrentMap} instance to the given field. |
| * Used on deserialization only. |
| */ |
| static <T extends MetadataStandard> void setMapForField(final Class<T> classe, final T instance, final String name) |
| throws InvalidClassException |
| { |
| try { |
| AccessController.doPrivileged(new FinalFieldSetter<>(classe, name)).set(instance, new ConcurrentHashMap<>()); |
| } catch (ReflectiveOperationException e) { |
| throw FinalFieldSetter.readFailure(e); |
| } |
| } |
| |
| /** |
| * Invoked during deserialization for restoring the transient fields. |
| * |
| * @param in the input stream from which to deserialize a metadata standard. |
| * @throws IOException if an I/O error occurred while reading or if the stream contains invalid data. |
| * @throws ClassNotFoundException if the class serialized on the stream is not on the classpath. |
| */ |
| private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException { |
| in.defaultReadObject(); |
| setMapForField(MetadataStandard.class, this, "accessors"); |
| } |
| } |
