org.apache.sis.feature.builder

Class AttributeTypeBuilder<V>

Object

TypeBuilder

PropertyTypeBuilder

AttributeTypeBuilder<V>

Type Parameters:

V - the class of attribute values.

All Implemented Interfaces:

Localized

public final class AttributeTypeBuilder<V>
extends PropertyTypeBuilder

Describes one Attribute­Type which will be part of the feature type to be built by a Feature­Type­Builder. An attribute can be for example a city name, a temperature (together with its units of measurement and uncertainty if desired) or a geometric shape. Attribute types contain the following information:

• the name — a unique name which can be defined within a scope (or namespace).
• the definition — a concise definition of the element.
• the designation — a natural language designator for the element for user interfaces.
• the description — information beyond that required for concise definition of the element.
• the value class — often String, Float or Geometry. Must be specified at construction time.
• a default value — to be used when an attribute instance does not provide an explicit value.
• characteristics — for example the units of measurement for all attributes of the same type.
• cardinality — the minimum and maximum occurrences of attribute values.

Since:

0.8

See Also:

Feature­Type­Builder.add­Attribute(Class), Default­Attribute­Type

Defined in the sis-feature module

Method Summary

Modifier and Type	Method and Description
<C> CharacteristicTypeBuilder<C>	addCharacteristic(Class<C> type) Adds another attribute type that describes this attribute type.
<C> CharacteristicTypeBuilder<C>	addCharacteristic(DefaultAttributeType<C> template) Adds another attribute type that describes this attribute type, using an existing one as a template.
boolean	addRole(AttributeRole role) Flags this attribute as an input of one of the pre-defined operations managed by Attribute­Type­Builder.
DefaultAttributeType<V>	build() Builds the attribute type from the information specified to this builder.
List<CharacteristicTypeBuilder<?>>	characteristics() Returns a view of all characteristics added to the Attribute­Type to build.
CharacteristicTypeBuilder<?>	getCharacteristic(String name) Returns the builder for the characteristic of the given name.
CoordinateReferenceSystem	getCRS() Returns the coordinate reference system associated to attribute values.
V	getDefaultValue() Returns the default value for the attribute, or null if none.
Integer	getMaximalLength() Returns the maximal length that characterizes the Char­Sequence values of this attribute.
V[]	getValidValues() Returns an enumeration of valid values for the attribute, or an empty array if none.
Class<V>	getValueClass() Returns the class of attribute values.
void	remove() Removes this property from the Feature­Type­Builder.
Set<AttributeRole>	roles() Returns the roles that the attribute play in the pre-defined operations managed by Attribute­Type­Builder.
AttributeTypeBuilder<V>	setCRS(CoordinateReferenceSystem crs) Sets the coordinate reference system that characterizes the values of this attribute.
AttributeTypeBuilder<V>	setDefaultValue(V value) Sets the default value for the attribute.
AttributeTypeBuilder<V>	setDefinition(CharSequence definition) Sets a concise definition of the element.
AttributeTypeBuilder<V>	setDeprecated(boolean deprecated) Sets whether the type is deprecated.
AttributeTypeBuilder<V>	setDescription(CharSequence description) Sets optional information beyond that required for concise definition of the element.
AttributeTypeBuilder<V>	setDesignation(CharSequence designation) Sets a natural language designator for the element.
AttributeTypeBuilder<V>	setMaximalLength(Integer length) Sets the maximal length that characterizes the Char­Sequence values of this attribute.
AttributeTypeBuilder<V>	setMaximumOccurs(int occurs) Sets the maximum number of attribute values.
AttributeTypeBuilder<V>	setMinimumOccurs(int occurs) Sets the minimum number of attribute values.
AttributeTypeBuilder<V>	setName(CharSequence... components) Sets the Attribute­Type name as a string in the given scope.
AttributeTypeBuilder<V>	setName(CharSequence localPart) Sets the Attribute­Type name as a simple string (local name).
AttributeTypeBuilder<V>	setName(GenericName name) Sets the Attribute­Type name as a generic name.
AttributeTypeBuilder<V>	setValidValues(V... values) Sets an enumeration of valid values for the attribute.
<N> AttributeTypeBuilder<N>	setValueClass(Class<N> type) Sets the class of attribute values.

Methods inherited from class PropertyTypeBuilder

get­Maximum­Occurs, get­Minimum­Occurs

Methods inherited from class TypeBuilder

