B
- The builder subclass.public abstract class Builder<B extends Builder<B>> extends Object
IdentifiedObject
. Builder
s aim to make object creation
easier — they do not add any new functionality compared to ObjectFactory
.
Builder methods like addName(CharSequence)
and addIdentifier(String)
provide convenient ways
to fill the properties
map, which will be given to the ObjectFactory
methods at
IdentifiedObject
creation time. Creations happen when any createXXX(…)
method defined in
the builder subclasses is invoked.
This base class provides method for defining the following IdentifiedObject
properties:
Name
:Each IdentifiedObject
shall have a name, which can be specified by a call to any of theaddName(…)
methods defined in this class.Aliases
:Identified objects 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.Identifiers
:Identified objects can also have an arbitrary amount of identifiers, which are specified by the addIdentifier(…)
methods. Like names, more than one identifier can be added by invoking the method many time.Remarks
:Identified objects can have at most one remark, which is specified by the setRemarks(…)
method.
Builder
class:
Builder
will stay
active until they are specified again, because those information are typically shared by all components.createXXX(…)
method, because they are usually specific to a particular IdentifiedObject
instance.The two first names, which use the default namespace specified by the call toBuilder builder = new Builder(); builder.setCodespace (Citations.OGP, "EPSG") .addName ("Mercator (variant A)") // Defined in EPSG namespace. .addName ("Mercator (1SP)") // Defined in EPSG namespace. .addIdentifier("9804") // Defined in EPSG namespace. .addName (Citations.OGC, "Mercator_1SP") .addName (Citations.GEOTIFF, "CT_Mercator") .addIdentifier(Citations.GEOTIFF, "7") .setRemarks("The “Mercator (1SP)” method name was used prior to October 2010."); // At this point, the createXXX(…) method to invoke depends on the Builder subclass.
setCodeSpace(…)
,
will have the "EPSG"
scope. Since scopes are not shown
in string representation of names, the string representation
of the two first names will omit the "EPSG:"
prefix. However the string representation of the
two last names will be "OGC:Mercator_1SP"
and "GeoTIFF:CT_Mercator"
respectively.
The IdentificationObject
created by this example will have the following properties:
See
Name
:"Mercator (variant A)"
as a local name in"EPSG"
scope.Aliases
:"Mercator (1SP)"
as a local name in"EPSG"
scope,"OGC:Mercator_1SP"
and"GeoTIFF:CT_Mercator"
as scoped names.Identifiers
:"EPSG:9804"
and"GeoTIFF:7"
.Remarks
:"The “Mercator (1SP)” method name was used prior to October 2010."
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.
|
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. |
protected void |
onCreate(boolean cleanup)
Initializes/cleanups the
properties map before/after a createXXX(…) execution. |
B |
setCodeSpace(Citation authority,
String codespace)
Sets the
ReferenceIdentifier authority and code space. |
B |
setRemarks(CharSequence remarks)
Sets remarks as a
String or InternationalString instance. |
B |
setVersion(String version)
Sets the
ReferenceIdentifier 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)
public B setCodeSpace(Citation authority, String codespace)
ReferenceIdentifier
authority and code space. 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
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.public B setVersion(String version)
ReferenceIdentifier
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 ReferenceIdentifier
or
GenericName
object.
Lifetime:
the name and all aliases are cleared after a createXXX(…)
method has been invoked.
name
- The IdentifiedObject
name.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.OGP, "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
or
version
specified to this builder (if any), since the given
identifier already contains 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
or
version
specified to this builder (if any), since the given
generic name already contains 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
and version
information for creating the ReferenceIdentifier
object.
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
or
version
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 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, or null
if none.this
, for method call chaining.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 and remarks) 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–2014 The Apache Software Foundation. All rights reserved.