Class AbstractAttribute<V>
- Type Parameters:
V
- the type of attribute values. If the attribute supports multi-occurrences, then this is the type of elements (not the collection type).
- All Implemented Interfaces:
Serializable
- Direct Known Subclasses:
AttributeView
,EnvelopeOperation.Result
,GroupAsPolylineOperation.Result
,MultiValuedAttribute
,SingletonAttribute
,StringJoinOperation.Result
Attribute
holds three main information:
- A reference to an attribute type which defines the base Java type and domain of valid values.
- One or more values, which may be a singleton ([0 … 1] multiplicity) or multi-valued ([0 … ∞] multiplicity).
- Optional characteristics about the attribute (e.g. a temperature attribute may have a characteristic holding the measurement accuracy). Characteristics are often, but not necessarily, constant for all attributes of the same type in a dataset.
AbstractAttribute
can be instantiated by calls to DefaultAttributeType.newInstance()
.
Limitations
- Multi-threading:
AbstractAttribute
instances are not thread-safe. Synchronization, if needed, shall be done externally by the caller. - Serialization: serialized objects of this class are not guaranteed to be compatible with future versions. Serialization should be used only for short term storage or RMI between applications running the same SIS version.
- Cloning: despite providing a public
clone()
method, this base class is not cloneable by default. Subclasses shall implement theCloneable
interface themselves if they choose to support cloning.
- Since:
- 0.5
- Version:
- 0.8
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Map<String,
AbstractAttribute<?>> Other attributes that describes this attribute, ornull
if not yet created.private static final long
For cross-version compatibility.(package private) final DefaultAttributeType<V>
Information about the attribute (base Java class, domain of values, etc.). -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
Creates a new attribute of the given type. -
Method Summary
Modifier and TypeMethodDescriptionOther attributes that describes this attribute.(package private) final Map<String,
AbstractAttribute<?>> Returns the characteristics, or an empty map if the characteristics have not yet been built.clone()
Returns a copy of this attribute if cloning is supported.static <V> AbstractAttribute<V>
create
(DefaultAttributeType<V> type) Creates a new attribute of the given type initialized to the default value.(package private) static <V> AbstractAttribute<V>
create
(DefaultAttributeType<V> type, Object value) Creates a new attribute of the given type initialized to the given value.org.opengis.util.GenericName
getName()
Returns the name of this attribute as defined by its type.getType()
Returns information about the attribute (base Java class, domain of values, etc.).abstract V
getValue()
Returns the attribute value, ornull
if none.Returns all attribute values, or an empty collection if none.private Map<String,
AbstractAttribute<?>> Creates an initially empty map of characteristics for this attribute.org.opengis.metadata.quality.DataQuality
quality()
Evaluates the quality of this attribute at this method invocation time.private void
Invoked on deserialization for restoring thecharacteristics
field.abstract void
Sets the attribute value.void
setValues
(Collection<? extends V> values) Sets the attribute values.toString()
Returns a string representation of this attribute.private void
Invoked on serialization for saving thecharacteristics
field.Methods inherited from class org.apache.sis.feature.Field
isDeprecated, isSingleton
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
type
Information about the attribute (base Java class, domain of values, etc.). -
characteristics
Other attributes that describes this attribute, ornull
if not yet created.Design note: We could question if it is a good idea to put this field here, given that this field add a slight cost to all attribute implementations while only a small fraction of them will want attribute characteristics. Since attributes may exist in a very large amount, that question may be significant. However,AbstractFeature
tries hard to not createAttribute
instances at all (it tries to store only their value instead), so we presume that peoples who ask forAttribute
instances are willing to accept their cost.- See Also:
-
-
Constructor Details
-
AbstractAttribute
Creates a new attribute of the given type.- Parameters:
type
- information about the attribute (base Java class, domain of values, etc.).- See Also:
-
-
Method Details
-
create
Creates a new attribute of the given type initialized to the default value.- Type Parameters:
V
- the type of attribute values.- Parameters:
type
- information about the attribute (base Java class, domain of values, etc.).- Returns:
- the new attribute.
- See Also:
-
create
Creates a new attribute of the given type initialized to the given value. Note that anull
value may not be the same as the default value.- Type Parameters:
V
- the type of attribute values.- Parameters:
type
- information about the attribute (base Java class, domain of values, etc.).value
- the initial value (may benull
).- Returns:
- the new attribute.
-
writeObject
Invoked on serialization for saving thecharacteristics
field.- Parameters:
out
- the output stream where to serialize this attribute.- Throws:
IOException
- if an I/O error occurred while writing.
-
readObject
Invoked on deserialization for restoring thecharacteristics
field.- Parameters:
in
- the input stream from which to deserialize an attribute.- Throws:
IOException
- if an I/O error occurred while reading or if the stream contains invalid data.ClassNotFoundException
- if the class serialized on the stream is not on the classpath.
-
getName
public org.opengis.util.GenericName getName()Returns the name of this attribute as defined by its type. This convenience method delegates toAbstractIdentifiedType.getName()
. -
getType
Returns information about the attribute (base Java class, domain of values, etc.).Warning: In a future SIS version, the return type may be changed toorg.opengis.feature.AttributeType
. This change is pending GeoAPI revision.- Returns:
- information about the attribute.
-
getValue
Returns the attribute value, ornull
if none. This convenience method can be invoked in the common case where the maximum number of attribute values is restricted to 1 or 0.- Specified by:
getValue
in classField<V>
- Returns:
- the attribute value (may be
null
). - Throws:
IllegalStateException
- if this attribute contains more than one value.- See Also:
-
getValues
Returns all attribute values, or an empty collection if none. The returned collection is live: changes in the returned collection will be reflected immediately in thisAttribute
instance, and conversely.The default implementation returns a collection which will delegate its work to
getValue()
andsetValue(Object)
. -
setValue
Sets the attribute value. All previous values are replaced by the given singleton.Validation
The amount of validation performed by this method is implementation dependent. Usually, only the most basic constraints are verified. This is so for performance reasons and also because some rules may be temporarily broken while constructing a feature. A more exhaustive verification can be performed by invoking thequality()
method.- Specified by:
setValue
in classField<V>
- Parameters:
value
- the new value, ornull
for removing all values from this attribute.- Throws:
IllegalArgumentException
- if this method verifies argument validity and the given value does not met the attribute constraints.- See Also:
-
setValues
Sets the attribute values. All previous values are replaced by the given collection.The default implementation ensures that the given collection contains at most one element, then delegates to
setValue(Object)
.- Overrides:
setValues
in classField<V>
- Parameters:
values
- the new values.- Throws:
IllegalArgumentException
- if the given collection contains too many elements.
-
characteristics
Other attributes that describes this attribute. For example if this attribute carries a measurement, then a characteristic of this attribute could be the measurement accuracy. See "Attribute characterization" inDefaultAttributeType
Javadoc for more information.The map returned by this method contains only the characteristics explicitly defined for this attribute. If the map contains no characteristic for a given name, a default value may still exist. In such cases, callers may also need to inspect the
DefaultAttributeType.characteristics()
as shown in the Reading a characteristic section below.Rational: Very often, all attributes of a given type in the same dataset have the same characteristics. For example, it is very common that all temperature measurements in a dataset have the same accuracy, and setting a different accuracy for a single measurement is relatively rare. Consequently,characteristics.isEmpty()
is a convenient way to check that an attribute have all the "standard" characteristics and need no special processing.Reading a characteristic
The characteristic values are enumerated in the map values. The map keys are theString
representations of characteristics name, for more convenient lookups.If an attribute is known to be a measurement with a characteristic named "accuracy" of type
Float
, then the accuracy value could be read as below:Adding a characteristic
A new characteristic can be added in the map in three different ways:- Putting the (name, characteristic) pair explicitly. If an older characteristic existed for that name, it will be replaced. Example:
- Adding the new characteristic to the values collection.
The name is inferred automatically from the characteristic type.
If an older characteristic existed for the same name, an
IllegalStateException
will be thrown. Example: - Adding the characteristic name to the key set. If no characteristic existed for that name, a default one will be created. Example:
- Returns:
- other attribute types that describes this attribute type, or an empty map if none.
- See Also:
-
newCharacteristicsMap
Creates an initially empty map of characteristics for this attribute. This method does not store the new map in thecharacteristics
field; it is caller responsibility to do so if desired. -
characteristicsReadOnly
Returns the characteristics, or an empty map if the characteristics have not yet been built. Contrarily tocharacteristics()
, this method does not create the map. This method is suitable when then caller only wants to read the map and does not plan to write anything. -
quality
public org.opengis.metadata.quality.DataQuality quality()Evaluates the quality of this attribute at this method invocation time. The data quality reports may include information about whether the attribute value mets the constraints defined by the attribute type, or any other criterion at implementation choice.The default implementation reports data quality with at least the following information:
-
The scope
level is set to
ScopeCode.ATTRIBUTE
. -
At most one domain consistency
element is added to the reports list (implementations are free to omit that element if they have nothing to report).
If a report is provided, then it will contain at least the following information:
-
The attribute name as the data quality measure identification.
Note: strictly speaking,measureIdentification
identifies the quality measurement, not the “real” measurement itself. However, this implementation uses the same set of identifiers for both for simplicity. -
If the attribute value is not an instance of the expected value class, or if the number of occurrences is not inside the multiplicity range, or if any other constraint is violated, then a conformance result is added for each violation with an explanation set to the error message.
Note: this is a departure from ISO intent, sinceexplanation
should be a statement about what a successful conformance means. This point may be reformulated in a future SIS version.
-
false
.Example: given an attribute named “population” with [1 … 1] multiplicity, if no value has been assigned to that attribute, then thisquality()
method will return the following data quality report:- Returns:
- reports on all constraint violations found.
- See Also:
-
The scope
level is set to
-
toString
Returns a string representation of this attribute. The returned string is for debugging purpose and may change in any future SIS version. The current implementation is like below: -
clone
Returns a copy of this attribute if cloning is supported. The decision to support cloning or not is left to subclasses. If the subclass does not implement theCloneable
interface, then this method throws aCloneNotSupportedException
. Otherwise the default implementation returns a shallow copy of thisAttribute
: the attribute value and characteristics are not cloned. However, subclasses may choose to do otherwise.- Overrides:
clone
in classObject
- Returns:
- a clone of this attribute.
- Throws:
CloneNotSupportedException
- if this attribute, the value or one of its characteristics cannot be cloned.
-