Class Builder<B extends Builder<B>>
- Type Parameters:
B- the builder subclass.
- Direct Known Subclasses:
ParameterBuilder
IdentifiedObject. This class provides convenience methods
for filling the properties map to be given to an ObjectFactory.
The main properties are:
- Name:
eachIdentifiedObjectshall have a name, which can be specified by a call to any of theaddName(…)methods defined in this class. - Aliases:
IdentifiedObjects can optionally have an arbitrary number of aliases, which are also specified by theaddName(…)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 theaddIdentifier(…)methods. Like names, more than one identifier can be added by invoking the method many time. - Code space:
IdentifiedObjectnames and identifiers can be local to a code space defined by an authority. Both the authority and code space can be specified by thesetCodeSpace(Citation, String)method, and usually (but not necessarily) apply to allIdentifierinstances. - Version:
Identifiers can optionally have a version specified by thesetVersion(String)method. The version usually (but not necessarily) applies to allIdentifierinstances. - Description:
Identifiers can optionally have a description specified by thesetDescription(CharSequence)method. The description applies only to the next identifier to create. - Remarks:
IdentifiedObjects can have at most one remark, which is specified by thecode setRemarks(…)method.
Namespaces and scopes
TheaddName(…) and addIdentifier(…) methods come in three flavors:
- The
addIdentifier(String)andaddName(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 thetoString()method. - The
addIdentifier(Citation, String)andaddName(Citation, CharSequence)methods use the givenCitationargument, ignoring any authority or code space information given to thisBuilder. The result is a scoped name or identifier, in which the code space information is shown by thetoString()method. - The
addIdentifier(Identifier),addName(Identifier)andaddName(GenericName)methods take the given object as-is. Any authority, code space, version or description information given to theBuilderare ignored.
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 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 theBuilder 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 acreateXXX(…)method, because those properties are usually specific to a particularIdentifiedObjectorIdentifierinstance.
Usage examples
SeeParameterBuilder 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 invokeonCreate(boolean)before and after usage ofpropertiesmap by the factory.
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
-
Field Summary
Fields -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedBuilder()Creates a new builder.protectedBuilder(IdentifiedObject object) Creates a new builder initialized to properties of the given object. -
Method Summary
Modifier and TypeMethodDescriptionaddIdentifier(String identifier) Adds anIdentifiedObjectidentifier given by aString.addIdentifier(Citation authority, String identifier) Adds anIdentifiedObjectidentifier in an alternative namespace.addIdentifier(ReferenceIdentifier identifier) Adds anIdentifiedObjectidentifier fully specified by the given identifier.addName(CharSequence name) Adds anIdentifiedObjectname given by aStringorInternationalString.addName(Citation authority, CharSequence name) Adds anIdentifiedObjectname in an alternative namespace.addName(ReferenceIdentifier name) Adds anIdentifiedObjectname fully specified by the given identifier.addName(GenericName name) Adds anIdentifiedObjectname fully specified by the given generic name.addNameAndIdentifier(Citation authority, IdentifiedObject object) Adds the non-deprecated names and identifiers from the given object for the specified authority.Adds all non-deprecated names and identifiers from the given object.protected voidonCreate(boolean cleanup) Initializes/cleanups thepropertiesmap before/after acreateXXX(…)execution.reidentify(Citation authority, String... replacements) Replaces the identifiers associated to the given authority by the given new identifiers.rename(Citation authority, CharSequence... replacements) Replaces the names associated to the given authority by the given new names.setCodeSpace(Citation authority, String codespace) Sets theIdentifierauthority and code space.setDeprecated(boolean deprecated) Sets whether the nextGenericNames,Identifiers orIdentifiedObjects to create shall be considered deprecated.setDescription(CharSequence description) Sets anIdentifierorIdentifiedObjectdescription.setRemarks(CharSequence remarks) Sets remarks as aStringorInternationalStringinstance.setVersion(String version) Sets theIdentifierversion of object definitions.
-
Field Details
-
properties
The properties to be given toObjectFactorymethods. 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:
-
-
Constructor Details
-
Builder
protected Builder()Creates a new builder. -
Builder
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, ornull.- Since:
- 0.6
-
-
Method Details
-
setCodeSpace
Sets theIdentifierauthority 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 isThis method is typically invoked only once, since a compound object often uses the same code space for all individual components."EPSG"for historical reasons.Condition: this method cannot be invoked after one or more names or identifiers have been added (by calls to the
addName(…)oraddIdentifier(…)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 tocreateXXX(…).Lifetime: this property is kept unchanged until this
setCodeSpace(…)method is invoked again.- Parameters:
authority- bibliographic reference to the authority defining the codes, ornullif none.codespace- theIdentifiedObjectcodespace, ornullfor inferring it from the authority.- Returns:
this, for method call chaining.- Throws:
IllegalStateException- ifaddName(…)oraddIdentifier(…)has been invoked at least once since builder construction or since the last call to acreateXXX(…)method.- See Also:
-
setVersion
Sets theIdentifierversion 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(…)oraddIdentifier(…)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 tocreateXXX(…).Lifetime: this property is kept unchanged until this
setVersion(…)method is invoked again.- Parameters:
version- the version of code definitions, ornullif none.- Returns:
this, for method call chaining.- Throws:
IllegalStateException- ifaddName(…)oraddIdentifier(…)has been invoked at least once since builder construction or since the last call to acreateXXX(…)method.
-
addName
Adds anIdentifiedObjectname given by aStringorInternationalString. The given string will be combined with the authority, code space and version information for creating theIdentifierorGenericNameobject.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. IfsetDeprecated(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- theIdentifiedObjectname as aStringorInternationalStringinstance.- Returns:
this, for method call chaining.
-
addName
Adds anIdentifiedObjectname 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,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."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, ornullif none.name- theIdentifiedObjectalias as a name in the namespace of the given authority.- Returns:
this, for method call chaining.- See Also:
-
addName
Adds anIdentifiedObjectname 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- theIdentifiedObjectname as an identifier.- Returns:
this, for method call chaining.
-
addName
Adds anIdentifiedObjectname 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- theIdentifiedObjectname as an identifier.- Returns:
this, for method call chaining.
-
addIdentifier
Adds anIdentifiedObjectidentifier given by aString. The given string will be combined with the authority, code space version and description information for creating theIdentifierobject.Deprecated identifiers
Some identifiers may exist for historical reasons but have their use discouraged. IfsetDeprecated(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- theIdentifiedObjectidentifier.- Returns:
this, for method call chaining.
-
addIdentifier
Adds anIdentifiedObjectidentifier in an alternative namespace. This method is typically invoked in complement toaddName(Citation, CharSequence).Lifetime: all identifiers are cleared after a
createXXX(…)method has been invoked.- Parameters:
authority- bibliographic reference to the authority defining the codes, ornullif none.identifier- theIdentifiedObjectidentifier as a code in the namespace of the given authority.- Returns:
this, for method call chaining.- See Also:
-
addIdentifier
Adds anIdentifiedObjectidentifier 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- theIdentifiedObjectidentifier.- Returns:
this, for method call chaining.
-
addNamesAndIdentifiers
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
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
Replaces the names associated to the given authority by the given new names. More specifically:- The first occurrence of a name associated to
authoritywill be replaced by a new name with the same authority and the local part defined byreplacements[0]. - The second occurrence of a name associated to
authoritywill be replaced by a new name with the same authority and the local part defined byreplacements[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 thereplacementsarray. - There are no more elements in the
replacementsarray, in which case all remaining names associated to the given authority in thisBuilderare removed.
- There are no more names associated to the given authority in this
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, ornullor an empty array for removing all names associated to the given authority.- Returns:
this, for method call chaining.- Since:
- 0.6
- The first occurrence of a name associated to
-
reidentify
Replaces the identifiers associated to the given authority by the given new identifiers. More specifically:- The first occurrence of an identifier associated to
authoritywill be replaced by a new identifier with the same authority and the code defined byreplacements[0]. - The second occurrence of an identifier associated to
authoritywill be replaced by a new identifier with the same authority and the local part defined byreplacements[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 thereplacementsarray. - There are no more elements in the
replacementsarray, in which case all remaining identifiers associated to the given authority in thisBuilderare removed.
- There are no more identifiers associated to the given authority in this
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, ornullor an empty array for removing all names associated to the given authority.- Returns:
this, for method call chaining.- Since:
- 0.8
- The first occurrence of an identifier associated to
-
setDescription
Sets anIdentifierorIdentifiedObjectdescription. Descriptions can be used in various contexts:- Before calls to
addIdentifier(String)oraddIdentifier(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 allIdentifiedObjectsupports description.
Lifetime: previous descriptions are discarded by calls to
setDescription(…). Descriptions are cleared after acreateXXX(…)method has been invoked.- Parameters:
description- the description as aStringorInternationalStringinstance, ornullif none.- Returns:
this, for method call chaining.- See Also:
- Before calls to
-
setRemarks
Sets remarks as aStringorInternationalStringinstance. Calls to this method overwrite any previous value.Lifetime: previous remarks are discarded by calls to
setRemarks(…). Remarks are cleared after acreateXXX(…)method has been invoked.- Parameters:
remarks- the remarks as aStringorInternationalStringinstance, ornullif none.- Returns:
this, for method call chaining.
-
setDeprecated
Sets whether the nextGenericNames,Identifiers orIdentifiedObjects 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-trueif the next names, identifiers and identified objects should be considered deprecated, orfalseotherwise.- Returns:
this, for method call chaining.- Since:
- 0.6
- See Also:
-
onCreate
protected void onCreate(boolean cleanup) Initializes/cleanups thepropertiesmap before/after acreateXXX(…)execution. Subclasses shall invoke this method in theircreateXXX(…)methods as below:
Ifpublic Foo createFoo() { final Foo foo; onCreate(false); try { foo = factory.createFoo(properties); } finally { onCreate(true); } return foo; }cleanupistrue, 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-falsewhen this method is invoked before object creation, andtruewhen this method is invoked after object creation.- See Also:
-