org.geotoolkit.metadata
Class ModifiableMetadata

Object
  extended by AbstractMetadata
      extended by ModifiableMetadata
All Implemented Interfaces:
Cloneable, LenientComparable
Direct Known Subclasses:
MetadataEntity

Deprecated. Moved to the org.apache.sis.metadata package.

@Deprecated
public abstract class ModifiableMetadata
extends AbstractMetadata
implements Cloneable

Base class for metadata that may (or may not) be modifiable. Implementations will typically provide set*(...) methods for each corresponding get*() method. An initially modifiable metadata may become unmodifiable at a later stage (typically after its construction is completed) by the call to the freeze() method.


Guidline for implementors
Subclasses should follow the pattern below for every get and set methods, with a special processing for collections:

private Foo property;

public Foo getProperty() {
    return property;
}

public synchronized void setProperty(Foo newValue) {
    checkWritePermission();
    property = newValue;
}
For collections (note that the call to checkWritePermission() is implicit):
private Collection<Foo> properties;

public synchronized Collection<Foo> getProperties() {
    return properties = nonNullCollection(properties, Foo.class);
}

public synchronized void setProperties(Collection<Foo> newValues) {
    properties = copyCollection(newValues, properties, Foo.class);
}

Since:
2.4
Version:
3.20
Author:
Martin Desruisseaux (Geomatys)
Module:
metadata/geotk-metadata (download)    View source code for this class

Field Summary
 
Fields inherited from class AbstractMetadata
LOGGER
 
Constructor Summary
protected ModifiableMetadata()
          Deprecated. Constructs an initially empty metadata.
protected ModifiableMetadata(Object source)
          Deprecated. Constructs a metadata entity initialized with the values from the specified metadata.
 
Method Summary
protected  void checkWritePermission()
          Deprecated. Checks if changes in the metadata are allowed.
protected  ModifiableMetadata clone()
          Deprecated. Returns a shallow copy of this metadata.
protected
<E> Class<? extends Collection<E>>
collectionType(Class<E> elementType)
          Deprecated. Returns the type of collection to use for the given type.
protected
<E> Collection<E>
copyCollection(Collection<? extends E> source, Collection<E> target, Class<E> elementType)
          Deprecated. Copies the content of one collection (source) into an other (target).
protected
<E> List<E>
copyList(Collection<? extends E> source, List<E> target, Class<E> elementType)
          Deprecated. Copies the content of one list (source) into an other (target).
protected
<E> Set<E>
copySet(Collection<? extends E> source, Set<E> target, Class<E> elementType)
          Deprecated. Copies the content of one Set (source) into an other (target).
 void freeze()
          Deprecated. Declares this metadata and all its attributes as unmodifiable.
 boolean isModifiable()
          Deprecated. Returns true if this metadata is modifiable.
protected
<E> Collection<E>
nonNullCollection(Collection<E> c, Class<E> elementType)
          Deprecated. Returns the specified collection, or a new one if c is null.
protected
<E> List<E>
nonNullList(List<E> c, Class<E> elementType)
          Deprecated. Returns the specified list, or a new one if c is null.
protected
<E> Set<E>
nonNullSet(Set<E> c, Class<E> elementType)
          Deprecated. Returns the specified set, or a new one if c is null.
 void prune()
          Deprecated. Removes all references to empty properties.
 AbstractMetadata unmodifiable()
          Deprecated. Returns an unmodifiable copy of this metadata.
 
Methods inherited from class AbstractMetadata
asMap, asTree, asTreeTable, equals, equals, getInterface, getStandard, hashCode, isEmpty, parse, toString
 
Methods inherited from class Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ModifiableMetadata

protected ModifiableMetadata()
Deprecated. 
Constructs an initially empty metadata.


ModifiableMetadata

protected ModifiableMetadata(Object source)
                      throws ClassCastException,
                             UnmodifiableMetadataException
