Class ReferencingFactoryFinder
To declare a factory implementation, a services subdirectory is placed within the META-INF
directory that
is present in every JAR file. This directory contains a file for each factory interface that has one or more
implementation classes present in the JAR file. For example, if the JAR file contained a class named
com.mycompany.DatumFactoryImpl
which implements the DatumFactory
interface, the JAR file would
contain a file named:
META-INF/services/org.geotools.api.referencing.datum.DatumFactory
containing the line:
com.mycompany.DatumFactoryImpl
If the factory classes implements RegisterableService
, it will be notified upon
registration and deregistration. Note that the factory classes should be lightweight and quick to load.
Implementations of these interfaces should avoid complex dependencies on other classes and on native code. The usual
pattern for more complex services is to register a lightweight proxy for the heavyweight service.
Note on factory ordering
This class is thread-safe. However, calls to any setAuthorityOrdering(java.lang.String, java.lang.String)
or setVendorOrdering(java.lang.String, java.lang.String)
methods have a system-wide effect. If two threads or two applications need a different ordering, they shall manage
their own instance of FactoryRegistry
. This FactoryFinder
class is simply a convenience wrapper
around a FactoryRegistry
instance.
- Since:
- 2.4
- Author:
- Martin Desruisseaux (IRD)
-
Field Summary
Fields inherited from class FactoryFinder
EMPTY_HINTS
-
Method Summary
Modifier and TypeMethodDescriptionstatic void
addAuthorityFactory
(AuthorityFactory authority) Programmatic management of authority factories.Returns the names of all currently registered authorities.Returns a set of all available implementations for theCoordinateOperationAuthorityFactory
interface.getCoordinateOperationAuthorityFactory
(String authority, Hints hints) Returns the first implementation ofCoordinateOperationAuthorityFactory
matching the specified hints.static Set<CoordinateOperationFactory>
Returns a set of all available implementations for theCoordinateOperationFactory
interface.static CoordinateOperationFactory
Returns the first implementation ofCoordinateOperationFactory
matching the specified hints.static Set<CRSAuthorityFactory>
getCRSAuthorityFactories
(Hints hints) Returns a set of all available implementations for theCRSAuthorityFactory
interface.static CRSAuthorityFactory
getCRSAuthorityFactory
(String authority, Hints hints) Returns the first implementation ofCRSAuthorityFactory
matching the specified hints.static Set<CRSFactory>
getCRSFactories
(Hints hints) Returns a set of all available implementations for theCRSFactory
interface.static CRSFactory
getCRSFactory
(Hints hints) Returns the first implementation ofCRSFactory
matching the specified hints.static Set<CSAuthorityFactory>
getCSAuthorityFactories
(Hints hints) Returns a set of all available implementations for theCSAuthorityFactory
interface.static CSAuthorityFactory
getCSAuthorityFactory
(String authority, Hints hints) Returns the first implementation ofCSAuthorityFactory
matching the specified hints.getCSFactories
(Hints hints) Returns a set of all available implementations for theCSFactory
interface.static CSFactory
getCSFactory
(Hints hints) Returns the first implementation ofCSFactory
matching the specified hints.static Set<DatumAuthorityFactory>
getDatumAuthorityFactories
(Hints hints) Returns a set of all available implementations for theDatumAuthorityFactory
interface.static DatumAuthorityFactory
getDatumAuthorityFactory
(String authority, Hints hints) Returns the first implementation ofDatumAuthorityFactory
matching the specified hints.static Set<DatumFactory>
getDatumFactories
(Hints hints) Returns a set of all available implementations for theDatumFactory
interface.static DatumFactory
getDatumFactory
(Hints hints) Returns the first implementation ofDatumFactory
matching the specified hints.static Set<GridShiftLocator>
getGridShiftLocators
(Hints hints) Returns a set of all available implementations for theGridShiftLocator
interface.static Set<MathTransformFactory>
getMathTransformFactories
(Hints hints) Returns a set of all available implementations for theMathTransformFactory
interface.static MathTransformFactory
getMathTransformFactory
(Hints hints) Returns the first implementation ofMathTransformFactory
matching the specified hints.static boolean
isRegistered
(Factory factory) Returnstrue
if the specified factory is registered.static void
listProviders
(Writer out, Locale locale) List all available factory implementations in a tabular format.static void
Dump to the standard output stream a list of available factory implementations.static void
removeAuthorityFactory
(AuthorityFactory authority) Programmatic management of authority factories.static void
reset()
Resets the factory finder and prepares for a new full scan of the SPI subsystemsstatic void
Scans for factory plug-ins on the application class path.static boolean
setAuthorityOrdering
(String authority1, String authority2) Sets a pairwise ordering between two authorities.static boolean
setVendorOrdering
(String vendor1, String vendor2) Sets a pairwise ordering between two vendors.static boolean
unsetAuthorityOrdering
(String authority1, String authority2) Unsets a pairwise ordering between two authorities.static boolean
unsetVendorOrdering
(String vendor1, String vendor2) Unsets a pairwise ordering between two vendors.Methods inherited from class FactoryFinder
mergeSystemHints
-
Method Details
-
getAuthorityNames
Returns the names of all currently registered authorities. -
getDatumFactory
Returns the first implementation ofDatumFactory
matching the specified hints. If no implementation matches, a new one is created if possible or an exception is thrown otherwise. If more than one implementation is registered and an ordering is set, then the preferred implementation is returned. Otherwise an arbitrary one is selected.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- The first datum factory that matches the supplied hints.
- Throws:
FactoryRegistryException
- if no implementation was found or can be created for theDatumFactory
interface.
-
getDatumFactories
Returns a set of all available implementations for theDatumFactory
interface.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- Set of available datum factory implementations.
-
getCSFactory
Returns the first implementation ofCSFactory
matching the specified hints. If no implementation matches, a new one is created if possible or an exception is thrown otherwise. If more than one implementation is registered and an ordering is set, then the preferred implementation is returned. Otherwise an arbitrary one is selected.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- The first coordinate system factory that matches the supplied hints.
- Throws:
FactoryRegistryException
- if no implementation was found or can be created for theCSFactory
interface.
-
getCSFactories
Returns a set of all available implementations for theCSFactory
interface.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- Set of available coordinate system factory implementations.
-
getCRSFactory
Returns the first implementation ofCRSFactory
matching the specified hints. If no implementation matches, a new one is created if possible or an exception is thrown otherwise. If more than one implementation is registered and an ordering is set, then the preferred implementation is returned. Otherwise an arbitrary one is selected.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- The first coordinate reference system factory that matches the supplied hints.
- Throws:
FactoryRegistryException
- if no implementation was found or can be created for theCRSFactory
interface.
-
getCRSFactories
Returns a set of all available implementations for theCRSFactory
interface.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- Set of available coordinate reference system factory implementations.
-
getCoordinateOperationFactory
public static CoordinateOperationFactory getCoordinateOperationFactory(Hints hints) throws FactoryRegistryException Returns the first implementation ofCoordinateOperationFactory
matching the specified hints. If no implementation matches, a new one is created if possible or an exception is thrown otherwise. If more than one implementation is registered and an ordering is set, then the preferred implementation is returned. Otherwise an arbitrary one is selected.Hints that may be understood includes
MATH_TRANSFORM_FACTORY
,DATUM_SHIFT_METHOD
,LENIENT_DATUM_SHIFT
andVERSION
.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- The first coordinate operation factory that matches the supplied hints.
- Throws:
FactoryRegistryException
- if no implementation was found or can be created for theCoordinateOperationFactory
interface.
-
getCoordinateOperationFactories
Returns a set of all available implementations for theCoordinateOperationFactory
interface.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- Set of available coordinate operation factory implementations.
-
getDatumAuthorityFactory
public static DatumAuthorityFactory getDatumAuthorityFactory(String authority, Hints hints) throws FactoryRegistryException Returns the first implementation ofDatumAuthorityFactory
matching the specified hints. If no implementation matches, a new one is created if possible or an exception is thrown otherwise. If more than one implementation is registered and an ordering is set, then the preferred implementation is returned. Otherwise an arbitrary one is selected.- Parameters:
authority
- The desired authority (e.g. "EPSG").hints
- An optional map of hints, ornull
if none.- Returns:
- The first datum authority factory that matches the supplied hints.
- Throws:
FactoryRegistryException
- if no implementation was found or can be created for theDatumAuthorityFactory
interface.
-
getDatumAuthorityFactories
Returns a set of all available implementations for theDatumAuthorityFactory
interface.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- Set of available datum authority factory implementations.
-
getCSAuthorityFactory
public static CSAuthorityFactory getCSAuthorityFactory(String authority, Hints hints) throws FactoryRegistryException Returns the first implementation ofCSAuthorityFactory
matching the specified hints. If no implementation matches, a new one is created if possible or an exception is thrown otherwise. If more than one implementation is registered and an ordering is set, then the preferred implementation is returned. Otherwise an arbitrary one is selected.Hints that may be understood includes
FORCE_LONGITUDE_FIRST_AXIS_ORDER
,FORCE_STANDARD_AXIS_UNITS
andFORCE_STANDARD_AXIS_DIRECTIONS
andVERSION
.- Parameters:
authority
- The desired authority (e.g. "EPSG").hints
- An optional map of hints, ornull
if none.- Returns:
- The first coordinate system authority factory that matches the supplied hints.
- Throws:
FactoryRegistryException
- if no implementation was found or can be created for theCSAuthorityFactory
interface.
-
getCSAuthorityFactories
Returns a set of all available implementations for theCSAuthorityFactory
interface.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- Set of available coordinate system authority factory implementations.
-
getCRSAuthorityFactory
public static CRSAuthorityFactory getCRSAuthorityFactory(String authority, Hints hints) throws FactoryRegistryException Returns the first implementation ofCRSAuthorityFactory
matching the specified hints. If no implementation matches, a new one is created if possible or an exception is thrown otherwise. If more than one implementation is registered and an ordering is set, then the preferred implementation is returned. Otherwise an arbitrary one is selected.Hints that may be understood includes
FORCE_LONGITUDE_FIRST_AXIS_ORDER
,FORCE_STANDARD_AXIS_UNITS
,FORCE_STANDARD_AXIS_DIRECTIONS
andVERSION
.TIP: The EPSG official factory and the EPSG extensions (additional CRS provided by ESRI and others) are two distinct factories. Call to
getCRSAuthorityFactory("EPSG", null)
returns only one of those, usually the official EPSG factory. If the union of those two factories is wanted, then a chain of fallbacks is wanted. Consider using something like:FallbackAuthorityFactory.create(CRSAuthorityFactory.class, getCRSAuthorityFactories(hints));
- Parameters:
authority
- The desired authority (e.g. "EPSG").hints
- An optional map of hints, ornull
if none.- Returns:
- The first coordinate reference system authority factory that matches the supplied hints.
- Throws:
FactoryRegistryException
- if no implementation was found or can be created for theCRSAuthorityFactory
interface.
-
getCRSAuthorityFactories
Returns a set of all available implementations for theCRSAuthorityFactory
interface. This set can be used to list the available codes known to all authorities. In the event that the same code is understood by more then one authority you will need to assume both are close enough, or make use of this set directly rather than use theCRS.decode(java.lang.String)
convenience method.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- Set of available coordinate reference system authority factory implementations.
-
getCoordinateOperationAuthorityFactory
public static CoordinateOperationAuthorityFactory getCoordinateOperationAuthorityFactory(String authority, Hints hints) throws FactoryRegistryException Returns the first implementation ofCoordinateOperationAuthorityFactory
matching the specified hints. If no implementation matches, a new one is created if possible or an exception is thrown otherwise. If more than one implementation is registered and an ordering is set, then the preferred implementation is returned. Otherwise an arbitrary one is selected.- Parameters:
authority
- The desired authority (e.g. "EPSG").hints
- An optional map of hints, ornull
if none.- Returns:
- The first coordinate operation authority factory that matches the supplied hints.
- Throws:
FactoryRegistryException
- if no implementation was found or can be created for theCoordinateOperationAuthorityFactory
interface.
-
getCoordinateOperationAuthorityFactories
public static Set<CoordinateOperationAuthorityFactory> getCoordinateOperationAuthorityFactories(Hints hints) Returns a set of all available implementations for theCoordinateOperationAuthorityFactory
interface.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- Set of available coordinate operation authority factory implementations.
-
getGridShiftLocators
Returns a set of all available implementations for theGridShiftLocator
interface.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- Set of available grid shift factory implementations.
-
getMathTransformFactory
public static MathTransformFactory getMathTransformFactory(Hints hints) throws FactoryRegistryException Returns the first implementation ofMathTransformFactory
matching the specified hints. If no implementation matches, a new one is created if possible or an exception is thrown otherwise. If more than one implementation is registered and an ordering is set, then the preferred implementation is returned. Otherwise an arbitrary one is selected.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- The first math transform factory that matches the supplied hints.
- Throws:
FactoryRegistryException
- if no implementation was found or can be created for theMathTransformFactory
interface.
-
getMathTransformFactories
Returns a set of all available implementations for theMathTransformFactory
interface.- Parameters:
hints
- An optional map of hints, ornull
if none.- Returns:
- Set of available math transform factory implementations.
-
setVendorOrdering
Sets a pairwise ordering between two vendors. If one or both vendors are not currently registered, or if the desired ordering is already set, nothing happens andfalse
is returned.The example below said that an ESRI implementation (if available) is preferred over the Geotools one:
FactoryFinder.setVendorOrdering("ESRI", "Geotools");
- Parameters:
vendor1
- The preferred vendor.vendor2
- The vendor to whichvendor1
is preferred.- Returns:
true
if the ordering was set for at least one category.
-
unsetVendorOrdering
Unsets a pairwise ordering between two vendors. If one or both vendors are not currently registered, or if the desired ordering is already unset, nothing happens andfalse
is returned.- Parameters:
vendor1
- The preferred vendor.vendor2
- The vendor to whichvendor1
is preferred.- Returns:
true
if the ordering was unset for at least one category.
-
setAuthorityOrdering
Sets a pairwise ordering between two authorities. If one or both authorities are not currently registered, or if the desired ordering is already set, nothing happens andfalse
is returned.The example below said that EPSG authority factories are preferred over ESRI ones:
FactoryFinder.setAuthorityOrdering("EPSG", "ESRI");
- Parameters:
authority1
- The preferred authority.authority2
- The authority to whichauthority1
is preferred.- Returns:
true
if the ordering was set for at least one category.
-
unsetAuthorityOrdering
Unsets a pairwise ordering between two authorities. If one or both authorities are not currently registered, or if the desired ordering is already unset, nothing happens andfalse
is returned.- Parameters:
authority1
- The preferred authority.authority2
- The vendor to whichauthority1
is preferred.- Returns:
true
if the ordering was unset for at least one category.
-
addAuthorityFactory
Programmatic management of authority factories. Needed for user managed, not plug-in managed, authority factory. Also useful for test cases.- Parameters:
authority
- The authority factory to add.
-
removeAuthorityFactory
Programmatic management of authority factories. Needed for user managed, not plug-in managed, authority factory. Also useful for test cases.- Parameters:
authority
- The authority factory to remove.
-
isRegistered
Returnstrue
if the specified factory is registered. A factory may have been registered byscanForPlugins()
if it was declared in aMETA-INF/services
file, or it may have been added programmatically.- Since:
- 2.4
-
scanForPlugins
public static void scanForPlugins()Scans for factory plug-ins on the application class path. This method is needed because the application class path can theoretically change, or additional plug-ins may become available. Rather than re-scanning the classpath on every invocation of the API, the class path is scanned automatically only on the first invocation. Clients can call this method to prompt a re-scan. Thus this method need only be invoked by sophisticated applications which dynamically make new plug-ins available at runtime. -
listProviders
List all available factory implementations in a tabular format. For each factory interface, the first implementation listed is the default one. This method provides a way to check the state of a system, usually for debugging purpose.- Parameters:
out
- The output stream where to format the list.locale
- The locale for the list, ornull
.- Throws:
IOException
- if an error occurs while writting toout
.
-
reset
public static void reset()Resets the factory finder and prepares for a new full scan of the SPI subsystems -
main
Dump to the standard output stream a list of available factory implementations. This method can be invoked from the command line. It provides a mean to verify if some implementations were found in the classpath. The syntax is:
java org.geotools.referencing.FactoryFinder <options>
where options are:
-encoding
<code>Set the character encoding -locale
<language>Set the language for the output (e.g. "fr" for French) Note for Windows users: If the output contains strange symbols, try to supply an "
-encoding
" argument. Example:java org.geotools.referencing.FactoryFinder -encoding Cp850
The codepage number (850 in the previous example) can be obtained from the DOS commande line using the "
chcp
" command with no arguments.- Parameters:
args
- Command line arguments.
-