org.geotools.metadata
Class ModifiableMetadata

java.lang.Object
  extended by org.geotools.metadata.AbstractMetadata
      extended by org.geotools.metadata.ModifiableMetadata
All Implemented Interfaces:
java.lang.Cloneable
Direct Known Subclasses:
MetadataEntity

public abstract class ModifiableMetadata
extends AbstractMetadata
implements java.lang.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.

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:
$Id: ModifiableMetadata.java 30852 2008-07-03 15:59:42Z desruisseaux $
Author:
Martin Desruisseaux

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

Constructor Detail

ModifiableMetadata

protected ModifiableMetadata()
Constructs an initially empty metadata.


ModifiableMetadata

protected ModifiableMetadata(java.lang.Object source)
                      throws java.lang.ClassCastException,
                             UnmodifiableMetadataException
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.
Throws:
java.lang.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

isModifiable

public final boolean isModifiable()
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.

unmodifiable

public AbstractMetadata unmodifiable()
Returns an unmodifiable copy of this metadata. Any attempt to modify an attribute of the returned object will throw an UnmodifiableMetadataException. If this metadata is already unmodifiable, then this method returns this.

The default implementation clone this metadata and freeze the clone before to return it.

Returns:
An unmodifiable copy of this metadata.

freeze

public void freeze()
Declares this metadata and all its attributes as unmodifiable. This method is invoked automatically by the unmodifiable() method. Subclasses usually don't need to override it since the default implementation performs its work using Java reflection.


checkWritePermission

protected void checkWritePermission()
                             throws UnmodifiableMetadataException
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.

copyList

protected final <E> java.util.List<E> copyList(java.util.Collection<? extends E> source,
                                               java.util.List<E> target,
                                               java.lang.Class<E> elementType)
                                    throws UnmodifiableMetadataException
Copies the content of one list (source) into an other (target). If the target list is null, a new target list is created.

A call to checkWritePermission() is implicit before the copy is performed.

Type Parameters:
E - The type of elements in the list.
Parameters:
source - The source list. null is synonymous to empty.
target - The target list, or null if not yet created.
elementType - The base type of elements to put in the list.
Returns:
target, or a newly created list.
Throws:
UnmodifiableMetadataException - if this metadata is unmodifiable.
Since:
2.5

copyCollection

protected final <E> java.util.Collection<E> copyCollection(java.util.Collection<? extends E> source,
                                                           java.util.Collection<E> target,
                                                           java.lang.Class<E> elementType)
                                                throws UnmodifiableMetadataException
Copies the content of one collection (source) into an other (target). If the target collection is null, or if its type (List vs Set) doesn't matches the type of the source collection, a new target collection is created.

A call to checkWritePermission() is implicit before the copy is performed.

Type Parameters:
E - The type of elements in the collection.
Parameters:
source - The source collection. null is synonymous to empty.
target - The target collection, or null if not yet created.
elementType - The base type of elements to put in the collection.
Returns:
target, or a newly created collection.
Throws:
UnmodifiableMetadataException - if this metadata is unmodifiable.

nonNullCollection

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

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.

nonNullSet

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

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

nonNullList

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

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.

clone

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

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 expect from clone() a shallow copy of this metadata entity. The default implementation of Object.clone() is suffisient for most use.

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


Copyright © 1996-2010 Geotools. All Rights Reserved.