Class Builder<B extends Builder<B>>

java.lang.Object
org.apache.sis.referencing.Builder<B>
Type Parameters:
B - the builder subclass.
Direct Known Subclasses:
GeodeticObjectBuilder, ParameterBuilder

public abstract class Builder<B extends Builder<B>> extends Object
Base class of builders for various kinds of IdentifiedObject. This class provides convenience methods for filling the properties map to be given to an ObjectFactory. The main properties are:
  • Name:
    each IdentifiedObject shall have a name, which can be specified by a call to any of the addName(…) methods defined in this class.
  • Aliases:
    IdentifiedObjects can optionally have an arbitrary number of aliases, which are also specified by the addName(…) methods. Each call after the first one adds an alias.
  • Identifiers:
    IdentifiedObjects can also have an arbitrary number of identifiers, which are specified by any of the addIdentifier(…) methods. Like names, more than one identifier can be added by invoking the method many time.
  • Code space:
    IdentifiedObject names and identifiers can be local to a code space defined by an authority. Both the authority and code space can be specified by the setCodeSpace(Citation, String) method, and usually (but not necessarily) apply to all Identifier instances.
  • Version:
    Identifiers can optionally have a version specified by the setVersion(String) method. The version usually (but not necessarily) applies to all Identifier instances.
  • Description:
    Identifiers can optionally have a description specified by the setDescription(CharSequence) method. The description applies only to the next identifier to create.
  • Remarks:
    IdentifiedObjects can have at most one remark, which is specified by the code setRemarks(…) method.

Namespaces and scopes

The addName(…) and addIdentifier(…) methods come in three flavors:
  • The addIdentifier(String) and addName(CharSequence) methods combine the given argument with the above-cited authority, code space, version and description information. The result is a local name or identifier, in which the code space information is stored but not shown by the toString() method.
  • The addIdentifier(Citation, String) and addName(Citation, CharSequence) methods use the given Citation argument, ignoring any authority or code space information given to this Builder. The result is a scoped name or identifier, in which the code space information is shown by the toString() method.
  • The addIdentifier(Identifier), addName(Identifier) and addName(GenericName) methods take the given object as-is. Any authority, code space, version or description information given to the Builder are ignored.
Example: The EPSG database defines a projection named "Mercator (variant A)" (EPSG:9804). This projection was named "Mercator (1SP)" in older EPSG database versions. The same projection was also named "Mercator_1SP" by OGC some specifications. If we choose EPSG as our primary naming authority, then those three names can be declared as below: The toString() representation of those three names are "Mercator (variant A)", "Mercator (1SP)" (note the absence of "EPSG:" prefix, which is stored as the name scope but not shown) and "OGC:Mercator_1SP" respectively.

Builder property lifetimes

Some complex objects require the creation of many components. For example, constructing a Coordinate Reference System (CRS) may require constructing a coordinate system, a datum and an ellipsoid among other components. However, all those components often (but not necessarily) share the same authority, code space and version information. In order to simplify that common usage, two groups of properties have different lifetimes in the Builder class:
  • Authority, code space and version:
    Kept until they are specified again, because those properties are typically shared by all components.
  • Name, aliases, identifiers, description and remarks:
    Cleared after each call to a createXXX(…) method, because those properties are usually specific to a particular IdentifiedObject or Identifier instance.

Usage examples

See ParameterBuilder class javadoc for more examples with the Mercator projection parameters.

Note for subclass implementers

  • The type <B> shall be exactly the subclass type. For performance reasons, this is verified only if Java assertions are enabled.
  • All createXXX(…) methods shall invoke onCreate(boolean) before and after usage of properties map by the factory.
