001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2006-2024 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.util;
019
020import java.util.Map;
021import org.opengis.annotation.UML;
022
023import static org.opengis.annotation.Obligation.*;
024import static org.opengis.annotation.Specification.*;
025
026
027/**
028 * A collection of {@linkplain RecordType record types}. All schemas possess an associated
029 * {@linkplain NameSpace name space} within which the {@linkplain RecordType record type}
030 * names are defined. A schema is a flat data structure, similar to a Java package.
031 *
032 * <p>Record schemas do not provide a hierarchical framework within which data types may be organized.
033 * {@linkplain NameSpace Name spaces}, however, do define a hierarchical framework for arbitrary
034 * named items. Record schemas can participate in this framework by virtue of the fact that they
035 * are all identified by {@linkplain LocalName local name} or some subclass.  A schema's location
036 * in the hierarchy can be communicated by
037 *
038 * <code>{@linkplain #getSchemaName()}.{@linkplain LocalName#scope() scope()}.{@linkplain NameSpace#name() name()}</code>.
039 * </p>
040 *
041 * @author  Bryce Nordgren (USDA)
042 * @author  Martin Desruisseaux (IRD)
043 * @version 3.0
044 * @since   2.1
045 *
046 * @deprecated The {@code RecordSchema} interface has been removed in the 2015 revision of ISO 19103 standard.
047 */
048@Deprecated(since="3.1")
049@UML(identifier="RecordSchema", specification=ISO_19103, version=2005)
050public interface RecordSchema {
051    /**
052     * Returns the schema name. The {@linkplain LocalName#scope scope} of the schema name is
053     * associated with a {@linkplain NameSpace name space} which fixes this schema to a specific
054     * location in the type hierarchy.
055     *
056     * @return the schema name.
057     */
058    @UML(identifier="schemaName", obligation=MANDATORY, specification=ISO_19103, version=2005)
059    LocalName getSchemaName();
060
061    /**
062     * Returns the dictionary of all (<var>name</var>, <var>record type</var>) pairs
063     * in this schema.
064     *
065     * @return all (<var>name</var>, <var>record type</var>) pairs in this schema.
066     */
067    @UML(identifier="description", obligation=MANDATORY, specification=ISO_19103, version=2005)
068    Map<TypeName, RecordType> getDescription();
069
070    /**
071     * Looks up the provided type name and returns the associated record type. If the type name is not
072     * defined within this schema, then this method returns {@code null}. This is functionally equivalent
073     * to <code>{@linkplain #getDescription()}.{@linkplain Map#get get}(name)</code>.
074     *
075     * @param  name  the name of the type to lookup.
076     * @return the type for the given name, or {@code null} if none.
077     */
078    @UML(identifier="locate", obligation=MANDATORY, specification=ISO_19103, version=2005)
079    RecordType locate(TypeName name);
080}