org.geotoolkit.referencing.factory
Class IdentifiedObjectFinder

Object
  IdentifiedObjectFinder

@NotThreadSafe
public class IdentifiedObjectFinder
extends Object

Lookups an object from an authority factory which is equal, ignoring metadata, to the specified object. The main purpose of this class is to get a fully identified object from an incomplete one, for example from an object without identifiers ("AUTHORITY[...]" element in Well Known Text terminology).

The steps for using IdentifiedObjectFinder are:

1. Get a new instance by calling AbstractAuthorityFactory.getIdentifiedObjectFinder(Class).
2. Optionally configure that instance by calling its setter methods.
3. Perform a search by invoking the find(IdentifiedObject) or findIdentifier(IdentifiedObject) methods.
4. Reuse the same IdentifiedObjectFinder instance for consecutive searches.

Thread safety
IdentifiedObjectFinder are not guaranteed to be thread-safe even if the underlying factory is thread-safe. If concurrent searches are desired, then a new instance should be created for each thread.

Since:

2.4

Version:

3.18

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

AbstractAuthorityFactory.getIdentifiedObjectFinder(Class), CRS#lookupIdentifier(IdentifiedObject, boolean)

Module:

referencing/geotk-referencing (download)

View source code for this class

Constructor Summary

protected

IdentifiedObjectFinder(AuthorityFactory factory, Class<? extends IdentifiedObject> type) Creates a finder using the specified factory.

Method Summary

protected IdentifiedObject	create(String code, int attempt) Creates an object for the given code.
IdentifiedObject	find(IdentifiedObject object) Lookups an object which is equal, ignoring metadata, to the specified object.
protected IdentifiedObject	findFromParent(IdentifiedObject object, Class<? extends IdentifiedObject> type) Lookups an object from the parent finder, of from this finder if there is no parent.
String	findIdentifier(IdentifiedObject object) Returns the identifier of the specified object, or null if none.
Citation	getAuthority() Returns the authority of the factory examined by this finder.
protected Set<String>	getCodeCandidates(IdentifiedObject object) Returns a set of authority codes that may identify the same object than the specified one.
ComparisonMode	getComparisonMode() Returns the criterion used for determining if a candidate found by this IdentifiedObjectFinder shall be considered equals to the requested object.
boolean	isFullScanAllowed() If true, an exhaustive full scan against all registered objects will be performed (may be slow).
void	setComparisonMode(ComparisonMode mode) Sets the criterion used for determining if a candidate found by this IdentifiedObjectFinder shall be considered equals to the requested object.
void	setFullScanAllowed(boolean fullScan) Sets whatever an exhaustive scan against all registered objects is allowed.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IdentifiedObjectFinder

protected IdentifiedObjectFinder(AuthorityFactory factory,
                                 Class<? extends IdentifiedObject> type)

Creates a finder using the specified factory. This constructor is protected because instances of this class should not be created directly. Use AbstractAuthorityFactory.getIdentifiedObjectFinder(Class) instead.

Parameters:

factory - The factory to scan for the identified objects.

type - The type of objects to lookup.

See Also:

AbstractAuthorityFactory.getIdentifiedObjectFinder(Class)

Method Detail

getAuthority

public Citation getAuthority()
                      throws FactoryException

Returns the authority of the factory examined by this finder.

Returns:

The authority of the factory used for the searches.

Throws:

FactoryException - If an error occurred while fetching the authority.

getComparisonMode

public ComparisonMode getComparisonMode()

Returns the criterion used for determining if a candidate found by this IdentifiedObjectFinder shall be considered equals to the requested object. The default value is ComparisonMode.IGNORE_METADATA.

Returns:

The criterion to use for comparing objects.

Since:

3.18

setComparisonMode

public void setComparisonMode(ComparisonMode mode)

Sets the criterion used for determining if a candidate found by this IdentifiedObjectFinder shall be considered equals to the requested object.

Parameters:

mode - The criterion to use for comparing objects.

Since:

3.18

isFullScanAllowed

public boolean isFullScanAllowed()

If true, an exhaustive full scan against all registered objects will be performed (may be slow). Otherwise only a fast lookup based on embedded identifiers and names will be performed. The default value is true.

Returns:

true if exhaustive scans are allowed, or false for faster but less complete searches.

setFullScanAllowed

public void setFullScanAllowed(boolean fullScan)

Sets whatever an exhaustive scan against all registered objects is allowed. The default value is true.