Example:
Since:
0.4
Version:
1.1
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final List<org.opengis.util.GenericName>
    A temporary list for aliases, before to assign them to the properties.
    private final List<org.opengis.referencing.ReferenceIdentifier>
    A temporary list for identifiers, before to assign them to the properties.
    private org.opengis.util.NameFactory
    The name factory, fetched when first needed.
    private org.opengis.util.NameSpace
    The codespace as a NameSpace object, or null if not yet created.
    protected final Map<String,Object>
    The properties to be given to ObjectFactory methods.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Creates a new builder.
    protected
    Builder(org.opengis.referencing.IdentifiedObject object)
    Creates a new builder initialized to properties of the given object.
  • Method Summary

    Modifier and Type
    Method
    Description
    addIdentifier(String identifier)
    Adds an IdentifiedObject identifier given by a String.
    addIdentifier(org.opengis.metadata.citation.Citation authority, String identifier)
    Adds an IdentifiedObject identifier in an alternative namespace.
    addIdentifier(org.opengis.referencing.ReferenceIdentifier identifier)
    Adds an IdentifiedObject identifier fully specified by the given identifier.
    Adds an IdentifiedObject name given by a String or InternationalString.
    addName(org.opengis.metadata.citation.Citation authority, CharSequence name)
    Adds an IdentifiedObject name in an alternative namespace.
    addName(org.opengis.referencing.ReferenceIdentifier name)
    Adds an IdentifiedObject name fully specified by the given identifier.
    addName(org.opengis.util.GenericName name)
    Adds an IdentifiedObject name fully specified by the given generic name.
    addNameAndIdentifier(org.opengis.metadata.citation.Citation authority, org.opengis.referencing.IdentifiedObject object)
    Adds the non-deprecated names and identifiers from the given object for the specified authority.
    addNamesAndIdentifiers(org.opengis.referencing.IdentifiedObject object)
    Adds all non-deprecated names and identifiers from the given object.
    private org.opengis.referencing.ReferenceIdentifier
    createIdentifier(org.opengis.metadata.citation.Citation authority, String identifier)
    Creates an identifier for the given authority.
    private org.opengis.referencing.ReferenceIdentifier
    createIdentifier(org.opengis.metadata.citation.Citation authority, String codeSpace, String identifier, String version)
    Creates an identifier for the given authority, code space and version.
    private org.opengis.util.GenericName
    Creates or returns an existing name for the given string in the current namespace.
    private org.opengis.util.GenericName
    createName(org.opengis.metadata.citation.Citation authority, CharSequence name)
    Creates or returns an existing name for the given string in the given namespace.
    private org.opengis.util.NameFactory
    Returns the name factory to use for creating namespaces and local names.
    private org.opengis.metadata.citation.Citation
    Returns the value of the first argument given by the last call to setCodeSpace(Citation, String), or null if none.
    private String
    Returns the value of the last argument given by the last call to setCodeSpace(Citation, String), or null if none.
    private org.opengis.util.InternationalString
    Returns the parameter description specified by the last call to setDescription(CharSequence), or null if none.
    private org.opengis.util.InternationalString
    Returns the remarks specified by the last call to setRemarks(CharSequence), or null if none.
    private String
    Returns the value given by the last call to setVersion(String), or null if none.
    private boolean
    Returns true if the deprecated flag is set to true.
    private static boolean
    isValid(Object object)
    Returns true if the given name or identifier is non-null and non-deprecated.
    protected void
    onCreate(boolean cleanup)
    Initializes/cleanups the properties map before/after a createXXX(…) execution.
    reidentify(org.opengis.metadata.citation.Citation authority, String... replacements)
    Replaces the identifiers associated to the given authority by the given new identifiers.
    rename(org.opengis.metadata.citation.Citation authority, CharSequence... replacements)
    Replaces the names associated to the given authority by the given new names.
    private B
    Returns this casted to <B>.
    setCodeSpace(org.opengis.metadata.citation.Citation authority, String codespace)
    Sets the Identifier authority and code space.
    setDeprecated(boolean deprecated)
    Sets whether the next GenericNames, Identifiers or IdentifiedObjects to create shall be considered deprecated.
    Sets an Identifier or IdentifiedObject description.
    private boolean
    setProperty(String key, Object value)
    Sets the property value for the given key, if a change is still possible.
    Sets remarks as a String or InternationalString instance.
    setVersion(String version)
    Sets the Identifier version of object definitions.
    private static org.opengis.referencing.ReferenceIdentifier
    toIdentifier(org.opengis.util.GenericName name)
    Converts the given name into an identifier.
    private static boolean
    Verifies that B in <B extends Builder<B> is the expected class.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • properties

      protected final Map<String,Object> properties
      The properties to be given to ObjectFactory methods. This map may contain values for the "name", "alias", "identifiers" and "remarks" keys. Subclasses may add other entries like "domainOfValidity" and "scope" keys.

      See Notes for subclass implementers in class javadoc for usage conditions.

      See Also:
    • aliases

      private final List<org.opengis.util.GenericName> aliases
      A temporary list for aliases, before to assign them to the properties.
    • identifiers

      private final List<org.opengis.referencing.ReferenceIdentifier> identifiers
      A temporary list for identifiers, before to assign them to the properties.
    • namespace

      private transient org.opengis.util.NameSpace namespace
      The codespace as a NameSpace object, or null if not yet created. This object is built from the "codespace" value when first needed.
    • nameFactory

      private transient org.opengis.util.NameFactory nameFactory
      The name factory, fetched when first needed.
      See Also:
  • Constructor Details

    • Builder

      protected Builder()
      Creates a new builder.
    • Builder

      protected Builder(org.opengis.referencing.IdentifiedObject object)
      Creates a new builder initialized to properties of the given object. The properties recognized by this constructor are documented here.
      Parameters:
      object - the identified object from which to inherit properties, or null.
      Since:
      0.6
  • Method Details

    • verifyParameterizedType

      private static boolean verifyParameterizedType(Class<?> expected)
      Verifies that B in <B extends Builder<B> is the expected class. This method is for assertion purposes only.
    • self

      private B self()
      Returns this casted to <B>. The cast is valid if the assertion performed at construction time passes. Since the <B> type is hard-coded in the source code, if the JUnit test passes then the cast should always be valid for all instances of the same builder class.
    • factory

      private org.opengis.util.NameFactory factory()
      Returns the name factory to use for creating namespaces and local names. The factory will be fetched when first needed, and while not change anymore for the rest of this Builder lifetime.
    • createName

      private org.opengis.util.GenericName createName(CharSequence name)
      Creates or returns an existing name for the given string in the current namespace. The namespace may be cleared at anytime by a call to setCodeSpace(Citation, String).
    • createName

      private org.opengis.util.GenericName createName(org.opengis.metadata.citation.Citation authority, CharSequence name)
      Creates or returns an existing name for the given string in the given namespace.
    • createIdentifier

      private org.opengis.referencing.ReferenceIdentifier createIdentifier(org.opengis.metadata.citation.Citation authority, String identifier)
      Creates an identifier for the given authority. If and only if the given authority is the default one, then the new identifier will also contain the user supplied code space and version (if any). The new identifier will be marked as deprecated if isDeprecated() returns true.
    • createIdentifier

      private org.opengis.referencing.ReferenceIdentifier createIdentifier(org.opengis.metadata.citation.Citation authority, String codeSpace, String identifier, String version)
      Creates an identifier for the given authority, code space and version. The new identifier will be marked as deprecated if isDeprecated() returns true.
    • toIdentifier

      private static org.opengis.referencing.ReferenceIdentifier toIdentifier(org.opengis.util.GenericName name)
      Converts the given name into an identifier. Note that NamedIdentifier implements both GenericName and Identifier interfaces.
    • setProperty

      private boolean setProperty(String key, Object value) throws IllegalStateException
      Sets the property value for the given key, if a change is still possible. The check for change permission is needed for all keys defined in the Identifier interface. This check is not needed for other keys, so callers do not need to invoke this method for other keys.
      Parameters:
      key - the key of the property to set.
      value - the value to set.
      Returns:
      true if the property changed as a result of this method call.
      Throws:
      IllegalStateException - if a new value is specified in a phase where the value cannot be changed.
    • getAuthority

      private org.opengis.metadata.citation.Citation getAuthority()
      Returns the value of the first argument given by the last call to setCodeSpace(Citation, String), or null if none. The default value is null.
      Returns:
      the citation specified by the last call to setCodeSpace(…), or null if none.
      Since:
      0.6
    • getCodeSpace

      private String getCodeSpace()
      Returns the value of the last argument given by the last call to setCodeSpace(Citation, String), or null if none. The default value is null.
      Returns:
      the string specified by the last call to setCodeSpace(…), or null if none.
      Since:
      0.6
    • setCodeSpace

      public B setCodeSpace(org.opengis.metadata.citation.Citation authority, String codespace)
      Sets the Identifier authority and code space. The code space is often the authority's abbreviation, but not necessarily.
      Example: Coordinate Reference System (CRS) objects identified by codes from the EPSG database are maintained by the International Association of Oil & Gas producers (IOGP) authority, but the code space is "EPSG" for historical reasons.
      This method is typically invoked only once, since a compound object often uses the same code space for all individual components.

      Condition: this method cannot be invoked after one or more names or identifiers have been added (by calls to the addName(…) or addIdentifier(…) methods) for the next object to create. This method can be invoked again after the name, aliases and identifiers have been cleared by a call to createXXX(…).

      Lifetime: this property is kept unchanged until this setCodeSpace(…) method is invoked again.

      Parameters:
      authority - bibliographic reference to the authority defining the codes, or null if none.
      codespace - the IdentifiedObject codespace, or null for inferring it from the authority.
      Returns:
      this, for method call chaining.
      Throws:
      IllegalStateException - if addName(…) or addIdentifier(…) has been invoked at least once since builder construction or since the last call to a createXXX(…) method.
      See Also:
    • getVersion

      private String getVersion()
      Returns the value given by the last call to setVersion(String), or null if none. The default value is null.
      Returns:
      the value specified by the last call to setVersion(…), or null if none.
      Since:
      0.6
    • setVersion

      public B setVersion(String version)
      Sets the Identifier version of object definitions. This method is typically invoked only once, since a compound object often uses the same version for all individual components.

      Condition: this method cannot be invoked after one or more names or identifiers have been added (by calls to the addName(…) or addIdentifier(…) methods) for the next object to create. This method can be invoked again after the name, aliases and identifiers have been cleared by a call to createXXX(…).

      Lifetime: this property is kept unchanged until this setVersion(…) method is invoked again.

      Parameters:
      version - the version of code definitions, or null if none.
      Returns:
      this, for method call chaining.
      Throws:
      IllegalStateException - if addName(…) or addIdentifier(…) has been invoked at least once since builder construction or since the last call to a createXXX(…) method.
    • addName

      public B addName(CharSequence name)
      Adds an IdentifiedObject name given by a String or InternationalString. The given string will be combined with the authority, code space and version information for creating the Identifier or GenericName object.

      Name and aliases

      This method can be invoked many times. The first invocation sets the primary name, and all subsequent invocations add an alias.

      Deprecated names

      Some names may exist for historical reasons but have their use discouraged. If setDeprecated(true) has been invoked, then this method creates a deprecated alias with the current remarks. The remark should suggest a replacement, for example with a sentence like "Superseded by <new-name>".

      Note that deprecated names are always added as aliases, never as the primary name of an identified object.

      Lifetime: the name and all aliases are cleared after a createXXX(…) method has been invoked.

      Parameters:
      name - the IdentifiedObject name as a String or InternationalString instance.
      Returns:
      this, for method call chaining.
    • addName

      public B addName(org.opengis.metadata.citation.Citation authority, CharSequence name)
      Adds an IdentifiedObject name in an alternative namespace. This method is typically invoked for aliases defined after the primary name.
      Example: The "Longitude of natural origin" parameter defined by EPSG is named differently by OGC and GeoTIFF. Those alternative names can be defined as below: In this example, "central_meridian" will be the tip and "OGC" will be the head of the first alias.

      Lifetime: the name and all aliases are cleared after a createXXX(…) method has been invoked.

      Parameters:
      authority - bibliographic reference to the authority defining the codes, or null if none.
      name - the IdentifiedObject alias as a name in the namespace of the given authority.
      Returns:
      this, for method call chaining.
      See Also:
    • addName

      public B addName(org.opengis.referencing.ReferenceIdentifier name)
      Adds an IdentifiedObject name fully specified by the given identifier. This method ignores the authority, code space, version and description specified to this builder (if any), since the given identifier may already contain those information.

      Name and aliases

      This method can be invoked many times. The first invocation sets the primary name to the given value, and all subsequent invocations add an alias.

      Lifetime: the name and all aliases are cleared after a createXXX(…) method has been invoked.

      Parameters:
      name - the IdentifiedObject name as an identifier.
      Returns:
      this, for method call chaining.
    • addName

      public B addName(org.opengis.util.GenericName name)
      Adds an IdentifiedObject name fully specified by the given generic name. This method ignores the authority, code space, version and description specified to this builder (if any), since the given generic name may already contain those information.

      Name and aliases

      This method can be invoked many times. The first invocation sets the primary name to the given value, and all subsequent invocations add an alias.

      Lifetime: the name and all aliases are cleared after a createXXX(…) method has been invoked.

      Parameters:
      name - the IdentifiedObject name as an identifier.
      Returns:
      this, for method call chaining.
    • addIdentifier

      public B addIdentifier(String identifier)
      Adds an IdentifiedObject identifier given by a String. The given string will be combined with the authority, code space version and description information for creating the Identifier object.

      Deprecated identifiers

      Some identifiers may exist for historical reasons but have their use discouraged. If setDeprecated(true) has been invoked, then this method creates a deprecated identifier with the current remarks. The remark should suggest a replacement, for example with a sentence like "Superseded by <new-code>".

      Lifetime: all identifiers are cleared after a createXXX(…) method has been invoked.

      Parameters:
      identifier - the IdentifiedObject identifier.
      Returns:
      this, for method call chaining.
    • addIdentifier

      public B addIdentifier(org.opengis.metadata.citation.Citation authority, String identifier)
      Adds an IdentifiedObject identifier in an alternative namespace. This method is typically invoked in complement to addName(Citation, CharSequence).

      Lifetime: all identifiers are cleared after a createXXX(…) method has been invoked.

      Parameters:
      authority - bibliographic reference to the authority defining the codes, or null if none.
      identifier - the IdentifiedObject identifier as a code in the namespace of the given authority.
      Returns:
      this, for method call chaining.
      See Also:
    • addIdentifier

      public B addIdentifier(org.opengis.referencing.ReferenceIdentifier identifier)
      Adds an IdentifiedObject identifier fully specified by the given identifier. This method ignores the authority, code space, version and description specified to this builder (if any), since the given identifier already contains those information.

      Lifetime: all identifiers are cleared after a createXXX(…) method has been invoked.

      Parameters:
      identifier - the IdentifiedObject identifier.
      Returns:
      this, for method call chaining.
    • isValid

      private static boolean isValid(Object object)
      Returns true if the given name or identifier is non-null and non-deprecated.
      See Also:
    • addNamesAndIdentifiers

      public B addNamesAndIdentifiers(org.opengis.referencing.IdentifiedObject object)
      Adds all non-deprecated names and identifiers from the given object. Other properties like description and remarks are ignored.

      This is a convenience method for using an existing object as a template, before to modify some names by calls to rename(Citation, CharSequence[]).

      Parameters:
      object - the object from which to copy the names and identifiers.
      Returns:
      this, for method call chaining.
      Since:
      0.6
    • addNameAndIdentifier

      public B addNameAndIdentifier(org.opengis.metadata.citation.Citation authority, org.opengis.referencing.IdentifiedObject object)
      Adds the non-deprecated names and identifiers from the given object for the specified authority. This is a convenience method for reusing name and identifier already declared for another object.
      Parameters:
      authority - the authority for which to copy the name and identifier.
      object - the object from which to copy the name and identifier.
      Returns:
      this, for method call chaining.
      Since:
      1.1
    • rename

      public B rename(org.opengis.metadata.citation.Citation authority, CharSequence... replacements)
      Replaces the names associated to the given authority by the given new names. More specifically:
      • The first occurrence of a name associated to authority will be replaced by a new name with the same authority and the local part defined by replacements[0].
      • The second occurrence of a name associated to authority will be replaced by a new name with the same authority and the local part defined by replacements[1].
      • etc. until one of the following conditions is met:
        • There are no more names associated to the given authority in this Builder, in which case new names are inserted for all remaining elements in the replacements array.
        • There are no more elements in the replacements array, in which case all remaining names associated to the given authority in this Builder are removed.
      This method could also be understood as a setNames(Citation, ...) method, except that it modifies only the names associated to the given authority and preserves the same order than previous names.
      Parameters:
      authority - the authority of the names to replaces.
      replacements - the new local parts for the names to replace, or null or an empty array for removing all names associated to the given authority.
      Returns:
      this, for method call chaining.
      Since:
      0.6
    • reidentify

      public B reidentify(org.opengis.metadata.citation.Citation authority, String... replacements)
      Replaces the identifiers associated to the given authority by the given new identifiers. More specifically:
      • The first occurrence of an identifier associated to authority will be replaced by a new identifier with the same authority and the code defined by replacements[0].
      • The second occurrence of an identifier associated to authority will be replaced by a new identifier with the same authority and the local part defined by replacements[1].
      • etc. until one of the following conditions is met:
        • There are no more identifiers associated to the given authority in this Builder, in which case new identifiers are inserted for all remaining elements in the replacements array.
        • There are no more elements in the replacements array, in which case all remaining identifiers associated to the given authority in this Builder are removed.
      This method could also be understood as a setIdentifiers(Citation, ...) method, except that it modifies only the identifiers associated to the given authority and preserves the same order than previous identifiers.
      Parameters:
      authority - the authority of the names to replaces.
      replacements - the new local parts for the names to replace, or null or an empty array for removing all names associated to the given authority.
      Returns:
      this, for method call chaining.
      Since:
      0.8
    • getDescription

      private org.opengis.util.InternationalString getDescription()
      Returns the parameter description specified by the last call to setDescription(CharSequence), or null if none.
    • setDescription

      public B setDescription(CharSequence description)
      Sets an Identifier or IdentifiedObject description. Descriptions can be used in various contexts:
      • Before calls to addIdentifier(String) or addIdentifier(Citation, String) for specifying a natural language description of the meaning of the code value.
        Example: setDescription("World Geodetic System 1984").addIdentifier("4326")
      • Before calls to a createXXX(…) method for providing a narrative explanation of the role of the object. Not all IdentifiedObject supports description.
      Calls to this method overwrite any previous value.

      Lifetime: previous descriptions are discarded by calls to setDescription(…). Descriptions are cleared after a createXXX(…) method has been invoked.

      Parameters:
      description - the description as a String or InternationalString instance, or null if none.
      Returns:
      this, for method call chaining.
      See Also:
    • getRemarks

      private org.opengis.util.InternationalString getRemarks()
      Returns the remarks specified by the last call to setRemarks(CharSequence), or null if none.
    • setRemarks

      public B setRemarks(CharSequence remarks)
      Sets remarks as a String or InternationalString instance. Calls to this method overwrite any previous value.

      Lifetime: previous remarks are discarded by calls to setRemarks(…). Remarks are cleared after a createXXX(…) method has been invoked.

      Parameters:
      remarks - the remarks as a String or InternationalString instance, or null if none.
      Returns:
      this, for method call chaining.
    • isDeprecated

      private boolean isDeprecated()
      Returns true if the deprecated flag is set to true.
    • setDeprecated

      public B setDeprecated(boolean deprecated)
      Sets whether the next GenericNames, Identifiers or IdentifiedObjects to create shall be considered deprecated. Deprecated objects exist in some authority factories like the EPSG database.

      Lifetime: Deprecation status is cleared after a createXXX(…) method has been invoked.

      Parameters:
      deprecated - true if the next names, identifiers and identified objects should be considered deprecated, or false otherwise.
      Returns:
      this, for method call chaining.
      Since:
      0.6
      See Also:
    • onCreate

      protected void onCreate(boolean cleanup)
      Initializes/cleanups the properties map before/after a createXXX(…) execution. Subclasses shall invoke this method in their createXXX(…) methods as below: If cleanup is true, then this method clears the identification information (name, aliases, identifiers, description, remarks and deprecation status) for preparing the builder to the construction of another object. The authority, codespace and version properties are not cleared by this method.
      Parameters:
      cleanup - false when this method is invoked before object creation, and true when this method is invoked after object creation.
      See Also: