# Class IdentifiedObjectFinder

Object
IdentifiedObjectFinder

Direct Known Subclasses:
  `IdentifiedObjectFinder​.Wrapper`

public class IdentifiedObjectFinder extends Object
Searches in an authority factory for objects approximately equal to a given object. This class can be used for fetching a fully defined identified object from an incomplete one, for example from an object without "`ID[…]`" or "`AUTHORITY[…]`" element in Well Known Text.

The steps for using `IdentifiedObjectFinder` are:

1. Get a new instance by calling `GeodeticAuthorityFactory​.newIdentifiedObjectFinder()`.
2. Optionally configure that instance by calling its setter methods.
3. Perform a search by invoking the `find(IdentifiedObject)` or `findSingleton(IdentifiedObject)` method.
4. The same `IdentifiedObjectFinder` instance can be reused 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:
  0.7
See Also:
  - `GeodeticAuthorityFactory​.newIdentifiedObjectFinder()`
  - `IdentifiedObjects​.newFinder(String)`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `IdentifiedObjectFinder​.Domain`
  The domain of the search (for example, whether to include deprecated objects in the search).
  `static class`
  `IdentifiedObjectFinder​.Wrapper`
  An object finder which delegates some or all work to another object finder.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final AuthorityFactory`
  `factory`
  The factory to use for creating objects.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `IdentifiedObjectFinder(AuthorityFactory factory)`
  Creates a finder using the specified factory.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Set<IdentifiedObject>`
  `find(IdentifiedObject object)`
  Looks up objects which are approximately equal to the specified object.
  `IdentifiedObject`
  `findSingleton(IdentifiedObject object)`
  Looks up only one object which is approximately equal to the specified object.
  `protected Iterable<String>`
  `getCodeCandidates(IdentifiedObject object)`
  Returns a set of authority codes that may identify the same object as the specified one.
  `IdentifiedObjectFinder​.Domain`
  `getSearchDomain()`
  Returns the domain of the search (for example, whether to include deprecated objects in the search).
  `boolean`
  `isIgnoringAxes()`
  Returns `true` if the search should ignore coordinate system axes.
  `void`
  `setIgnoringAxes(boolean ignore)`
  Sets whether the search should ignore coordinate system axes.
  `void`
  `setSearchDomain(IdentifiedObjectFinder​.Domain domain)`
  Sets the domain of the search (for example, whether to include deprecated objects in the search).

  ### Methods inherited from class Object

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

- ## Field Details

  - ### factory

    protected final AuthorityFactory factory
    The factory to use for creating objects. This is the factory specified at construction time.

- ## Constructor Details

  - ### IdentifiedObjectFinder

    protected IdentifiedObjectFinder(AuthorityFactory factory)
    Creates a finder using the specified factory.

    #### API note

    This constructor is protected because instances of this class should not be created directly. Use `GeodeticAuthorityFactory​.newIdentifiedObjectFinder()` instead.
    Parameters:
      `factory` - the factory to scan for the identified objects.
    See Also:
      - `GeodeticAuthorityFactory​.newIdentifiedObjectFinder()`

- ## Method Details

  - ### getSearchDomain

    public IdentifiedObjectFinder.Domain getSearchDomain()
    Returns the domain of the search (for example, whether to include deprecated objects in the search). If the domain is `DECLARATION`, then the `find(…)` method will only perform a fast lookup based on the identifiers and the names of the object to search. Otherwise, an exhaustive scan of the geodetic dataset will be performed (may be slow).

    The default value is `IdentifiedObjectFinder​.Domain​.VALID_DATASET`.

    Returns:
      the domain of the search.

  - ### setSearchDomain

    public void setSearchDomain(IdentifiedObjectFinder.Domain domain)
    Sets the domain of the search (for example, whether to include deprecated objects in the search). If this method is never invoked, the default value is `IdentifiedObjectFinder​.Domain​.VALID_DATASET`.
    Parameters:
      `domain` - the domain of the search.

  - ### isIgnoringAxes

    public boolean isIgnoringAxes()
    Returns `true` if the search should ignore coordinate system axes. The default value is `false`.
    Returns:
      `true` if the search should ignore coordinate system axes.

  - ### setIgnoringAxes

    public void setIgnoringAxes(boolean ignore)
    Sets whether the search should ignore coordinate system axes. If this property is set to `true`, then the search will compare only the coordinate system type and dimension. The axis names, orientation and units will be ignored. For example, the `find(…)` method may return a Coordinate Reference System object with (latitude, longitude) axes even if the given object had (longitude, latitude) axes.
    Parameters:
      `ignore` - `true` if the search should ignore coordinate system axes.

  - ### findSingleton

    @OptionalCandidate public IdentifiedObject findSingleton(IdentifiedObject object) throws FactoryException
    Looks up only one object which is approximately equal to the specified object. This method invokes `find(IdentifiedObject)`, then examine the returned `Set` as below:
    - If the set is empty, then this method returns `null`.
    - If the set contains exactly one element, then this method returns that element.
    - If the set contains more than one element, but only one element has the same axis order than `object` and all other elements have different axis order, then this method returns the single element having the same axis order.
    - Otherwise this method considers that there is ambiguity and returns `null`.
    Parameters:
      `object` - the object looked up.
    Returns:
      the identified object, or `null` if none or ambiguous.
    Throws:
      `FactoryException` - if an error occurred while fetching the authority code candidates.

  - ### find

    public Set<IdentifiedObject> find(IdentifiedObject object) throws FactoryException
    Looks up objects which are approximately equal to the specified object. This method tries to instantiate objects identified by the set of candidate codes using the authority factory specified at construction time. `FactoryException`s thrown during object creations are logged and otherwise ignored. The successfully created objects which are equal to the specified object in the sense of `ComparisonMode​.APPROXIMATE` or `ALLOW_VARIANT` (depending on whether axes are ignored) are included in the returned set.

    #### Exception handling

    This method may return a lazy set, in which case some checked exceptions may occur at iteration time. These exceptions are wrapped in a `BackingStoreException`.
    Parameters:
      `object` - the object looked up.
    Returns:
      the identified objects, or an empty set if not found.
    Throws:
      `FactoryException` - if an error occurred while fetching the authority code candidates.

  - ### getCodeCandidates

    protected Iterable<String> getCodeCandidates(IdentifiedObject object) throws FactoryException
    Returns a set of authority codes that may identify the same object as the specified one. The codes may be determined from object identifiers, names, aliases or extensive search in the geodetic dataset. The effort in populating the returned set is specified by the search domain. The returned set should contain at least the codes of every objects in the search domain that are approximately equal to the specified object. However, the set may conservatively contain the codes for more objects if an exact search is too expensive.

    This method is invoked by the default `find(IdentifiedObject)` method implementation. The caller iterates through the returned codes, instantiates the objects and compares them with the specified object in order to determine which codes are really matching. The iteration order should be the preference order.

    #### Exceptions during iteration

    An unchecked `BackingStoreException` may be thrown during the iteration if the implementation fetches the codes lazily (when first needed) from the authority factory, and that action failed. The exception cause is often the checked `FactoryException`.

    #### Default implementation

    The default implementation returns codes defined from `object​.getIdentifiers()`, or `factory​.getAuthorityCodes(type)` where `type` is derived from `object` class, or a combination of both collection, depending on the search domain. 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.
    See Also:
      - `IdentifiedObject​.getIdentifiers()`
      - `AuthorityFactory​.getAuthorityCodes(Class)`