Deprecated. 
Constructs a metadata entity initialized with the values from the specified metadata. This constructor behavior is as in superclass constructor.

Parameters:
source - The metadata to copy values from, or null if none.
Throws:
ClassCastException - if the specified metadata don't implements the expected metadata interface.
UnmodifiableMetadataException - if this class don't define set methods corresponding to the get methods found in the implemented interface, or if this instance is not modifiable for some other reason.
Method Detail

clone

protected ModifiableMetadata clone()
                            throws CloneNotSupportedException
Deprecated. 
Returns a shallow copy of this metadata.

Usage
While cloneable, this class do not provides the clone() operation as part of the public API. The clone operation is required for the internal working of the unmodifiable() method, which needs shallow copies of metadata entities. The default Object.clone() implementation is sufficient in most cases.

Overrides:
clone in class Object
Returns:
A shallow copy of this metadata.
Throws:
CloneNotSupportedException - if the clone is not supported.

prune

public void prune()
           throws UnmodifiableMetadataException
Deprecated. 
Removes all references to empty properties. The default implementation iterates over all non null properties using Java reflection, and sets to null the properties for which isEmpty() returned true.

Throws:
UnmodifiableMetadataException - If this metadata is not modifiable.
Since:
3.20

isModifiable

public final boolean isModifiable()
Deprecated. 
Returns true if this metadata is modifiable. This method returns false if freeze() has been invoked on this object.

Returns:
true if this metadata is modifiable.
See Also:
freeze(), checkWritePermission()

unmodifiable

public AbstractMetadata unmodifiable()
Deprecated. 
Returns an unmodifiable copy of this metadata. Any attempt to modify a property of the returned object will throw an UnmodifiableMetadataException. The state of this object is not modified.

This method is useful for reusing the same metadata object as a template. For example:

DefaultCitation myCitation = new DefaultCitation();
myCitation.setTitle(new SimpleInternationalString("The title of my book"));
myCitation.setEdition(new SimpleInternationalString("First edition"));
final Citation firstEdition = (Citation) myCitation.unmodifiable();

myCitation.setEdition(new SimpleInternationalString("Second edition"));
final Citation secondEdition = (Citation) myCitation.unmodifiable();
// The title of the second edition is unchanged compared to the first edition.
The default implementation makes the following choice:

Returns:
An unmodifiable copy of this metadata.

freeze

public void freeze()
Deprecated. 
Declares this metadata and all its attributes as unmodifiable. Any attempt to modify a property after this method call will throw an UnmodifiableMetadataException. If this metadata is already unmodifiable, then this method does nothing.

Subclasses usually don't need to override this method since the default implementation performs its work using Java reflection.

See Also:
isModifiable(), checkWritePermission()

checkWritePermission

protected void checkWritePermission()
                             throws UnmodifiableMetadataException
Deprecated. 
Checks if changes in the metadata are allowed. All setFoo(...) methods in subclasses should invoke this method (directly or indirectly) before to apply any change.

Throws:
UnmodifiableMetadataException - if this metadata is unmodifiable.
See Also:
isModifiable(), freeze()

copyList

protected final <E> List<E> copyList(Collection<? extends E> source,
                                     List<E> target,
                                     Class<E> elementType)
                          throws UnmodifiableMetadataException
Deprecated. 
Copies the content of one list (source) into an other (target). This method performs the following steps:

Type Parameters:
E - The type of elements in the list.
Parameters:
source - The source list, or null.
target - The target list, or null if not yet created.
elementType - The base type of elements to put in the list.
Returns:
A list (possibly the target instance) containing the source elements, or null if the source was null.
Throws:
UnmodifiableMetadataException - if this metadata is unmodifiable.
Since:
2.5
See Also:
nonNullList(List, Class)

copySet

protected final <E> Set<E> copySet(Collection<? extends E> source,
                                   Set<E> target,
                                   Class<E> elementType)
                        throws UnmodifiableMetadataException