get­Definition, get­Description, get­Designation, get­Locale, get­Name, is­Deprecated, to­String

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, wait, wait, wait

Method Detail

setName

public AttributeTypeBuilder<V> setName(GenericName name)

Sets the Attribute­Type name as a generic name. If another name was defined before this method call, that previous value will be discarded.

Overrides:

set­Name in class Type­Builder

Parameters:

name - the generic name (can not be null).

Returns:

this for allowing method calls chaining.

See Also:

Type­Builder.get­Name(), Type­Builder.set­Name(Char­Sequence), Abstract­Identified­Type.NAME_KEY

setName

public AttributeTypeBuilder<V> setName(CharSequence localPart)

Sets the Attribute­Type name as a simple string (local name). The namespace will be the value specified by the last call to Feature­Type­Builder.set­Name­Space(Char­Sequence), but that namespace will not be visible in the string representation unless the fully qualified name is requested.

This convenience method creates a Local­Name instance from the given Char­Sequence, then delegates to set­Name(Generic­Name).

Overrides:

set­Name in class Type­Builder

Parameters:

local­Part - the local part of the generic name as a String or International­String.

Returns:

this for allowing method calls chaining.

See Also:

Type­Builder.get­Name(), Type­Builder.set­Name(Char­Sequence...), Feature­Type­Builder.get­Name­Space()

setName

public AttributeTypeBuilder<V> setName(CharSequence... components)

Sets the Attribute­Type name as a string in the given scope. The components array must contain at least one element. The last component (the tip) will be sufficient in many cases for calls to the Abstract­Feature.get­Property(String) method. The other elements before the last one are optional and can be used for resolving ambiguity. They will be visible as the name path.

Example: a call to set­Name("A", "B", "C") will create a "A:B:C" name. An attribute built with this name can be obtained from a feature by a call to feature.get­Property("C") if there is no ambiguity, or otherwise by a call to feature.get­Property("B:C") (if non-ambiguous) or feature.get­Property("A:B:C").

In addition to the path specified by the components array, the name may also contain a namespace specified by the last call to Feature­Type­Builder.set­Name­Space(Char­Sequence). But contrarily to the specified components, the namespace will not be visible in the name string representation unless the fully qualified name is requested.

This convenience method creates a Local­Name or Scoped­Name instance depending on whether the names array contains exactly 1 element or more than 1 element, then delegates to set­Name(Generic­Name).

Overrides:

set­Name in class Type­Builder

Parameters:

components - the name components as an array of String or International­String instances.

Returns:

this for allowing method calls chaining.

See Also:

Type­Builder.get­Name(), Type­Builder.set­Name(Char­Sequence), Feature­Type­Builder.get­Name­Space()

setMinimumOccurs

public AttributeTypeBuilder<V> setMinimumOccurs(int occurs)

Sets the minimum number of attribute values. If the given number is greater than the maximal number of attribute values, than the maximum is also set to that value.

Overrides:

set­Minimum­Occurs in class Property­Type­Builder

Parameters:

occurs - the new minimum number of attribute values.

Returns:

this for allowing method calls chaining.

See Also:

Property­Type­Builder.get­Minimum­Occurs()

setMaximumOccurs

public AttributeTypeBuilder<V> setMaximumOccurs(int occurs)

Sets the maximum number of attribute values. If the given number is less than the minimal number of attribute values, than the minimum is also set to that value.

Overrides:

set­Maximum­Occurs in class Property­Type­Builder

Parameters:

occurs - the new maximum number of attribute values.

Returns:

this for allowing method calls chaining.

See Also:

Property­Type­Builder.get­Maximum­Occurs()

getValueClass

public Class<V> getValueClass()

Returns the class of attribute values.

Returns:

the class of attribute values.

See Also:

set­Value­Class(Class)

setValueClass

public <N> AttributeTypeBuilder<N> setValueClass(Class<N> type)
                                          throws UnconvertibleObjectException

Sets the class of attribute values. Callers must use the builder returned by this method instead of this builder after this method call, since the returned builder may be a new instance.

Type Parameters:

N - the compile-time value of the type argument.

Parameters:

type - the new class of attribute values.

Returns:

the attribute builder — not necessarily this instance.

Throws:

Unconvertible­Object­Exception - if the default value can not be converted to the given <N> class.

See Also:

get­Value­Class()

getDefaultValue

public V getDefaultValue()

Returns the default value for the attribute, or null if none.

Returns:

the default attribute value, or null if none.

See Also:

