Package org.apache.sis.referencing.factory

## Class IdentifiedObjectFinder

- Object
- - IdentifiedObjectFinder

-     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)`

  Defined in the `sis-referencing` module

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `IdentifiedObjectFinder.Domain` | The domain of the search (for example whether to include deprecated objects in the search).

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected 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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Set<IdentifiedObject>` | `find​(IdentifiedObject object)` | Lookups objects which are approximately equal to the specified object.
    `IdentifiedObject` | `findSingleton​(IdentifiedObject object)` | Lookups only one object which is approximately equal to the specified object.
    `protected Set<String>` | `getCodeCandidates​(IdentifiedObject object)` | Returns a set of authority codes that may identify the same object than 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 Detail

    - #### factory

          protected final AuthorityFactory factory

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

  - ### Constructor Detail

    - #### IdentifiedObjectFinder

          protected IdentifiedObjectFinder​(AuthorityFactory factory)

      Creates a finder using the specified factory.
      Design 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 Detail

    - #### getSearchDomain

          public IdentifiedObjectFinder.Domain getSearchDomain()

      Returns the domain of the search (for example whether to include deprecated objects in the search). If `DECLARATION`, only a fast lookup based on embedded identifiers and names will be performed. Otherwise an exhaustive full scan against all registered objects 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, then 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.

    - #### find

          public Set<IdentifiedObject> find​(IdentifiedObject object)
                                     throws FactoryException

      Lookups objects which are approximately equal 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 a full scan of the dataset is allowed, then full set of candidate codes is used for creating objects to be tested.
      The created objects which are equal to the specified object in the the sense of `ComparisonMode​.APPROXIMATE` are returned.
      Parameters:
        `object` - the object looked up.
      Returns:
        the identified objects, or an empty set if not found.
      Throws:
        `FactoryException` - if an error occurred while creating an object.

    - #### findSingleton

          public IdentifiedObject findSingleton​(IdentifiedObject object)
                                         throws FactoryException

      Lookups 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 creating an object.

    - #### 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 `approximately equal` to the specified one. However the set may conservatively contains the code 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, 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.