Class Builder<B extends Builder<B>>

  • Type Parameters:
    B - the builder subclass.
    Direct Known Subclasses:
    Parameter­Builder

    public abstract class Builder<B extends Builder<B>>
    extends Object
    Base class of builders for various kind of Identified­Object. This class provides convenience methods for filling the properties map to be given to an Object­Factory. The main properties are:
    • Name:
      each Identified­Object shall have a name, which can be specified by a call to any of the add­Name(…) methods defined in this class.
    • Aliases:
      Identified­Objects can optionally have an arbitrary amount of aliases, which are also specified by the add­Name(…) methods. Each call after the first one adds an alias.
    • Identifiers:
      Identified­Objects can also have an arbitrary amount of identifiers, which are specified by any of the add­Identifier(…) methods. Like names, more than one identifier can be added by invoking the method many time.
    • Code space:
      Identified­Object 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 set­Code­Space(Citation, String) method, and usually (but not necessarily) apply to all Identifier instances.
    • Version:
      Identifiers can optionally have a version specified by the set­Version(String) method. The version usually (but not necessarily) applies to all Identifier instances.
    • Description:
      Identifiers can optionally have a description specified by the set­Description(Char­Sequence) method. The description applies only to the next identifier to create.
    • Remarks:
      Identified­Objects can have at most one remark, which is specified by the code set­Remarks(…) method.
    Namespaces and scopes
    The add­Name(…) and add­Identifier(…) methods come in three flavors:
    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:
    builder.setCodespace (Citations.EPSG, "EPSG")
           .addName("Mercator (variant A)")
           .addName("Mercator (1SP)")
           .addName(Citations.OGC, "Mercator_1SP")
    The to­String() 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 create­XXX(…) method, because those properties are usually specific to a particular Identified­Object or Identifier instance.
    Usage examples
    See Parameter­Builder 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 create­XXX(…) methods shall invoke on­Create(boolean) before and after usage of properties map by the factory.
    Example:
    public class MyBuilder extends Builder<MyBuilder> {
        public Foo createFoo() {
            onCreate(false);
            Foo foo = factory.createFoo(properties);
            onCreate(true);
            return foo;
        }
    }
    Since:
    0.4

    Defined in the sis-referencing module

    • Constructor Detail

      • Builder

        protected Builder()
        Creates a new builder.
      • Builder

        protected Builder​(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 Detail

      • setCodeSpace

        public B setCodeSpace​(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 can not be invoked after one or more names or identifiers have been added (by calls to the add­Name(…) or add­Identifier(…) 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 create­XXX(…).

        Lifetime: this property is kept unchanged until this set­Code­Space(…) method is invoked again.

        Parameters:
        authority - bibliographic reference to the authority defining the codes, or null if none.
        codespace - the Identified­Object codespace, or null for inferring it from the authority.
        Returns:
        this, for method call chaining.
        Throws:
        Illegal­State­Exception - if add­Name(…) or add­Identifier(…) has been invoked at least once since builder construction or since the last call to a create­XXX(…) method.
        See Also:
        Immutable­Identifier​.get­Authority(), Immutable­Identifier​.get­Code­Space()
      • 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 can not be invoked after one or more names or identifiers have been added (by calls to the add­Name(…) or add­Identifier(…) 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 create­XXX(…).

        Lifetime: this property is kept unchanged until this set­Version(…) method is invoked again.

        Parameters:
        version - the version of code definitions, or null if none.
        Returns:
        this, for method call chaining.
        Throws:
        Illegal­State­Exception - if add­Name(…) or add­Identifier(…) has been invoked at least once since builder construction or since the last call to a create­XXX(…) method.
      • addName

        public B addName​(CharSequence name)
        Adds an Identified­Object name given by a String or International­String. The given string will be combined with the authority, code space and version information for creating the Identifier or Generic­Name 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 set­Deprecated(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 create­XXX(…) method has been invoked.

        Parameters:
        name - the Identified­Object name as a String or International­String instance.
        Returns:
        this, for method call chaining.
      • addName

        public B addName​(Citation authority,
                         CharSequence name)
        Adds an Identified­Object 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:
        builder.setCodespace(Citations.EPSG, "EPSG")          // Sets the default namespace to "EPSG".
               .addName("Longitude of natural origin")        // Primary name in builder default namespace.
               .addName(Citations.OGC, "central_meridian")    // First alias in "OGC" namespace.
               .addName(Citations.GEOTIFF, "NatOriginLong");  // Second alias in "GeoTIFF" namespace.
        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 create­XXX(…) method has been invoked.

        Parameters:
        authority - bibliographic reference to the authority defining the codes, or null if none.
        name - the Identified­Object alias as a name in the namespace of the given authority.
        Returns:
        this, for method call chaining.
        See Also:
        add­Identifier(Citation, String)
      • addName

        public B addName​(ReferenceIdentifier name)
        Adds an Identified­Object 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 create­XXX(…) method has been invoked.

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

        public B addName​(GenericName name)
        Adds an Identified­Object 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 create­XXX(…) method has been invoked.

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

        public B addIdentifier​(String identifier)
        Adds an Identified­Object 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 set­Deprecated(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 create­XXX(…) method has been invoked.

        Parameters:
        identifier - the Identified­Object identifier.
        Returns:
        this, for method call chaining.
      • addIdentifier

        public B addIdentifier​(Citation authority,
                               String identifier)
        Adds an Identified­Object identifier in an alternative namespace. This method is typically invoked in complement to add­Name(Citation, Char­Sequence).

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

        Parameters:
        authority - bibliographic reference to the authority defining the codes, or null if none.
        identifier - the Identified­Object identifier as a code in the namespace of the given authority.
        Returns:
        this, for method call chaining.
        See Also:
        add­Name(Citation, Char­Sequence)
      • addIdentifier

        public B addIdentifier​(ReferenceIdentifier identifier)
        Adds an Identified­Object 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 create­XXX(…) method has been invoked.

        Parameters:
        identifier - the Identified­Object identifier.
        Returns:
        this, for method call chaining.
      • addNamesAndIdentifiers

        public B addNamesAndIdentifiers​(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, Char­Sequence[]).

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

        public B rename​(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 is no more name associated to the given authority in this Builder, in which case new names are inserted for all remaining elements in the replacements array.
          • There is 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 set­Names(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​(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 is no more identifier associated to the given authority in this Builder, in which case new identifiers are inserted for all remaining elements in the replacements array.
          • There is 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 set­Identifiers(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
      • setDescription

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

        Lifetime: previous descriptions are discarded by calls to set­Description(…). Descriptions are cleared after a create­XXX(…) method has been invoked.

        Parameters:
        description - the description as a String or International­String instance, or null if none.
        Returns:
        this, for method call chaining.
        See Also:
        Immutable­Identifier​.get­Description()
      • setRemarks

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

        Lifetime: previous remarks are discarded by calls to set­Remarks(…). Remarks are cleared after a create­XXX(…) method has been invoked.

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

        public B setDeprecated​(boolean deprecated)
        Sets whether the next Identifier or Identified­Objects to create shall be considered deprecated. Deprecated objects exist in some authority factories like the EPSG database.

        Note that this method does not apply to name and identifiers, which have their own add­Deprecated­Foo(…) methods.

        Lifetime: Deprecation status is cleared after a create­XXX(…) 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:
        Abstract­Identified­Object​.is­Deprecated()
      • onCreate

        protected void onCreate​(boolean cleanup)
        Initializes/cleanups the properties map before/after a create­XXX(…) execution. Subclasses shall invoke this method in their create­XXX(…) methods as below:
        public Foo createFoo() {
            final Foo foo;
            onCreate(false);
            try {
                foo = factory.createFoo(properties);
            } finally {
                onCreate(true);
            }
            return foo;
        }
        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 an other 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:
        properties