set­Default­Value(Object)

setDefaultValue

public AttributeTypeBuilder<V> setDefaultValue(V value)

Sets the default value for the attribute.

Parameters:

value - default attribute value, or null if none.

Returns:

this for allowing method calls chaining.

See Also:

get­Default­Value()

getValidValues

public V[] getValidValues()

Returns an enumeration of valid values for the attribute, or an empty array if none. This convenience method returns the value of the characteristic set by set­Valid­Values(Object...).

Returns:

valid values for the attribute, or an empty array if none.

setValidValues

@SafeVarargs
public final AttributeTypeBuilder<V> setValidValues(V... values)

Sets an enumeration of valid values for the attribute.

This is a convenience method for add­Characteristic(Class) with a value of type Set and a conventional name.

Parameters:

values - valid values.

Returns:

this for allowing method calls chaining.

See Also:

characteristics(), Attribute­Convention.VALID_VALUES_CHARACTERISTIC

getMaximalLength

public Integer getMaximalLength()

Returns the maximal length that characterizes the Char­Sequence values of this attribute. This convenience method returns the value of the characteristic set by set­Maximal­Length(Integer).

Returns:

the maximal length of Char­Sequence attribute values, or null.

setMaximalLength

public AttributeTypeBuilder<V> setMaximalLength(Integer length)

Sets the maximal length that characterizes the Char­Sequence values of this attribute. While this characteristic can be applied to any kind of attribute, it is meaningful only with character sequences.

This is a convenience method for add­Characteristic(Class) with a value of type Integer and a conventional name.

Parameters:

length - maximal length of Char­Sequence attribute values, or null.

Returns:

this for allowing method calls chaining.

See Also:

characteristics(), Attribute­Convention.MAXIMAL_LENGTH_CHARACTERISTIC

getCRS

public CoordinateReferenceSystem getCRS()

Returns the coordinate reference system associated to attribute values. This convenience method returns the value of the characteristic set by set­CRS(Coordinate­Reference­System).

Returns:

the coordinate reference system associated to attribute values, or null.

setCRS

public AttributeTypeBuilder<V> setCRS(CoordinateReferenceSystem crs)

Sets the coordinate reference system that characterizes the values of this attribute. While this characteristic can be applied to any kind of attribute, it is meaningful only with georeferenced values like geometries or coverages.

This is a convenience method for add­Characteristic(Class) with a value of type Coordinate­Reference­System and a conventional name.

Parameters:

crs - coordinate reference system associated to attribute values, or null.

Returns:

this for allowing method calls chaining.

See Also:

characteristics(), Attribute­Convention.CRS_CHARACTERISTIC

getCharacteristic

public CharacteristicTypeBuilder<?> getCharacteristic(String name)

Returns the builder for the characteristic of the given name. The given name does not need to contains all elements of a Scoped­Name; it is okay to specify only the tip (for example "my­Name" instead of "my­Scope:my­Name") provided that ignoring the name head does not create ambiguity.

Parameters:

name - name of the characteristic to search.

Returns:

characteristic of the given name, or null if none.

Throws:

Illegal­Argument­Exception - if the given name is ambiguous.

See Also:

characteristics()

addCharacteristic

public <C> CharacteristicTypeBuilder<C> addCharacteristic(Class<C> type)

Adds another attribute type that describes this attribute type. See "Attribute characterization" in Default­Attribute­Type Javadoc for more information.

Usage example:

attribute.addCharacteristic(Unit.class).setName("Unit of measurement").setDefaultValue(Units.CELSIUS);

The default characteristic name is the name of the given type, but callers should invoke one of the Characteristic­Type­Builder.set­Name(…) methods on the returned instance with a better name.

Type Parameters:

C - the compile-time type of type argument.

Parameters:

type - the class of characteristic values.

Returns:

a builder for a characteristic of this attribute.

See Also:

characteristics()

addCharacteristic

public <C> CharacteristicTypeBuilder<C> addCharacteristic(DefaultAttributeType<C> template)

Adds another attribute type that describes this attribute type, using an existing one as a template. See "Attribute characterization" in Default­Attribute­Type Javadoc for more information.

Warning: The template argument type will be changed to Attribute­Type if and when such interface will be defined in GeoAPI.

Type Parameters:

C - the compile-time type of values in the template argument.

Parameters:

template - an existing attribute type to use as a template.

Returns:

a builder for a characteristic of this attribute, initialized with the values of the given template.

See Also:

characteristics()

