org.geotoolkit.referencing.factory
Class IdentifiedObjectSet<T extends IdentifiedObject>

Object
  AbstractCollection<E>
      AbstractSet<T>
          IdentifiedObjectSet<T>

Type Parameters:

T - The type of objects to be included in this set.

All Implemented Interfaces:

Serializable, Iterable<T>, Collection<T>, Set<T>

@NotThreadSafe
public class IdentifiedObjectSet<T extends IdentifiedObject>
extends AbstractSet<T>
implements Serializable

A lazy set of identified objects. This set creates IdentifiedObjects from authority codes only when first needed. This class is typically used as the set returned by implementations of the CoordinateOperationAuthorityFactory.createFromCoordinateReferenceSystemCodes(String, String) method. Deferred creation in this case may have great performance impact since a set can contains about 40 entries (e.g. transformations from "ED50" (EPSG:4230) to "WGS 84" (EPSG:4326)) while some users only want to look for the first entry (e.g. the default AuthorityBackedFactory implementation).

Note: This is mostly a helper class for implementors, especially the org.geotoolkit.referencing.factory.epsg package. This class is not expected to be useful to users.

Exception handling
If the underlying factory failed to creates an object because of an unsupported operation method (NoSuchIdentifierException), the exception is logged with the FINE level (because this is a recoverable failure) and the iteration continue. If the operation creation failed for any other kind of reason (FactoryException), then the exception is rethrown as an unchecked BackingStoreException. This default behavior can be changed if a subclass overrides the isRecoverableFailure method.

Serialization
Serialization of this class forces the immediate creation of all identified objects not yet created. The serialized set is disconnected from the underlying factory.

Since:

2.2

Version:

3.18

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

Serialized Form

Module:

referencing/geotk-referencing (download)

View source code for this class

Field Summary

protected Class<T>

type The type of objects included in this set.

Constructor Summary

IdentifiedObjectSet(AuthorityFactory factory, Class<T> type)
Creates an initially empty set.

Method Summary

boolean	add(T object) Ensures that this collection contains the specified object.
boolean	addAuthorityCode(String code) Ensures that this collection contains an object for the specified authority code.
void	clear() Removes all of the elements from this collection.
boolean	contains(Object object) Returns true if this collection contains the specified object.
protected T	createObject(String code) Creates an object for the specified authority code.
protected String	getAuthorityCode(T object) Returns the code to uses as a key for the specified object.
String[]	getAuthorityCodes() Returns the authority code of all objects in this set.
protected AuthorityFactory	getAuthorityFactory() Returns the authority factory used by the createObject method.
protected boolean	isRecoverableFailure(FactoryException exception) Returns true if the specified exception should be handled as a recoverable failure.
Iterator<T>	iterator() Returns an iterator over the objects in this set.
boolean	remove(Object object) Removes a single instance of the specified element from this collection, if it is present.
boolean	removeAll(Collection<?> collection) Removes from this collection all of its elements that are contained in the specified collection.
void	resolve(int n) Ensures that the n first objects in this set are created.
void	setAuthorityCodes(String[] codes) Sets the content of this set as an array of authority codes.
int	size() Returns the number of objects available in this set.
protected Object	writeReplace() Returns a serializable copy of this set.

Methods inherited from class AbstractSet

equals, hashCode

Methods inherited from class AbstractCollection

addAll, containsAll, isEmpty, retainAll, toArray, toArray, toString

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface Set

addAll, containsAll, isEmpty, retainAll, toArray, toArray

Field Detail

type

protected final Class<T extends IdentifiedObject> type

The type of objects included in this set.

Since:

3.00

Constructor Detail

IdentifiedObjectSet

public IdentifiedObjectSet(AuthorityFactory factory,
                           Class<T> type)

Creates an initially empty set. The IdentifiedObjects will be created when first needed using the specified factory.

Parameters:

factory - The factory to use for deferred IdentifiedObjects creations.

type - The type of objects included in this set.

Method Detail

clear

public void clear()

Removes all of the elements from this collection.

Specified by:

clear in interface Collection<T extends IdentifiedObject>

Specified by:

clear in interface Set<T extends IdentifiedObject>

Overrides:

clear in class AbstractCollection<T extends IdentifiedObject>

size

public int size()

Returns the number of objects available in this set. Note that this number may decrease during the iteration process if the creation of some identified objects failed.

Specified by:

size in interface Collection<T extends IdentifiedObject>

Specified by:

size in interface Set<T extends IdentifiedObject>

Specified by:

size in class AbstractCollection<T extends IdentifiedObject>

addAuthorityCode

public boolean addAuthorityCode(String code)

Ensures that this collection contains an object for the specified authority code. The identified object will be created from the specified code only when first needed.

Parameters:

code - The code authority code that shall be included in this set.

Returns:

true if this set changed as a result of this call.

add

public boolean add(T object)

Ensures that this collection contains the specified object. This set does not allow multiple objects for the same authority code. If this set already contains an object using the same authority code than the specified one, then the old object is replaced by the new one even if the objects are not otherwise identical.

Specified by:

add in interface Collection<T extends IdentifiedObject>

Specified by:

add in interface Set<T extends IdentifiedObject>

Overrides:

add in class AbstractCollection<T extends IdentifiedObject>

