- All Implemented Interfaces:
Emptiable,LenientComparable
- Direct Known Subclasses:
ISOMetadata
ModifiableMetadata are initially in editable state.
The metadata can be populated using the setter methods provided by subclasses, then transition to the
final state for making it safe to share by many consumers.
Tip for subclass implementations
Subclasses can follow the pattern below for everyget and set methods,
with a different processing for singleton value or for collections.
public class MyMetadata {
// ==== Example for a singleton value =============================
private Foo property;
public Foo getProperty() {
return property;
}
public void setProperty(Foo newValue) {
checkWritePermission();
property = newValue;
}
// ==== Example for a collection ==================================
private Collection<Foo> properties;
public Collection<Foo> getProperties() {
return properties = nonNullCollection(properties, Foo.class);
}
public void setProperties(Collection<Foo> newValues) {
// the call to checkWritePermission() is implicit
properties = writeCollection(newValues, properties, Foo.class);
}
}
- Since:
- 0.3
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enumWhether the metadata is still editable or has been made final. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedConstructs an initially empty metadata. -
Method Summary
Modifier and TypeMethodDescriptionprotected voidcheckWritePermission(Object current) Checks if changes in the metadata are allowed.protected <E> Class<? extends Collection<E>> collectionType(Class<E> elementType) Returns the type of collection to use for the given type.protected final <E> Collection<E> copyCollection(Collection<? extends E> source, Class<E> elementType) Creates a list or set with the content of thesourcecollection, or returnsnullif the source isnullor empty.protected final <E> List<E> copyList(Collection<? extends E> source, Class<E> elementType) Creates a list with the content of thesourcecollection, or returnsnullif the source isnullor empty.protected final <K,V> Map <K, V> Creates a map with the content of thesourcemap, or returnsnullif the source isnullor empty.protected final <E> Set<E> copySet(Collection<? extends E> source, Class<E> elementType) Creates a set with the content of thesourcecollection, or returnsnullif the source isnullor empty.deepCopy(ModifiableMetadata.State target) Copies (if necessary) this metadata and all its children.protected final <E> Collection<E> nonNullCollection(Collection<E> current, Class<E> elementType) Returns the specified collection, or a new one ifcurrentis null.protected final <E> List<E> nonNullList(List<E> current, Class<E> elementType) Returns the specified list, or a new one ifcurrentis null.protected final <K,V> Map <K, V> nonNullMap(Map<K, V> current, Class<K> keyType) Returns the specified map, or a new one ifcurrentis null.protected final <E> Set<E> nonNullSet(Set<E> current, Class<E> elementType) Returns the specified set, or a new one ifcurrentis null.protected final <E> Collection<E> Creates a singleton list or set containing only the given value, if non-null.state()Tells whether this instance of metadata is editable.booleanRequests this metadata instance and (potentially) all its children to transition to a new state.protected final <E> Collection<E> writeCollection(Collection<? extends E> source, Collection<E> target, Class<E> elementType) Writes the content of thesourcecollection into thetargetlist or set, creating it if needed.protected final <E> List<E> writeList(Collection<? extends E> source, List<E> target, Class<E> elementType) Writes the content of thesourcecollection into thetargetlist, creating it if needed.protected final <K,V> Map <K, V> Writes the content of thesourcemap into thetargetmap, creating it if needed.protected final <E> Set<E> writeSet(Collection<? extends E> source, Set<E> target, Class<E> elementType) Writes the content of thesourcecollection into thetargetset, creating it if needed.Methods inherited from class AbstractMetadata
asMap, asTreeTable, equals, equals, getInterface, getStandard, hashCode, isEmpty, prune, toString
-
Constructor Details
-
ModifiableMetadata
protected ModifiableMetadata()Constructs an initially empty metadata. The initial state isModifiableMetadata.State.EDITABLE.
-
-
Method Details
-
state
Tells whether this instance of metadata is editable. This is initiallyModifiableMetadata.State.EDITABLEfor newModifiableMetadatainstances, but can be changed by a call totransitionTo(State).ModifiableMetadata.State.FINALimplies that all properties are also final. This recursivity does not necessarily apply to other states. For example,ModifiableMetadata.State.EDITABLEdoes not imply that allModifiableMetadatachildren are also editable.API note: theModifiableMetadatastate is not a metadata per se, but rather an information about this particular instance of a metadata class. Two metadata instances may be in different states but still have the same metadata content. For this reason, this method does not havegetprefix for avoiding confusion with getter and setter methods of metadata properties.- Returns:
- the state (editable, completable or final) of this
ModifiableMetadatainstance. - Since:
- 1.0
-
transitionTo
Requests this metadata instance and (potentially) all its children to transition to a new state. The action performed by this method depends on the source state and the given target state, as listed in the following table:
The effect of invoking this method may be recursive. For example, transitioning toState transitions Current state Target state Action Any Same Does nothing and returns false.ModifiableMetadata.State.EDITABLEModifiableMetadata.State.COMPLETABLEMarks this metadata and all children as completable. Any ModifiableMetadata.State.FINALMarks this metadata and all children as unmodifiable. ModifiableMetadata.State.FINALAny other Throws UnmodifiableMetadataException.ModifiableMetadata.State.FINALimplies transitioning all childrenModifiableMetadatainstances to the final state too.- Parameters:
target- the desired new state (editable, completable or final).- Returns:
trueif the state of thisModifiableMetadatachanged as a result of this method call.- Throws:
UnmodifiableMetadataException- if a transition to a less restrictive state (e.g. fromModifiableMetadata.State.FINALtoModifiableMetadata.State.EDITABLE) was attempted.- Since:
- 1.0
-
deepCopy
Copies (if necessary) this metadata and all its children. Changes in the returned metadata will not affect thisModifiableMetadatainstance, and conversely. The returned metadata will be in the state specified by thetargetargument. The state of thisModifiableMetadatainstance stay unchanged.As a special case, this method returns
thisif and only if the specified target isModifiableMetadata.State.FINALand thisModifiableMetadatainstance is already in final state. In that particular case, copies are not needed for protecting metadata against changes because neitherthisor the returned value can be modified.This method is typically invoked for getting a modifiable metadata from an unmodifiable one:
Metadata source = ...; // Any implementation. DefaultMetadata md = DefaultMetadata.castOrCopy(source); md = (DefaultMetadata) md.deepCopy(DefaultMetadata.State.EDITABLE);Alternative
If unconditional copy is desired, or if the metadata to copy may be arbitrary implementations of GeoAPI interfaces (i.e. not necessarily aModifiableMetadatasubclass), then the following code can be used instead:TheMetadataCopier copier = new MetadataCopier(MetadataStandard.ISO_19115); Metadata source = ...; // Any implementation. Metadata copy = copier.copy(Metadata.class, source);Metadatatype in above example can be replaced by any other ISO 19115 type. Types from other standards can also be used if theMetadataStandard.ISO_19115constant is replaced accordingly.- Parameters:
target- the desired state (editable, completable or final).- Returns:
- a copy (except in above-cited special case) of this metadata in the specified state.
- Since:
- 1.1
- See Also:
-
checkWritePermission
Checks if changes in the metadata are allowed. AllsetFoo(…)methods in subclasses shall invoke this method (directly or indirectly) before to apply any change. The current property value should be specified in argument.- Parameters:
current- the current value, ornullif none.- Throws:
UnmodifiableMetadataException- if this metadata is unmodifiable.- Since:
- 1.0
- See Also:
-
writeList
protected final <E> List<E> writeList(Collection<? extends E> source, List<E> target, Class<E> elementType) throws UnmodifiableMetadataException Writes the content of thesourcecollection into thetargetlist, creating it if needed. This method performs the following steps:- Invokes
checkWritePermission(Object)in order to ensure that this metadata is modifiable. - If
sourceis null or empty, returnsnull(meaning that the metadata property is not provided). - If
targetis null, creates a newList. - Copies the content of the given
sourceinto the target.
- Type Parameters:
E- the type represented by theClassargument.- Parameters:
source- the source list, ornull.target- the target list, ornullif not yet created.elementType- the base type of elements to put in the list.- Returns:
- a list (possibly the
targetinstance) containing thesourceelements, ornullif the source was null. - Throws:
UnmodifiableMetadataException- if this metadata is unmodifiable.- See Also:
- Invokes
-
writeSet
protected final <E> Set<E> writeSet(Collection<? extends E> source, Set<E> target, Class<E> elementType) throws UnmodifiableMetadataException Writes the content of thesourcecollection into thetargetset, creating it if needed. This method performs the following steps:- Invokes
checkWritePermission(Object)in order to ensure that this metadata is modifiable. - If
sourceis null or empty, returnsnull(meaning that the metadata property is not provided). - If
targetis null, creates a newSet. - Copies the content of the given
sourceinto the target.
- Type Parameters:
E- the type represented by theClassargument.- Parameters:
source- the source set, ornull.target- the target set, ornullif not yet created.elementType- the base type of elements to put in the set.- Returns:
- a set (possibly the
targetinstance) containing thesourceelements, ornullif the source was null. - Throws:
UnmodifiableMetadataException- if this metadata is unmodifiable.- See Also:
- Invokes
-
writeCollection
protected final <E> Collection<E> writeCollection(Collection<? extends E> source, Collection<E> target, Class<E> elementType) throws UnmodifiableMetadataException Writes the content of thesourcecollection into thetargetlist or set, creating it if needed. This method performs the following steps:- Invokes
checkWritePermission(Object)in order to ensure that this metadata is modifiable. - If
sourceis null or empty, returnsnull(meaning that the metadata property is not provided). - If
targetis null, creates a newSetor a newListdepending on the value returned bycollectionType(Class). - Copies the content of the given
sourceinto the target.
Choosing a collection type
Implementations shall invokewriteListorwriteSetmethods instead of this method when the collection type is enforced by ISO specification. When the type is not enforced by the specification, some freedom are allowed at implementer choice. The default implementation invokescollectionType(Class)in order to get a hint about whether aListor aSetshould be used.- Type Parameters:
E- the type represented by theClassargument.- Parameters:
source- the source collection, ornull.target- the target collection, ornullif not yet created.elementType- the base type of elements to put in the collection.- Returns:
- a collection (possibly the
targetinstance) containing thesourceelements, ornullif the source was null. - Throws:
UnmodifiableMetadataException- if this metadata is unmodifiable.
- Invokes
-
writeMap
protected final <K,V> Map<K,V> writeMap(Map<? extends K, ? extends V> source, Map<K, throws UnmodifiableMetadataExceptionV> target, Class<K> keyType) Writes the content of thesourcemap into thetargetmap, creating it if needed. This method performs the following steps:- Invokes
checkWritePermission(Object)in order to ensure that this metadata is modifiable. - If
sourceis null or empty, returnsnull(meaning that the metadata property is not provided). - If
targetis null, creates a newMap. - Copies the content of the given
sourceinto the target.
- Type Parameters:
K- the type of keys represented by theClassargument.V- the type of values in the map.- Parameters:
source- the source map, ornull.target- the target map, ornullif not yet created.keyType- the base type of keys to put in the map.- Returns:
- a map (possibly the
targetinstance) containing thesourceentries, ornullif the source was null. - Throws:
UnmodifiableMetadataException- if this metadata is unmodifiable.- Since:
- 1.0
- See Also:
- Invokes
-
copyList
Creates a list with the content of thesourcecollection, or returnsnullif the source isnullor empty. This is a convenience method for copying fields in subclass copy constructors.- Type Parameters:
E- the type represented by theClassargument.- Parameters:
source- the source collection, ornull.elementType- the base type of elements to put in the list.- Returns:
- a list containing the
sourceelements, ornullif the source was null or empty.
-
copySet
Creates a set with the content of thesourcecollection, or returnsnullif the source isnullor empty. This is a convenience method for copying fields in subclass copy constructors.- Type Parameters:
E- the type represented by theClassargument.- Parameters:
source- the source collection, ornull.elementType- the base type of elements to put in the set.- Returns:
- a set containing the
sourceelements, ornullif the source was null or empty.
-
copyCollection
protected final <E> Collection<E> copyCollection(Collection<? extends E> source, Class<E> elementType) Creates a list or set with the content of thesourcecollection, or returnsnullif the source isnullor empty. This is a convenience method for copying fields in subclass copy constructors.The collection type is selected as described in the
nonNullCollection(Collection, Class).- Type Parameters:
E- the type represented by theClassargument.- Parameters:
source- the source collection, ornull.elementType- the base type of elements to put in the collection.- Returns:
- a collection containing the
sourceelements, ornullif the source was null or empty.
-
copyMap
Creates a map with the content of thesourcemap, or returnsnullif the source isnullor empty. This is a convenience method for copying fields in subclass copy constructors.- Type Parameters:
K- the type of keys represented by theClassargument.V- the type of values in the map.- Parameters:
source- the source map, ornull.keyType- the base type of keys to put in the map.- Returns:
- a map containing the
sourceentries, ornullif the source was null or empty. - Since:
- 1.0
-
singleton
Creates a singleton list or set containing only the given value, if non-null. This is a convenience method for initializing fields in subclass constructors.The collection type is selected as described in the
nonNullCollection(Collection, Class).- Type Parameters:
E- the type represented by theClassargument.- Parameters:
value- the singleton value to put in the returned collection, ornull.elementType- the element type (used only ifvalueis non-null).- Returns:
- a new modifiable collection containing the given value,
or
nullif the given value was null.
-
nonNullList
Returns the specified list, or a new one ifcurrentis null. This is a convenience method for implementation ofgetFoo()methods.- Type Parameters:
E- the type represented by theClassargument.- Parameters:
current- the existing list, ornullif the list has not yet been created.elementType- the element type (used only ifcurrentis null).- Returns:
current, or a new list ifcurrentis null.
-
nonNullSet
Returns the specified set, or a new one ifcurrentis null. This is a convenience method for implementation ofgetFoo()methods.- Type Parameters:
E- the type represented by theClassargument.- Parameters:
current- the existing set, ornullif the set has not yet been created.elementType- the element type (used only ifcurrentis null).- Returns:
current, or a new set ifcurrentis null.
-
nonNullCollection
Returns the specified collection, or a new one ifcurrentis null. This is a convenience method for implementation ofgetFoo()methods.Choosing a collection type
Implementations shall invokenonNullList(…)ornonNullSet(…)instead of this method when the collection type is enforced by ISO specification. When the type is not enforced by the specification, some freedom are allowed at implementer choice. The default implementation invokescollectionType(Class)in order to get a hint about whether aListor aSetshould be used.- Type Parameters:
E- the type represented by theClassargument.- Parameters:
current- the existing collection, ornullif the collection has not yet been created.elementType- the element type (used only ifcurrentis null).- Returns:
current, or a new collection ifcurrentis null.
-
nonNullMap
Returns the specified map, or a new one ifcurrentis null. This is a convenience method for implementation ofgetFoo()methods.- Type Parameters:
K- the type of keys represented by theClassargument.V- the type of values in the map.- Parameters:
current- the existing map, ornullif the map has not yet been created.keyType- the key type (used only ifcurrentis null).- Returns:
current, or a new map ifcurrentis null.- Since:
- 1.0
-
collectionType
Returns the type of collection to use for the given type. The current implementation can return only two values:Set.classif the property should not accept duplicated values, orList.classotherwise. Future SIS versions may accept other types.The default implementation returns
Set.classif the element type is assignable toCodeList,Enum,String,Charset,LocaleorCurrency, andList.classotherwise. Subclasses can override this method for choosing different kind of collections. Note however thatSetshould be used only with immutable element types, for hash code stability.- Type Parameters:
E- the type of elements in the collection to be created.- Parameters:
elementType- the type of elements in the collection to be created.- Returns:
List.classorSet.classdepending on whether the property shall accept duplicated values or not.
-