Parameters:

fullScan - true for allowing exhaustive scans, or false for faster but less complete searches.

find

public IdentifiedObject find(IdentifiedObject object)
                      throws FactoryException

Lookups an object which is equal, ignoring metadata, to the specified object. The default implementation tries to instantiate some identified objects from the authority factory specified at construction time, in the following order:

• If the specified object contains identifiers associated to the same authority than the factory, then those identifiers are used for creating objects to be tested.
• If the authority factory can create objects from their name in addition of identifiers, then the name and aliases are used for creating objects to be tested.
• If full scan is allowed, then full set of authority codes are used for creating objects to be tested.

The first of the above created objects which is equal to the specified object in the the sense of equalsIgnoreMetadata is returned.

Parameters:

object - The object looked up.

Returns:

The identified object, or null if not found.

Throws:

FactoryException - if an error occurred while creating an object.

findIdentifier

public String findIdentifier(IdentifiedObject object)
                      throws FactoryException

Returns the identifier of the specified object, or null if none. The default implementation invokes find(object) and extracts the code from the returned identified object.

Parameters:

object - The object looked up.

Returns:

The identifier of the given object, or null if none were found.

Throws:

FactoryException - if an error occurred while creating an object.

findFromParent

protected final IdentifiedObject findFromParent(IdentifiedObject object,
                                                Class<? extends IdentifiedObject> type)
                                         throws FactoryException

Lookups an object from the parent finder, of from this finder if there is no parent. A parent finder exists only if this finder is wrapped by an other finder. The parent can be the CachingAuthorityFactory finder or AuthorityFactoryAdapter finder.

This method should be considered as an implementation details. It is visible because it is needed by DirectEpsgFactory, which is defined in an other package. User should not rely on this method.

The main purpose of this method is to allow DirectAuthorityFactory implementations to look for dependencies while leveraging the cache managed by their CachingAuthorityFactory wrappers.

Parameters:

object - The object looked up.

type - The type of object to look for. It doesn't need to be the type specified at construction time. This relaxation exists in order to allow dependencies lookup, since the dependencies may be of different kinds.

Returns:

The identified object, or null if not found.

Throws:

FactoryException - if an error occurred while creating an object.

Since:

3.18

create

protected IdentifiedObject create(String code,
                                  int attempt)
                           throws FactoryException

Creates an object for the given code. This method is invoked by the default implementation of the find(IdentifiedObject) and findIdentifier(IdentifiedObject) methods. The method is invoked at least once for each code returned by the getCodeCandidates(IdentifiedObject) method, in iteration order, until an object equals (ignoring metadata) to the requested object is found.

This method may be invoked more than once for the same code. On the first invocation, the attempt argument is 0. If the returned object is not equals (ignoring metadata) to the requested object, then this method is invoked again with increasing values of the attempt argument until this method returns null, which means that every possible objects for the given code has been created. The purpose is to test various flavor of the same object (for example with the axis order forced to "longitude first" or not).

The default implementation delegates to the factory given at construction time only for the first attempt (attempt == 0), and returns null in all other cases.

Overriding
This method is aimed to be overridden, but subclasses shall not override it with caching service. For example do not delegate the creation to a CachingAuthorityFactory instance.

Parameters:

code - The authority code for which to create an object.

attempt - The number of previous attempt before this one.

Returns:

The identified object for the given code, or null to stop attempts.

Throws:

FactoryException - if an error occurred while creating the object.

Since:

3.10

getCodeCandidates

protected Set<String> getCodeCandidates(IdentifiedObject object)
                                 throws FactoryException

Returns a set of authority codes that may identify the same object than the specified one. The returned set must contains at least the code of every objects that are equal, ignoring metadata, to the specified one. However the set is not required to contains only the codes of those objects; it may conservatively contains the code for more objects if an exact search is too expensive.

This method is invoked by the default find method implementation. The caller iterates through the returned codes, instantiate the objects and compare them with the specified one in order to determine which codes are really applicable. The iteration stops as soon as a match is found (in other words, if more than one object is equals to the specified one, then the find method selects the first one in iteration order).

Default implementation
The default implementation returns the same set than getAuthorityCodes(type) where type is the interface specified at construction type. Subclasses should override this method in order to return a smaller set, if they can.

Parameters:

object - The object looked up.

Returns:

A set of code candidates.

Throws:

FactoryException - if an error occurred while fetching the set of code candidates.