Parameters:

object - The object to add to the set.

Returns:

true if this set changed as a result of this call.

contains

public boolean contains(Object object)

Returns true if this collection contains the specified object.

Specified by:

contains in interface Collection<T extends IdentifiedObject>

Specified by:

contains in interface Set<T extends IdentifiedObject>

Overrides:

contains in class AbstractCollection<T extends IdentifiedObject>

Parameters:

object - The object to test for presence in this set.

Returns:

true if the given object is presents in this set.

remove

public boolean remove(Object object)

Removes a single instance of the specified element from this collection, if it is present.

Specified by:

remove in interface Collection<T extends IdentifiedObject>

Specified by:

remove in interface Set<T extends IdentifiedObject>

Overrides:

remove in class AbstractCollection<T extends IdentifiedObject>

Parameters:

object - The object to remove from this set.

Returns:

true if this set changed as a result of this call.

removeAll

public boolean removeAll(Collection<?> collection)

Removes from this collection all of its elements that are contained in the specified collection.

Specified by:

removeAll in interface Collection<T extends IdentifiedObject>

Specified by:

removeAll in interface Set<T extends IdentifiedObject>

Overrides:

removeAll in class AbstractSet<T extends IdentifiedObject>

Parameters:

collection - The objects to remove from this set.

Returns:

true if this set changed as a result of this call.

iterator

public Iterator<T> iterator()
                                              throws BackingStoreException

Returns an iterator over the objects in this set. If the iteration encounter any kind of FactoryException other than NoSuchIdentifierException, then the exception will be rethrown as an unchecked BackingStoreException.

Specified by:

iterator in interface Iterable<T extends IdentifiedObject>

Specified by:

iterator in interface Collection<T extends IdentifiedObject>

Specified by:

iterator in interface Set<T extends IdentifiedObject>

Specified by:

iterator in class AbstractCollection<T extends IdentifiedObject>

Throws:

BackingStoreException - if the underlying factory failed to creates the first coordinate operation in the set.

resolve

public void resolve(int n)
             throws FactoryException

Ensures that the n first objects in this set are created. This method is typically invoked after some calls to addAuthorityCode(java.lang.String) in order to make sure that the underlying factory is really capable to create at least one object. FactoryException (except the ones accepted as recoverable failures) are thrown as if they were never wrapped into BackingStoreException.

Parameters:

n - The number of object to resolve. If this number is equals or greater than the set's size, then the creation of all objects is guaranteed successful.

Throws:

FactoryException - if an object creation failed.

getAuthorityCodes

public String[] getAuthorityCodes()

Returns the authority code of all objects in this set. The returned array contains the codes in iteration order. This method does not trig the creation of any new object.

This method is typically used together with setAuthorityCodes(java.lang.String[]) for altering the iteration order on the basis of authority codes.

Returns:

The authority codes in iteration order.

setAuthorityCodes

public void setAuthorityCodes(String[] codes)

Sets the content of this set as an array of authority codes. For any code in the given list, this method will preserve the corresponding identified object if it was already created. Other objects will be created only when first needed, as usual in this IdentifiedObjectSet implementation.

This method is typically used together with getAuthorityCodes() for altering the iteration order on the basis of authority codes. If the specified codes array contains the same elements than getAuthorityCodes() in a different order, then this method just set the new ordering.

Parameters:

codes - The authority codes of identified objects to store in this set.

See Also:

addAuthorityCode(java.lang.String)

getAuthorityCode

protected String getAuthorityCode(T object)

Returns the code to uses as a key for the specified object. The default implementation returns the code of the first identifier, if any, or the code of the primary name otherwise. Subclasses may override this method if they want to use a different key for this set.

Parameters:

object - The object for which to get the authority code.

Returns:

The authority code of the given identified object.

getAuthorityFactory

protected AuthorityFactory getAuthorityFactory()

Returns the authority factory used by the createObject method. This is the factory given at construction time.

Returns:

The authority factory.

Since:

3.00

createObject

protected T createObject(String code)
                                           throws FactoryException

Creates an object for the specified authority code. This method is invoked during the iteration process if an object was not already created.

Parameters:

code - The code for which to create the identified object.

Returns:

The identified object created from the given code.

Throws:

FactoryException - If the object creation failed.

isRecoverableFailure

protected boolean isRecoverableFailure(FactoryException exception)

Returns true if the specified exception should be handled as a recoverable failure. This method is invoked during the iteration process if the factory failed to create some objects. If this method returns true for the given exception, then the exception will be logged in the Geotk factory logger with the FINE level. If this method returns false, then the exception will be retrown as a BackingStoreException.

The default implementation returns true if the given exception is one of the following types:

• NoSuchIdentifierException but not NoSuchAuthorityCodeException
• OptionalFactoryOperationException

Parameters:

exception - The exception that occurred while creating an object.

Returns:

true if the given exception should be considered recoverable, or false if it should be considered fatal.

writeReplace

protected Object writeReplace()
                       throws ObjectStreamException

Returns a serializable copy of this set. This method is invoked automatically during serialization. The serialized set of identified objects is disconnected from the underlying factory.

Returns:

The object to write in replacement of this set.

Throws:

ObjectStreamException - If this set can not be serialized.