Class ModifiableMetadata
- 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
Defined in the sis-metadata module
- 
Nested Class SummaryNested ClassesModifier and TypeClassDescriptionstatic enumWhether the metadata is still editable or has been made final.
- 
Constructor SummaryConstructorsModifierConstructorDescriptionprotectedConstructs an initially empty metadata.
- 
Method SummaryModifier 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 AbstractMetadataasMap, asTreeTable, equals, equals, getInterface, getStandard, hashCode, isEmpty, prune, toString
- 
Constructor Details- 
ModifiableMetadataprotected ModifiableMetadata()Constructs an initially empty metadata. The initial state isModifiableMetadata.State.EDITABLE.
 
- 
- 
Method Details- 
stateTells 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
 
- 
transitionToRequests 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 this- ModifiableMetadatachanged as a result of this method call.
- Throws:
- UnmodifiableMetadataException- if a transition to a less restrictive state (e.g. from- ModifiableMetadata.State.FINALto- ModifiableMetadata.State.EDITABLE) was attempted.
- Since:
- 1.0
 
- 
deepCopyCopies (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); AlternativeIf 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:
 
- 
checkWritePermissionChecks 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, or- nullif none.
- Throws:
- UnmodifiableMetadataException- if this metadata is unmodifiable.
- Since:
- 1.0
- See Also:
 
- 
writeListprotected 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 the- Classargument.
- Parameters:
- source- the source list, or- null.
- target- the target list, or- nullif 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 
- 
writeSetprotected 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 the- Classargument.
- Parameters:
- source- the source set, or- null.
- target- the target set, or- nullif 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 
- 
writeCollectionprotected 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 typeImplementations 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 the- Classargument.
- Parameters:
- source- the source collection, or- null.
- target- the target collection, or- nullif 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 
- 
writeMapprotected 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 the- Classargument.
- V- the type of values in the map.
- Parameters:
- source- the source map, or- null.
- target- the target map, or- nullif 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 
- 
copyListCreates 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 the- Classargument.
- Parameters:
- source- the source collection, or- null.
- elementType- the base type of elements to put in the list.
- Returns:
- a list containing the sourceelements, ornullif the source was null or empty.
 
- 
copySetCreates 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 the- Classargument.
- Parameters:
- source- the source collection, or- null.
- elementType- the base type of elements to put in the set.
- Returns:
- a set containing the sourceelements, ornullif the source was null or empty.
 
- 
copyCollectionprotected 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 the- Classargument.
- Parameters:
- source- the source collection, or- null.
- elementType- the base type of elements to put in the collection.
- Returns:
- a collection containing the sourceelements, ornullif the source was null or empty.
 
- 
copyMapCreates 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 the- Classargument.
- V- the type of values in the map.
- Parameters:
- source- the source map, or- null.
- 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
 
- 
singletonCreates 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 the- Classargument.
- Parameters:
- value- the singleton value to put in the returned collection, or- null.
- elementType- the element type (used only if- valueis non-null).
- Returns:
- a new modifiable collection containing the given value,
         or nullif the given value was null.
 
- 
nonNullListReturns 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 the- Classargument.
- Parameters:
- current- the existing list, or- nullif the list has not yet been created.
- elementType- the element type (used only if- currentis null).
- Returns:
- current, or a new list if- currentis null.
 
- 
nonNullSetReturns 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 the- Classargument.
- Parameters:
- current- the existing set, or- nullif the set has not yet been created.
- elementType- the element type (used only if- currentis null).
- Returns:
- current, or a new set if- currentis null.
 
- 
nonNullCollectionReturns the specified collection, or a new one ifcurrentis null. This is a convenience method for implementation ofgetFoo()methods.Choosing a collection typeImplementations 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 the- Classargument.
- Parameters:
- current- the existing collection, or- nullif the collection has not yet been created.
- elementType- the element type (used only if- currentis null).
- Returns:
- current, or a new collection if- currentis null.
 
- 
nonNullMapReturns 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 the- Classargument.
- V- the type of values in the map.
- Parameters:
- current- the existing map, or- nullif the map has not yet been created.
- keyType- the key type (used only if- currentis null).
- Returns:
- current, or a new map if- currentis null.
- Since:
- 1.0
 
- 
collectionTypeReturns 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.classor- Set.classdepending on whether the property shall accept duplicated values or not.
 
 
-