characteristics

public List<CharacteristicTypeBuilder<?>> characteristics()

Returns a view of all characteristics added to the Attribute­Type to build. The returned list is live: changes in this builder are reflected in that list and conversely. However the returned list allows only remove operations; new characteristics can be added only by calls to one of the set/add­Characteristic(…) methods.

Returns:

a live list over the characteristics declared to this builder.

See Also:

get­Characteristic(String), add­Characteristic(Class), add­Characteristic(Default­Attribute­Type), set­Valid­Values(Object...), set­CRS(Coordinate­Reference­System)

roles

public Set<AttributeRole> roles()

Returns the roles that the attribute play in the pre-defined operations managed by Attribute­Type­Builder. The set returned by this method is live: additions or removal on that set are reflected back on this builder, and conversely.

Returns:

the roles that the attribute play in the pre-defined operations managed by Attribute­Type­Builder.

addRole

public boolean addRole(AttributeRole role)

Flags this attribute as an input of one of the pre-defined operations managed by Attribute­Type­Builder. Invoking this method is equivalent to invoking roles().add(role).

Parameters:

role - the role to add to the attribute (shall not be null).

Returns:

true if the given role has been added to the attribute.

setDefinition

public AttributeTypeBuilder<V> setDefinition(CharSequence definition)

Sets a concise definition of the element.

Overrides:

set­Definition in class Type­Builder

Parameters:

definition - a concise definition of the element, or null if none.

Returns:

this for allowing method calls chaining.

See Also:

Type­Builder.get­Definition(), Abstract­Identified­Type.DEFINITION_KEY

setDesignation

public AttributeTypeBuilder<V> setDesignation(CharSequence designation)

Sets a natural language designator for the element. This can be used as an alternative to the name in user interfaces.

Overrides:

set­Designation in class Type­Builder

Parameters:

designation - a natural language designator for the element, or null if none.

Returns:

this for allowing method calls chaining.

See Also:

Type­Builder.get­Designation(), Abstract­Identified­Type.DESIGNATION_KEY

setDescription

public AttributeTypeBuilder<V> setDescription(CharSequence description)

Sets optional information beyond that required for concise definition of the element. The description may assist in understanding the feature scope and application. If the type is deprecated, then the description should give indication about the replacement (e.g. "superceded by …").

Overrides:

set­Description in class Type­Builder

Parameters:

description - information beyond that required for concise definition of the element, or null if none.

Returns:

this for allowing method calls chaining.

See Also:

Type­Builder.get­Description(), Abstract­Identified­Type.DESCRIPTION_KEY

setDeprecated

public AttributeTypeBuilder<V> setDeprecated(boolean deprecated)

Sets whether the type is deprecated. If the type is deprecated, then the description should be set to an indication about the replacement (e.g. "superceded by …").

Overrides:

set­Deprecated in class Type­Builder

Parameters:

deprecated - whether this type is deprecated.

Returns:

this for allowing method calls chaining.

See Also:

Type­Builder.is­Deprecated(), Abstract­Identified­Type.DEPRECATED_KEY

remove

public void remove()

Removes this property from the Feature­Type­Builder. After this method has been invoked, this Property­Type­Builder instance is no longer in the list returned by Feature­Type­Builder.properties() and attempts to invoke any setter method on this will cause an Illegal­State­Exception to be thrown.

Overrides:

remove in class Property­Type­Builder

build

public DefaultAttributeType<V> build()

Builds the attribute type from the information specified to this builder. If a type has already been built and this builder state has not changed since the type creation, then the previously created Attribute­Type instance is returned.

Example: the following lines of code add a "name" attribute to a "City" feature, then get the corresponding Attribute­Type<String> instance. If no setter method is invoked on the builder of the "name" attribute after those lines, then the name variable below will reference the same instance than the "name" attribute in the city type.

FeatureTypeBuilder builder = new FeatureTypeBuilder().setName("City");
AttributeType<String> name = builder.addAttribute(String.class).setName("name").build();
FeatureType city = builder.build();

assert city.getProperty("name") == name : "AttributeType instance should be the same.";

Note that city.get­Property("name") returns Attribute­Type<?>, i.e. the value class is lost at compile-time. By comparison, this build() method has a more accurate return type.

Warning: In a future SIS version, the return type may be changed to the org.opengis.feature.Attribute­Type interface. This change is pending GeoAPI revision.

Specified by:

build in class Property­Type­Builder

Returns:

the attribute type.