Deprecated. 
Copies the content of one Set (source) into an other (target). This method performs the following steps:

Type Parameters:
E - The type of elements in the set.
Parameters:
source - The source set, or null.
target - The target set, or null if not yet created.
elementType - The base type of elements to put in the set.
Returns:
A set (possibly the target instance) containing the source elements, or null if the source was null.
Throws:
UnmodifiableMetadataException - if this metadata is unmodifiable.
Since:
3.02
See Also:
nonNullSet(Set, Class)

copyCollection

protected final <E> Collection<E> copyCollection(Collection<? extends E> source,
                                                 Collection<E> target,
                                                 Class<E> elementType)
                                      throws UnmodifiableMetadataException
Deprecated. 
Copies the content of one collection (source) into an other (target). This method performs the following steps:

Choosing a collection type
Implementations shall invoke copyList or copySet instead than 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 implementor choice. The default implementation invokes collectionType(Class) in order to get a hint about whatever a List or a Set should be used.

Type Parameters:
E - The type of elements in the collection.
Parameters:
source - The source collection, or null.
target - The target collection, or null if not yet created.
elementType - The base type of elements to put in the collection.
Returns:
A collection (possibly the target instance) containing the source elements, or null if the source was null.
Throws:
UnmodifiableMetadataException - if this metadata is unmodifiable.

nonNullList

protected final <E> List<E> nonNullList(List<E> c,
                                        Class<E> elementType)
Deprecated. 
Returns the specified list, or a new one if c is null. This is a convenience method for implementation of getFoo() methods.

Special cases
The general contract of this method is to never return null. However this method may exceptionally returns null during XML marshalling or during copy operations. The intend is to reduce the amount of empty object creations and should be invisible from the public API.

Type Parameters:
E - The type of elements in the list.
Parameters:
c - The list to checks.
elementType - The element type (used only if c is null).
Returns:
c, or a new list if c is null.

nonNullSet

protected final <E> Set<E> nonNullSet(Set<E> c,
                                      Class<E> elementType)
Deprecated. 
Returns the specified set, or a new one if c is null. This is a convenience method for implementation of getFoo() methods.

Special cases
The general contract of this method is to never return null. However this method may exceptionally returns null during XML marshalling or during copy operations. The intend is to reduce the amount of empty object creations and should be invisible from the public API.

Type Parameters:
E - The type of elements in the set.
Parameters:
c - The set to checks.
elementType - The element type (used only if c is null).
Returns:
c, or a new set if c is null.
Since:
2.5

nonNullCollection

protected final <E> Collection<E> nonNullCollection(Collection<E> c,
                                                    Class<E> elementType)
Deprecated. 
Returns the specified collection, or a new one if c is null. This is a convenience method for implementation of getFoo() methods.

Choosing a collection type
Implementations shall invoke nonNullList or nonNullSet instead than 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 implementor choice. The default implementation invokes collectionType(Class) in order to get a hint about whatever a List or a Set should be used.

Special cases
The general contract of this method is to never return null. However this method may exceptionally returns null during XML marshalling or during copy operations. The intend is to reduce the amount of empty object creations and should be invisible from the public API.

Type Parameters:
E - The type of elements in the collection.
Parameters:
c - The collection to checks.
elementType - The element type (used only if c is null).
Returns:
c, or a new collection if c is null.

collectionType

protected <E> Class<? extends Collection<E>> collectionType(Class<E> elementType)
Deprecated. 
Returns the type of collection to use for the given type. The current implementation can return only two values: Set.class if the attribute should not accept duplicated values, or List.class otherwise. Future Geotk versions may accept other types.

The default implementation returns Set.class if the element type is assignable to Enum or CodeList, and List.class otherwise. Subclasses can override this method for choosing different kind of collections. Note however that Set should 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.class or Set.class depending on whatever the attribute shall accept duplicated values or not.
Since:
3.18


Copyright © 2009-2013 Geotoolkit.org. All Rights Reserved.