B
- The builder subclass.public abstract class Builder<B extends Builder<B>> extends Object
IdentifiedObject
. This class provides convenience methods
for filling the properties
map to be given to an ObjectFactory
.
The main properties are:
IdentifiedObject
shall have a name, which can be specified by a call to any of the
addName(…)
methods defined in this class.IdentifiedObject
s can optionally have an arbitrary amount of aliases, which are also specified
by the addName(…)
methods. Each call after the first one adds an alias.IdentifiedObject
s can also have an arbitrary amount 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.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.Identifier
s can optionally have a version specified by the setVersion(String)
method.
The version usually (but not necessarily) applies to all Identifier
instances.Identifier
s can optionally have a description specified by the setDescription(CharSequence)
method.
The description applies only to the next identifier to create.IdentifiedObject
s can have at most one remark, which is specified by the
code setRemarks(…)
method.addName(…)
and addIdentifier(…)
methods come in three flavors:
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.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.#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.Mercator_1SP
" by OGC some specifications.
If we choose EPSG as our primary naming authority, then those three names can be declared as below:
Thebuilder.setCodespace (Citations.EPSG, "EPSG") .addName("Mercator (variant A)") .addName("Mercator (1SP)") .addName(Citations.OGC, "Mercator_1SP")
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
class:
createXXX(…)
method, because those properties are usually specific
to a particular IdentifiedObject
or Identifier
instance.
ParameterBuilder
class javadoc for more examples with the
Mercator projection parameters.
<B>
shall be exactly the subclass type.
For performance reasons, this is verified only if Java assertions are enabled.createXXX(…)
methods shall invoke onCreate(boolean)
before and after
usage of properties
map by the factory.public class MyBuilder extends Builder<MyBuilder> { public Foo createFoo() { onCreate(false); Foo foo = factory.createFoo(properties); onCreate(true); return foo; } }
Defined in the sis-referencing
module
Modifier and Type | Field and Description |
---|---|
protected Map<String,Object> |
properties
The properties to be given to
ObjectFactory methods. |
Modifier | Constructor and Description |
---|---|
protected |
Builder()
Creates a new builder.
|
protected |
Builder(IdentifiedObject object)
Creates a new builder initialized to properties of the given object.
|
Modifier and Type | Method and Description |
---|---|
B |
addIdentifier(Citation authority,
String identifier)
Adds an
IdentifiedObject identifier in an alternative namespace. |
B |
addIdentifier(ReferenceIdentifier identifier)
Adds an
IdentifiedObject identifier fully specified by the given identifier. |
B |
addIdentifier(String identifier)
Adds an
IdentifiedObject identifier given by a String . |
B |
addName(CharSequence name)
Adds an
IdentifiedObject name given by a String or InternationalString . |
B |
addName(Citation authority,
CharSequence name)
Adds an
IdentifiedObject name in an alternative namespace. |
B |
addName(GenericName name)
Adds an
IdentifiedObject name fully specified by the given generic name. |
B |
addName(ReferenceIdentifier name)
Adds an
IdentifiedObject name fully specified by the given identifier. |
B |
addNamesAndIdentifiers(IdentifiedObject object)
Adds all non-deprecated names and identifiers from the given object.
|
protected void |
onCreate(boolean cleanup)
Initializes/cleanups the
properties map before/after a createXXX(…) execution. |
B |
rename(Citation authority,
CharSequence... replacements)
Replaces the names associated to the given authority by the given new names.
|
B |
setCodeSpace(Citation authority,
String codespace)
Sets the
Identifier authority and code space. |
B |
setDeprecated(boolean deprecated)
Sets whether the next
Identifier or IdentifiedObject s to create shall be considered deprecated. |
B |
setDescription(CharSequence description)
Sets an
Identifier or IdentifiedObject description. |
B |
setRemarks(CharSequence remarks)
Sets remarks as a
String or InternationalString instance. |
B |
setVersion(String version)
Sets the
Identifier version of object definitions. |
protected final Map<String,Object> properties
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 implementors in class javadoc for usage conditions.
onCreate(boolean)
protected Builder()
protected Builder(IdentifiedObject object)
object
- The identified object from which to inherit properties, or null
.public B setCodeSpace(Citation authority, String codespace)
Identifier
authority and code space.
The code space is often the authority's abbreviation, but not necessarily.
"EPSG"
for historical reasons.Condition:
this method can not 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.
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.this
, for method call chaining.IllegalStateException
- if addName(…)
or addIdentifier(…)
has been invoked at least
once since builder construction or since the last call to a createXXX(…)
method.ImmutableIdentifier.getAuthority()
,
ImmutableIdentifier.getCodeSpace()
public B setVersion(String version)
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
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.
version
- The version of code definitions, or null
if none.this
, for method call chaining.IllegalStateException
- if addName(…)
or addIdentifier(…)
has been invoked at least
once since builder construction or since the last call to a createXXX(…)
method.public B addName(CharSequence name)
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.
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.
name
- The IdentifiedObject
name as a String
or InternationalString
instance.this
, for method call chaining.public B addName(Citation authority, CharSequence name)
IdentifiedObject
name in an alternative namespace. This method is typically invoked for
aliases defined after the primary name.
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.
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.this
, for method call chaining.addIdentifier(Citation, String)
public B addName(ReferenceIdentifier name)
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.
Lifetime:
the name and all aliases are cleared after a createXXX(…)
method has been invoked.
name
- The IdentifiedObject
name as an identifier.this
, for method call chaining.public B addName(GenericName name)
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.
Lifetime:
the name and all aliases are cleared after a createXXX(…)
method has been invoked.
name
- The IdentifiedObject
name as an identifier.this
, for method call chaining.public B addIdentifier(String identifier)
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.
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.
identifier
- The IdentifiedObject
identifier.this
, for method call chaining.public B addIdentifier(Citation authority, String identifier)
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.
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.this
, for method call chaining.addName(Citation, CharSequence)
public B addIdentifier(ReferenceIdentifier identifier)
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.
identifier
- The IdentifiedObject
identifier.this
, for method call chaining.public B addNamesAndIdentifiers(IdentifiedObject object)
This is a convenience method for using an existing object as a template, before to modify
some names by calls to rename(Citation, CharSequence[])
.
object
- The object from which to copy the references to names and identifiers.this
, for method call chaining.public B rename(Citation authority, CharSequence... replacements)
authority
will be replaced by a new name
with the same authority and the local part defined by replacements[0]
.authority
will be replaced by a new name
with the same authority and the local part defined by replacements[1]
.Builder
, in which case
new names are inserted for all remaining elements in the replacements
array.replacements
array, in which case all remaining
names associated to the given authority in this Builder
are removed.authority
- The authority of the names to replaces.replacements
- The new local parts for the names to replace,
or null
for removing all identifiers associated to the given authority.this
, for method call chaining.public B setDescription(CharSequence description)
Identifier
or IdentifiedObject
description.
Descriptions can be used in various contexts:
addIdentifier(String)
or addIdentifier(Citation, String)
for specifying a natural language description of the meaning of the code value.
setDescription("World Geodetic System 1984").addIdentifier("4326")
createXXX(…)
method for providing a narrative explanation
of the role of the object. Not all IdentifiedObject
supports description.Lifetime:
previous descriptions are discarded by calls to setDescription(…)
.
Descriptions are cleared after a createXXX(…)
method has been invoked.
description
- The description as a String
or InternationalString
instance, or null
if none.this
, for method call chaining.ImmutableIdentifier.getDescription()
public B setRemarks(CharSequence remarks)
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.
remarks
- The remarks as a String
or InternationalString
instance, or null
if none.this
, for method call chaining.public B setDeprecated(boolean deprecated)
Identifier
or IdentifiedObject
s 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
addDeprecatedFoo(…)
methods.
Lifetime:
Deprecation status is cleared after a createXXX(…)
method has been invoked.
deprecated
- true
if the next names, identifiers and identified objects should be
considered deprecated, or false
otherwise.this
, for method call chaining.AbstractIdentifiedObject.isDeprecated()
protected void onCreate(boolean cleanup)
properties
map before/after a createXXX(…)
execution.
Subclasses shall invoke this method in their createXXX(…)
methods as below:
Ifpublic Foo createFoo() { final Foo foo; onCreate(false); try { foo = factory.createFoo(properties); } finally { onCreate(true); } return foo; }
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.cleanup
- false
when this method is invoked before object creation, and
true
when this method is invoked after object creation.properties
Copyright © 2010–2015 The Apache Software Foundation. All rights reserved.