Package org.apache.sis.referencing.factory

Class IdentifiedObjectFinder

java.lang.Object
org.apache.sis.referencing.factory.IdentifiedObjectFinder
Direct Known Subclasses:
ConcurrentAuthorityFactory.Finder, EPSGCodeFinder, MultiAuthoritiesFactory.Finder
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
Version:
1.2
See Also:

  • 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).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) static final ComparisonMode
    COMPARISON_MODE
    The criterion for determining if a candidate found by IdentifiedObjectFinder should be considered equals to the requested object.
    private IdentifiedObjectFinder.Domain
    domain
    The domain of the search (for example whether to include deprecated objects in the search).
    protected final org.opengis.referencing.AuthorityFactory
    factory
    The factory to use for creating objects.
    private boolean
    ignoreAxes
    true if the search should ignore coordinate system axes.
    private AuthorityFactoryProxy<?>
    proxy
    The proxy for objects creation.
    private IdentifiedObjectFinder
    wrapper
    The cache or the adapter which is wrapping this finder, or null if none.

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) Set<org.opengis.referencing.IdentifiedObject>
    cache(org.opengis.referencing.IdentifiedObject object, Set<org.opengis.referencing.IdentifiedObject> result)
    Stores the given result in the cache, if any.
    private org.opengis.referencing.IdentifiedObject
    create(String code)
    Creates an object for the given identifier, name or alias.
    (package private) Set<org.opengis.referencing.IdentifiedObject>
    createFromCodes(org.opengis.referencing.IdentifiedObject object)
    Creates an object equals (optionally ignoring metadata), to the specified object.
    private org.opengis.referencing.IdentifiedObject
    createFromIdentifiers(org.opengis.referencing.IdentifiedObject object)
    Creates an object equals (optionally ignoring metadata), to the specified object using only the identifiers.
    private org.opengis.referencing.IdentifiedObject
    createFromNames(org.opengis.referencing.IdentifiedObject object)
    Creates an object equals (optionally ignoring metadata), to the specified object using only the name and aliases.
    private static void
    exceptionOccurred(org.opengis.util.FactoryException exception)
    Invoked when an exception occurred during the creation of a candidate from a code.
    Set<org.opengis.referencing.IdentifiedObject>
    find(org.opengis.referencing.IdentifiedObject object)
    Lookups objects which are approximately equal to the specified object.
    org.opengis.referencing.IdentifiedObject
    findSingleton(org.opengis.referencing.IdentifiedObject object)
    Lookups only one object which is approximately equal to the specified object.
    protected Set<String>
    getCodeCandidates(org.opengis.referencing.IdentifiedObject object)
    Returns a set of authority codes that may identify the same object than the specified one.
    (package private) Set<org.opengis.referencing.IdentifiedObject>
    getFromCache(org.opengis.referencing.IdentifiedObject object)
    Returns the cached value for the given object, or null if none.
    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.
    private boolean
    match(org.opengis.referencing.IdentifiedObject candidate, org.opengis.referencing.IdentifiedObject object)
    Returns true if a candidate found by IdentifiedObjectFinder should be considered equals to the requested object.
    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).
    (package private) final void
    setWrapper(IdentifiedObjectFinder other)
    Declares that the given cache or adapter is the wrapper of this finder.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • COMPARISON_MODE

      static final ComparisonMode COMPARISON_MODE
      The criterion for determining if a candidate found by IdentifiedObjectFinder should be considered equals to the requested object.

    • factory

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

    • proxy

      private transient AuthorityFactoryProxy<?> proxy
      The proxy for objects creation. This is updated before every object to search.

    • wrapper

      private IdentifiedObjectFinder wrapper
      The cache or the adapter which is wrapping this finder, or null if none. An example of wrapper is ConcurrentAuthorityFactory's finder.
      See Also:

    • domain

      private IdentifiedObjectFinder.Domain domain
      The domain of the search (for example whether to include deprecated objects in the search).
      See Also:

    • ignoreAxes

      private boolean ignoreAxes
      true if the search should ignore coordinate system axes.
      See Also:

  • Constructor Details

  • Method Details

    • setWrapper

      final void setWrapper(IdentifiedObjectFinder other)
      Declares that the given cache or adapter is the wrapper of this finder. This method should be invoked at wrapper construction time. An example of wrapper is ConcurrentAuthorityFactory's finder.

      This method also copies the configuration of the given finder, thus providing a central place where to add calls to setters methods if such methods are added in a future SIS version.

      Parameters:
      other - the cache or the adapter wrapping this finder.

    • 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.

    • match

      private boolean match(org.opengis.referencing.IdentifiedObject candidate, org.opengis.referencing.IdentifiedObject object)
      Returns true if a candidate found by IdentifiedObjectFinder should be considered equals to the requested object. This method invokes the equals(…) method on the candidate argument instead than on the user-specified object on the assumption that implementations coming from the factory are more reliable than user-specified objects.

    • getFromCache

      Set<org.opengis.referencing.IdentifiedObject> getFromCache(org.opengis.referencing.IdentifiedObject object)
      Returns the cached value for the given object, or null if none. The returned set (if non-null) should be unmodifiable.

    • cache

      Set<org.opengis.referencing.IdentifiedObject> cache(org.opengis.referencing.IdentifiedObject object, Set<org.opengis.referencing.IdentifiedObject> result)
      Stores the given result in the cache, if any. If this method chooses to cache the given set, then it shall wrap or copy the given set in an unmodifiable set and returns the result.
      Parameters:
      result - the search result as a modifiable set.
      Returns:
      a set with the same content than result.

    • find

      public Set<org.opengis.referencing.IdentifiedObject> find(org.opengis.referencing.IdentifiedObject object) throws org.opengis.util.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:
      org.opengis.util.FactoryException - if an error occurred while creating an object.

    • findSingleton

      public org.opengis.referencing.IdentifiedObject findSingleton(org.opengis.referencing.IdentifiedObject object) throws org.opengis.util.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:
      org.opengis.util.FactoryException - if an error occurred while creating an object.

    • createFromIdentifiers

      private org.opengis.referencing.IdentifiedObject createFromIdentifiers(org.opengis.referencing.IdentifiedObject object) throws org.opengis.util.FactoryException
      Creates an object equals (optionally ignoring metadata), to the specified object using only the identifiers. If no such object is found, returns null.

      This method may be used in order to get a fully identified object from a partially identified one.

      Parameters:
      object - the object looked up.
      Returns:
      the identified object, or null if not found.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while creating an object.
      See Also:

    • createFromNames

      private org.opengis.referencing.IdentifiedObject createFromNames(org.opengis.referencing.IdentifiedObject object) throws org.opengis.util.FactoryException
      Creates an object equals (optionally ignoring metadata), to the specified object using only the name and aliases. If no such object is found, returns null.

      This method may be used with some authority factory implementations like the one backed by the EPSG database, which are capable to find an object from its name when the identifier is unknown.

      Parameters:
      object - the object looked up.
      Returns:
      the identified object, or null if not found.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while creating an object.
      See Also:

    • createFromCodes

      Set<org.opengis.referencing.IdentifiedObject> createFromCodes(org.opengis.referencing.IdentifiedObject object) throws org.opengis.util.FactoryException
      Creates an object equals (optionally ignoring metadata), to the specified object. This method scans the authority codes, creates the objects and returns the first one which is equal to the specified object in the sense of Utilities.deepEquals(Object, Object, ComparisonMode).

      This method may be used in order to get a fully identified object from an object without identifiers.

      Scanning the whole set of authority codes may be slow. Users should try createFromIdentifiers(object) and/or createFromNames(object) before to fallback on this method.

      Parameters:
      object - the object looked up.
      Returns:
      the identified object, or null if not found.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while scanning through authority codes.
      See Also:

    • create

      private org.opengis.referencing.IdentifiedObject create(String code) throws org.opengis.util.FactoryException
      Creates an object for the given identifier, name or alias. This method is invoked by the default find(IdentifiedObject) method implementation with the following argument values, in order (from less expensive to most expensive search operation):
      1. All identifiers of the object to search, formatted in an "AUTHORITY:CODE" pattern.
      2. The name of the object to search, without authority.
      3. All aliases of the object to search.
      4. Each code returned by the getCodeCandidates(IdentifiedObject) method, in iteration order.
      Parameters:
      code - the authority code for which to create an object.
      Returns:
      the identified object for the given code, or null to stop attempts.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if no object is found for the given code. It may happen if code was a name or alias instead of an identifier and the factory supports only search by identifier.
      org.opengis.util.FactoryException - if an error occurred while creating the object.

    • getCodeCandidates

      protected Set<String> getCodeCandidates(org.opengis.referencing.IdentifiedObject object) throws org.opengis.util.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 equal 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:
      org.opengis.util.FactoryException - if an error occurred while fetching the set of code candidates.

    • exceptionOccurred

      private static void exceptionOccurred(org.opengis.util.FactoryException exception)
      Invoked when an exception occurred during the creation of a candidate from a code.