001/* 002 * GeoAPI - Java interfaces for OGC/ISO standards 003 * Copyright © 2004-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.metadata.identification; 019 020import java.util.Map; 021import java.util.Locale; 022import java.util.Collection; 023import java.util.Collections; 024import java.util.LinkedHashSet; 025import java.nio.charset.Charset; 026import org.opengis.util.InternationalString; 027import org.opengis.annotation.UML; 028import org.opengis.annotation.Profile; 029 030import static org.opengis.annotation.Obligation.*; 031import static org.opengis.annotation.Specification.*; 032import static org.opengis.annotation.ComplianceLevel.*; 033 034 035/** 036 * Information required to identify a resource. 037 * 038 * @author Martin Desruisseaux (IRD) 039 * @version 3.1 040 * @since 2.0 041 */ 042@UML(identifier="MD_DataIdentification", specification=ISO_19115) 043public interface DataIdentification extends Identification { 044 /** 045 * Language(s) and character set(s) used within the resource. 046 * The first element in iteration order shall be the default language. 047 * All other elements, if any, are alternate language(s) used within the resource. 048 * Note that contrarily to the {@code PT_Locale} object defined by ISO 19115:2014, the {@code java.util.Locale} 049 * object does not contain character encoding information. The character set information is stored in separated 050 * objects, associated to locales through entries in the map. 051 * 052 * <h4>XML representation</h4> 053 * XML documents shall format languages using the ISO 639-2 language code as returned by {@link Locale#getISO3Language()}. 054 * Character sets shall be referenced by name from the IANA Character Set register. 055 * 056 * @departure integration 057 * GeoAPI replaces ISO 19115:2014 {@code LanguageCode}, {@code CountryCode} and {@code MD_CharacterSetCode} 058 * code lists by equivalent objects from the standard Java library. 059 * See {@link org.opengis.metadata.Metadata#getLocalesAndCharsets()} for more information. 060 * 061 * @return language(s) and character set(s) used within the resource. 062 * 063 * @condition Mandatory if language used in resource. 064 * 065 * @see org.opengis.metadata.Metadata#getLocalesAndCharsets() 066 * @see org.opengis.metadata.content.FeatureCatalogueDescription#getLocalesAndCharsets() 067 * 068 * @since 3.1 069 */ 070 @Profile(level=CORE) 071 // Obligation note: `defaultLocale` is conditional and `otherLocale` is optional. 072 @UML(identifier="defaultLocale+otherLocale", obligation=CONDITIONAL, specification=ISO_19115) 073 default Map<Locale,Charset> getLocalesAndCharsets() { 074 return Collections.emptyMap(); 075 } 076 077 /** 078 * Language(s) used within the resource. 079 * 080 * @return language(s) used. 081 * 082 * @deprecated Replaced by {@code getLocalesAndCharsets().keySet()}. 083 */ 084 @Deprecated(since="3.1") 085 @UML(identifier="language", obligation=MANDATORY, specification=ISO_19115, version=2003) 086 default Collection<Locale> getLanguages() { 087 return getLocalesAndCharsets().keySet(); 088 } 089 090 /** 091 * The character coding standard(s) used for the dataset. 092 * 093 * <div class="warning"><b>Upcoming API change — JDK integration</b><br> 094 * As of ISO 19115:2014, {@code CharacterSet} is replaced by a reference to the 095 * <a href="http://www.iana.org/assignments/character-sets">IANA Character Set register</a>, 096 * which is represented in Java by {@link java.nio.charset.Charset}. 097 * This change may be applied in GeoAPI 4.0. 098 * </div> 099 * 100 * @return the character coding standard(s) used. 101 * 102 * @deprecated Replaced by {@code getLocalesAndCharsets().values()}. 103 */ 104 @Deprecated(since="3.1") 105 @UML(identifier="characterSet", obligation=CONDITIONAL, specification=ISO_19115, version=2003) 106 default Collection<CharacterSet> getCharacterSets() { 107 LinkedHashSet<CharacterSet> codes = new LinkedHashSet<>(); 108 getLocalesAndCharsets().values().forEach((cs) -> { 109 codes.add(CharacterSet.fromCharset(cs)); 110 }); 111 return codes; 112 } 113 114 /** 115 * Description of the resource in the producer's processing environment, including items 116 * such as the software, the computer operating system, file name, and the dataset size. 117 * 118 * @return description of the resource in the producer's processing environment, or {@code null}. 119 */ 120 @UML(identifier="environmentDescription", obligation=OPTIONAL, specification=ISO_19115) 121 default InternationalString getEnvironmentDescription() { 122 return null; 123 } 124 125 /** 126 * Any other descriptive information about the resource. 127 * 128 * @return other descriptive information, or {@code null}. 129 */ 130 @UML(identifier="supplementalInformation", obligation=OPTIONAL, specification=ISO_19115) 131 default InternationalString getSupplementalInformation() { 132 return null; 133 } 134}