AbstractMetadata
ModifiableMetadata
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Object
@ThreadSafe public abstract class ModifiableMetadata
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;
}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);
}
| metadata/geotk-metadata (download) | View source code for this class |
| Field Summary |
|---|
| Fields inherited from class AbstractMetadata |
|---|
LOGGER |
| Constructor Summary | |
|---|---|
protected |
ModifiableMetadata()
Constructs an initially empty metadata. |
protected |
ModifiableMetadata(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
|
collectionType(Class<E> elementType)
Returns the type of collection to use for the given type. |
|
protected
|
copyCollection(Collection<? extends E> source,
Collection<E> target,
Class<E> elementType)
Copies the content of one collection ( source) into an other (target). |
|
protected
|
copyList(Collection<? extends E> source,
List<E> target,
Class<E> elementType)
Copies the content of one list ( source) into an other (target). |
|
protected
|
copySet(Collection<? extends E> source,
Set<E> target,
Class<E> elementType)
Copies the content of one Set ( 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
|
nonNullCollection(Collection<E> c,
Class<E> elementType)
Returns the specified collection, or a new one if c is null. |
|
protected
|
nonNullList(List<E> c,
Class<E> elementType)
Returns the specified list, or a new one if c is null. |
|
protected
|
nonNullSet(Set<E> c,
Class<E> elementType)
Returns the specified set, or a new one if c is null. |
|
void |
prune()
Removes all references to empty properties. |
|
AbstractMetadata |
unmodifiable()
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 |
|---|
protected ModifiableMetadata()
protected ModifiableMetadata(Object source)
throws ClassCastException,
UnmodifiableMetadataException
source - The metadata to copy values from, or null if none.
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 |
|---|
protected ModifiableMetadata clone()
throws CloneNotSupportedException
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.
clone in class ObjectCloneNotSupportedException - if the clone is not supported.
public void prune()
throws UnmodifiableMetadataException
null the properties for which isEmpty() returned
true.
UnmodifiableMetadataException - If this metadata is not modifiable.public final boolean isModifiable()
true if this metadata is modifiable. This method returns
false if freeze() has been invoked on this object.
true if this metadata is modifiable.freeze(),
checkWritePermission()public AbstractMetadata unmodifiable()
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.
this
unchanged.
public void freeze()
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.
isModifiable(),
checkWritePermission()
protected void checkWritePermission()
throws UnmodifiableMetadataException
setFoo(...) methods in
subclasses should invoke this method (directly or indirectly) before to apply any
change.
UnmodifiableMetadataException - if this metadata is unmodifiable.isModifiable(),
freeze()
protected final <E> List<E> copyList(Collection<? extends E> source,
List<E> target,
Class<E> elementType)
throws UnmodifiableMetadataException
source) into an other (target).
This method performs the following steps:
checkWritePermission() in order to ensure that this metadata is
modifiable.source is null or
empty, returns null (meaning that the metadata is not provided).target is null, creates a new List.source into the target.
E - The type of elements in the list.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.
target instance) containing the source
elements, or null if the source was null.
UnmodifiableMetadataException - if this metadata is unmodifiable.nonNullList(List, Class)
protected final <E> Set<E> copySet(Collection<? extends E> source,
Set<E> target,
Class<E> elementType)
throws UnmodifiableMetadataException
source) into an other (target).
This method performs the following steps:
checkWritePermission() in order to ensure that this metadata is
modifiable.source is null or
empty, returns null (meaning that the metadata is not provided).target is null, creates a new Set.source into the target.
E - The type of elements in the set.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.
target instance) containing the source
elements, or null if the source was null.
UnmodifiableMetadataException - if this metadata is unmodifiable.nonNullSet(Set, Class)
protected final <E> Collection<E> copyCollection(Collection<? extends E> source,
Collection<E> target,
Class<E> elementType)
throws UnmodifiableMetadataException
source) into an other (target).
This method performs the following steps:
checkWritePermission() in order to ensure that this metadata is
modifiable.source is null or
empty, returns null (meaning that the metadata is not provided).target is null, creates a new Set or a new List
depending on the value returned by collectionType(Class).source into the target.
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.
E - The type of elements in the collection.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.
target instance) containing the source
elements, or null if the source was null.
UnmodifiableMetadataException - if this metadata is unmodifiable.
protected final <E> List<E> nonNullList(List<E> c,
Class<E> elementType)
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.
E - The type of elements in the list.c - The list to checks.elementType - The element type (used only if c is null).
c, or a new list if c is null.
protected final <E> Set<E> nonNullSet(Set<E> c,
Class<E> elementType)
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.
E - The type of elements in the set.c - The set to checks.elementType - The element type (used only if c is null).
c, or a new set if c is null.
protected final <E> Collection<E> nonNullCollection(Collection<E> c,
Class<E> elementType)
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.
E - The type of elements in the collection.c - The collection to checks.elementType - The element type (used only if c is null).
c, or a new collection if c is null.protected <E> Class<? extends Collection<E>> collectionType(Class<E> elementType)
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.
E - The type of elements in the collection to be created.elementType - The type of elements in the collection to be created.
List.class or Set.class depending on whatever the
attribute shall accept duplicated values or not.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||