Class Types
CodeList values.
This class provides:
- Methods for fetching the ISO name or description of a code list:
getStandardName(Class)for ISO namegetListName(CodeList)for ISO namegetDescription(Class)for a description
- Methods for fetching the ISO name or description of a code value:
getCodeName(CodeList)for ISO name,getCodeTitle(CodeList)for a label or titlegetDescription(CodeList)for a more verbose description
- Methods for fetching an instance from a name (converse of above
getmethods):
Substituting a free text by a code list
The ISO standard allows to substitute some character strings in the "free text" domain by aCodeList value.
<mac:type> value is normally a <gco:CharacterString>
but has been replaced by a SensorType code below:
<mac:MI_Instrument>
<mac:type>
<gmi:MI_SensorTypeCode
codeList="http://standards.iso.org/…snip…/codelists.xml#CI_SensorTypeCode"
codeListValue="RADIOMETER">Radiometer</gmi:MI_SensorTypeCode>
</mac:type>
</mac:MI_Instrument>
getCodeTitle(CodeList)for getting theInternationalStringinstance to store in a metadata property.forCodeTitle(CharSequence)for retrieving theCodeListpreviously stored as anInternationalString.
- Since:
- 0.3
Defined in the sis-metadata module
-
Method Summary
Modifier and TypeMethodDescriptionstatic <T extends CodeList<T>>
TforCodeName(Class<T> codeType, String name, boolean canCreate) Returns the code of the given type that matches the given name, or optionally returns a new one if none match the name.static CodeList<?>forCodeTitle(CharSequence title) Returns the code list or enumeration value for the given title, ornullif none.static <T extends Enum<T>>
TforEnumName(Class<T> enumType, String name) Returns the enumeration value of the given type that matches the given name, ornullif none.static Class<?>forStandardName(String identifier) Returns the Java type (usually a GeoAPI interface) for the given ISO name, ornullif none.static StringgetCodeLabel(CodeList<?> code) Returns a unlocalized title for the given enumeration or code list value.static StringgetCodeName(CodeList<?> code) Returns the ISO name (if available) or the Java name (as a fallback) of the given enumeration or code list value.static InternationalStringgetCodeTitle(CodeList<?> code) Returns the title of the given enumeration or code list value.static <T extends CodeList<?>>
T[]getCodeValues(Class<T> codeType) Returns all known values for the given type of code list.static InternationalStringgetDescription(Class<?> type) Returns a description for the given class, ornullif none.static InternationalStringgetDescription(Class<?> type, String property) Returns a description for the given property, ornullif none.static InternationalStringgetDescription(CodeList<?> code) Returns the description of the given enumeration or code list value, ornullif none.static StringgetListName(CodeList<?> code) Returns the ISO classname (if available) or the Java classname (as a fallback) of the given enumeration or code list value.static StringgetStandardName(Class<?> type) Returns the ISO name for the given class, ornullif none.static InternationalStringtoInternationalString(CharSequence string) Returns the given characters sequence as an international string.static InternationalStringtoInternationalString(Map<String, ?> properties, String prefix) Returns an international string for the values in the given properties map, ornullif none.static InternationalString[]toInternationalStrings(CharSequence... strings) Returns the given array ofCharSequences as an array ofInternationalStrings.static StringtoString(InternationalString i18n, Locale locale) Returns the given international string in the given locale, ornullif the given string is null.
-
Method Details
-
getStandardName
Returns the ISO name for the given class, ornullif none. This method can be used for GeoAPI interfaces orCodeList.Examples:This method looks for thegetStandardName(Citation.class)(an interface) returns"CI_Citation".getStandardName(AxisDirection.class)(a code list) returns"CS_AxisDirection".
UMLannotation on the given type. It does not search for parent classes or interfaces if the given type is not directly annotated (i.e.@UMLannotations are not inherited). If no annotation is found, then this method does not fallback on the Java name since, as the name implies, this method is about standard names.- Parameters:
type- the GeoAPI interface or code list from which to get the ISO name, ornull.- Returns:
- the ISO name for the given type, or
nullif none or if the given type isnull. - See Also:
-
getListName
Returns the ISO classname (if available) or the Java classname (as a fallback) of the given enumeration or code list value. This method uses theUMLannotation if it exists, or fallback on the simple class name otherwise.Examples:getListName(ParameterDirection.IN_OUT)returns"SV_ParameterDirection".getListName(AxisDirection.NORTH)returns"CS_AxisDirection".getListName(TopicCategory.INLAND_WATERS)returns"MD_TopicCategoryCode".getListName(ImagingCondition.BLURRED_IMAGE)returns"MD_ImagingConditionCode".
- Parameters:
code- the code for which to get the class name, ornull.- Returns:
- the ISO (preferred) or Java (fallback) class name, or
nullif the given code is null.
-
getCodeName
Returns the ISO name (if available) or the Java name (as a fallback) of the given enumeration or code list value. If the value has noUMLidentifier, then the programmatic name is used as a fallback.Examples:getCodeName(ParameterDirection.IN_OUT)returns"in/out".getCodeName(AxisDirection.NORTH)returns"north".getCodeName(TopicCategory.INLAND_WATERS)returns"inlandWaters".getCodeName(ImagingCondition.BLURRED_IMAGE)returns"blurredImage".
- Parameters:
code- the code for which to get the name, ornull.- Returns:
- the UML identifiers or programmatic name for the given code, or
nullif the given code is null. - See Also:
-
getCodeLabel
Returns a unlocalized title for the given enumeration or code list value. This method builds a title using heuristics rules, which should give reasonable results without the need of resource bundles. For better results, consider usinggetCodeTitle(CodeList)instead.The current heuristic implementation iterates over all code names, selects the longest one excluding the field name if possible, then makes a sentence from that name.
Examples:getCodeLabel(AxisDirection.NORTH)returns"North".getCodeLabel(TopicCategory.INLAND_WATERS)returns"Inland waters".getCodeLabel(ImagingCondition.BLURRED_IMAGE)returns"Blurred image".
- Parameters:
code- the code from which to get a title, ornull.- Returns:
- a unlocalized title for the given code, or
nullif the given code is null. - See Also:
-
getCodeTitle
Returns the title of the given enumeration or code list value. Title are usually much shorter than descriptions. English titles are often the same than the code labels.The code or enumeration value given in argument to this method can be retrieved from the returned title with the
forCodeTitle(CharSequence)method. See Substituting a free text by a code list in this class javadoc for more information.- Parameters:
code- the code for which to get the title, ornull.- Returns:
- the title, or
nullif the given code is null. - See Also:
-
getDescription
Returns the description of the given enumeration or code list value, ornullif none. For a description of the code list as a whole instead of a particular code, seegetDescription(Class).- Parameters:
code- the code for which to get the localized description, ornull.- Returns:
- the description, or
nullif none or if the given code is null. - See Also:
-
getDescription
Returns a description for the given class, ornullif none. This method can be used for GeoAPI interfaces orCodeList.- Parameters:
type- the GeoAPI interface or code list from which to get the description, ornull.- Returns:
- the description, or
nullif none or if the given type isnull. - See Also:
-
getDescription
Returns a description for the given property, ornullif none. The given type shall be a GeoAPI interface, and the given property shall be a UML identifier. If any of the input argument isnull, then this method returnsnull.- Parameters:
type- the GeoAPI interface from which to get the description of a property, ornull.property- the ISO name of the property for which to get the description, ornull.- Returns:
- the description, or
nullif none or if the given type or property name isnull.
-
getCodeValues
Returns all known values for the given type of code list. Note that the size of the returned array may growth between different invocations of this method, since users can add their own codes to an existing list.- Type Parameters:
T- the compile-time type given as thecodeTypeparameter.- Parameters:
codeType- the type of code list.- Returns:
- the list of values for the given code list, or an empty array if none.
- See Also:
-
forStandardName
Returns the Java type (usually a GeoAPI interface) for the given ISO name, ornullif none. The identifier argument shall be the value documented in theUML.identifier()annotation on the Java type.Examples:The package prefix (e.g.forStandardName("CI_Citation")returnsCitation.classforStandardName("CS_AxisDirection")returnsAxisDirection.class
"CI_"in"CI_Citation") can be omitted. The flexibility is provided for allowing transition to newer ISO standards, which are dropping the package prefixes. For example,"CS_AxisDirection"in ISO 19111:2007 has been renamed"AxisDirection"in ISO 19111:2018.Only identifiers for the stable part of GeoAPI or for some Apache SIS classes are recognized. This method does not handle the identifiers for interfaces in the
geoapi-pendingmodule.Future evolution: when a new ISO type does not yet have a corresponding GeoAPI interface, this method may temporarily return an Apache SIS class instead, until a future version can use the interface. For example,forStandardName("CI_Individual")returnsDefaultIndividual.classin Apache SIS versions that depend on GeoAPI 3.0, but the return type may be changed toIndividual.classwhen Apache SIS will be upgraded to GeoAPI 3.1.- Parameters:
identifier- the ISO UML identifier, ornull.- Returns:
- the GeoAPI interface, or
nullif the given identifier isnullor unknown.
-
forEnumName
Returns the enumeration value of the given type that matches the given name, ornullif none. This method is similar to the standardEnum.valueOf(…)method, except that this method is more tolerant on string comparisons:- Name comparisons are case-insensitive.
- Only letter and digit characters are compared.
Spaces and punctuation characters like
'_'and'-'are ignored.
null— it does not thrown an exception, unless the given class is not an enumeration.- Type Parameters:
T- the compile-time type given as theenumTypeparameter.- Parameters:
enumType- the type of enumeration.name- the name of the enumeration value to obtain, ornull.- Returns:
- a value matching the given name, or
nullif the name is null or if no matching enumeration is found. - Since:
- 0.5
- See Also:
-
forCodeName
public static <T extends CodeList<T>> T forCodeName(Class<T> codeType, String name, boolean canCreate) Returns the code of the given type that matches the given name, or optionally returns a new one if none match the name. This method performs the same work than the GeoAPICodeList.valueOf(…)method, except that this method is more tolerant on string comparisons when looking for an existing code:- Name comparisons are case-insensitive.
- Only letter and digit characters are compared.
Spaces and punctuation characters like
'_'and'-'are ignored.
canCreateargument istrue. Otherwise this method returnsnull.- Type Parameters:
T- the compile-time type given as thecodeTypeparameter.- Parameters:
codeType- the type of code list.name- the name of the code to obtain, ornull.canCreate-trueif this method is allowed to create new code.- Returns:
- a code matching the given name, or
nullif the name is null or if no matching code is found andcanCreateisfalse. - See Also:
-
forCodeTitle
Returns the code list or enumeration value for the given title, ornullif none. The current implementation performs the following choice:- If the given title is a value returned by a previous call to
getCodeTitle(CodeList), returns the code or enumeration value used for creating that title. - Otherwise returns
null.
- Parameters:
title- the title for which to get a code or enumeration value, ornull.- Returns:
- the code or enumeration value associated with the given title, or
null. - Since:
- 0.7
- See Also:
- If the given title is a value returned by a previous call to
-
toInternationalString
@OptionalCandidate public static InternationalString toInternationalString(Map<String, ?> properties, String prefix) throws IllegalArgumentExceptionReturns an international string for the values in the given properties map, ornullif none. This method is used when a property in aMapmay have many localized variants. For example, the given map may contains a"remarks"property defined by values associated to the"remarks_en"and"remarks_fr"keys, for English and French locales respectively.If the given map is
null, then this method returnsnull. Otherwise this method iterates over the entries having a key that starts with the specified prefix, followed by the'_'character. For each such key:- If the key is exactly equals to
prefix, selectsLocale.ROOT. - Otherwise the characters after
'_'are parsed as an ISO language and country code by theLocales.parse(String, int)method. Note that 3-letters codes are replaced by their 2-letters counterparts on a best effort basis. - The value for the decoded locale is added in the international string to be returned.
- Parameters:
properties- the map from which to get the string values for an international string, ornull.prefix- the prefix of keys to use for creating the international string.- Returns:
- the international string, or
nullif the given map is null or does not contain values associated to keys starting with the given prefix. - Throws:
IllegalArgumentException- if a key starts by the given prefix and:- The key suffix is an illegal
Localecode, - or the value associated to that key is a not a
CharSequence.
- The key suffix is an illegal
- Since:
- 0.4
- See Also:
- If the key is exactly equals to
-
toInternationalString
Returns the given characters sequence as an international string. If the given sequence is null or an instance ofInternationalString, then this method returns it unchanged. Otherwise, this method copies theInternationalString.toString()value in a newSimpleInternationalStringinstance and returns it.- Parameters:
string- the characters sequence to convert, ornull.- Returns:
- the given sequence as an international string, or
nullif the given sequence was null. - See Also:
-
toInternationalStrings
Returns the given array ofCharSequences as an array ofInternationalStrings. If the given array is null or an instance ofInternationalString[], then this method returns it unchanged. Otherwise a new array of typeInternationalString[]is created and every elements from the given array is copied or casted in the new array.If a defensive copy of the
stringsarray is wanted, then the caller needs to check if the returned array is the same instance than the one given in argument to this method.- Parameters:
strings- the characters sequences to convert, ornull.- Returns:
- the given array as an array of type
InternationalString[], ornullif the given array was null.
-
toString
Returns the given international string in the given locale, ornullif the given string is null. If the given locale isnull, then thei18ndefault locale is used.- Parameters:
i18n- the international string to get as a localized string, ornullif none.locale- the desired locale, ornullfor thei18ndefault locale.- Returns:
- the localized string, or
nullifi18nisnull. - Since:
- 0.8
-