org.geotools.referencing
Class FactoryFinder

java.lang.Object
  org.geotools.referencing.FactoryFinder

public final class FactoryFinder

extends java.lang.Object

Defines static methods used to access the application's default factory implementation.

To declare a factory implementation, a services subdirectory is placed within the 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 which implements the DatumFactory interface, the JAR file would contain a file named:

META-INF/services/org.opengis.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 in a multi-thread environment

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 class is simply a convenience wrapper around a instance.

Since:

2.0

Version:

$Id: FactoryFinder.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

Martin Desruisseaux

Method Summary

static void	addAuthorityFactory(org.opengis.referencing.AuthorityFactory authority) Programmatic management of authority factories.
static java.util.Set	getAuthorityNames() Returns the names of all currently registered authorities.
static java.util.Set	getCoordinateOperationAuthorityFactories() Returns a set of all available implementations for the CoordinateOperationAuthorityFactory interface.
static org.opengis.referencing.operation.CoordinateOperationAuthorityFactory	getCoordinateOperationAuthorityFactory(java.lang.String authority, Hints hints) Returns the first implementation of CoordinateOperationAuthorityFactory matching the specified hints.
static java.util.Set	getCoordinateOperationFactories() Returns a set of all available implementations for the CoordinateOperationFactory interface.
static org.opengis.referencing.operation.CoordinateOperationFactory	getCoordinateOperationFactory(Hints hints) Returns the first implementation of CoordinateOperationFactory matching the specified hints.
static java.util.Set	getCRSAuthorityFactories() Returns a set of all available implementations for the CRSAuthorityFactory interface.
static org.opengis.referencing.crs.CRSAuthorityFactory	getCRSAuthorityFactory(java.lang.String authority, Hints hints) Returns the first implementation of CRSAuthorityFactory matching the specified hints.
static java.util.Set	getCRSFactories() Returns a set of all available implementations for the CRSFactory interface.
static org.opengis.referencing.crs.CRSFactory	getCRSFactory(Hints hints) Returns the first implementation of CRSFactory matching the specified hints.
static java.util.Set	getCSAuthorityFactories() Returns a set of all available implementations for the CSAuthorityFactory interface.
static org.opengis.referencing.cs.CSAuthorityFactory	getCSAuthorityFactory(java.lang.String authority, Hints hints) Returns the first implementation of CSAuthorityFactory matching the specified hints.
static java.util.Set	getCSFactories() Returns a set of all available implementations for the CSFactory interface.
static org.opengis.referencing.cs.CSFactory	getCSFactory(Hints hints) Returns the first implementation of CSFactory matching the specified hints.
static java.util.Set	getDatumAuthorityFactories() Returns a set of all available implementations for the DatumAuthorityFactory interface.
static org.opengis.referencing.datum.DatumAuthorityFactory	getDatumAuthorityFactory(java.lang.String authority, Hints hints) Returns the first implementation of DatumAuthorityFactory matching the specified hints.
static java.util.Set	getDatumFactories() Returns a set of all available implementations for the DatumFactory interface.
static org.opengis.referencing.datum.DatumFactory	getDatumFactory(Hints hints) Returns the first implementation of DatumFactory matching the specified hints.
static java.util.Set	getMathTransformFactories() Returns a set of all available implementations for the MathTransformFactory interface.
static org.opengis.referencing.operation.MathTransformFactory	getMathTransformFactory(Hints hints) Returns the first implementation of MathTransformFactory matching the specified hints.
static void	listProviders(java.io.Writer out, java.util.Locale locale) List all available factory implementations in a tabular format.
static void	main(java.lang.String[] args) Dump to the standard output stream a list of available factory implementations.
static void	removeAuthorityFactory(org.opengis.referencing.AuthorityFactory authority) Programmatic management of authority factories.
static void	scanForPlugins() Scans for factory plug-ins on the application class path.
static boolean	setAuthorityOrdering(java.lang.String authority1, java.lang.String authority2) Sets a pairwise ordering between two authorities.
static boolean	setVendorOrdering(java.lang.String vendor1, java.lang.String vendor2) Sets a pairwise ordering between two vendors.
static boolean	unsetAuthorityOrdering(java.lang.String authority1, java.lang.String authority2) Unsets a pairwise ordering between two authorities.
static boolean	unsetVendorOrdering(java.lang.String vendor1, java.lang.String vendor2) Unsets a pairwise ordering between two vendors.

Methods inherited from class java.lang.Object

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

Method Detail

addAuthorityFactory

public static void addAuthorityFactory(org.opengis.referencing.AuthorityFactory authority)

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

public static void removeAuthorityFactory(org.opengis.referencing.AuthorityFactory authority)

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.

getAuthorityNames

public static java.util.Set getAuthorityNames()

Returns the names of all currently registered authorities.

getDatumFactory

public static org.opengis.referencing.datum.DatumFactory getDatumFactory(Hints hints)
                                                                  throws FactoryRegistryException

Returns the first implementation of DatumFactory 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, or if none.

Returns:

The first datum factory that matches the supplied hints.

Throws:

FactoryRegistryException - if no implementation was found or can be created for the DatumFactory interface.

getDatumFactories

public static java.util.Set getDatumFactories()

Returns a set of all available implementations for the DatumFactory interface.

Returns:

Set of available datum factory implementations.

getCSFactory

public static org.opengis.referencing.cs.CSFactory getCSFactory(Hints hints)
                                                         throws FactoryRegistryException

Returns the first implementation of CSFactory 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, or 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 the CSFactory interface.

getCSFactories

public static java.util.Set getCSFactories()

Returns a set of all available implementations for the CSFactory interface.

Returns:

Set of available coordinate system factory implementations.

getCRSFactory

public static org.opengis.referencing.crs.CRSFactory getCRSFactory(Hints hints)
                                                            throws FactoryRegistryException

Returns the first implementation of CRSFactory 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, or 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 the CRSFactory interface.

getCRSFactories

public static java.util.Set getCRSFactories()

Returns a set of all available implementations for the CRSFactory interface.

Returns:

Set of available coordinate reference system factory implementations.

getCoordinateOperationFactory

public static org.opengis.referencing.operation.CoordinateOperationFactory getCoordinateOperationFactory(Hints hints)
                                                                                                  throws FactoryRegistryException

Returns the first implementation of CoordinateOperationFactory 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 and LENIENT_DATUM_SHIFT.

Parameters:

hints - An optional map of hints, or 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 the CoordinateOperationFactory interface.

getCoordinateOperationFactories

public static java.util.Set getCoordinateOperationFactories()

Returns a set of all available implementations for the CoordinateOperationFactory interface.

getDatumAuthorityFactory

public static org.opengis.referencing.datum.DatumAuthorityFactory getDatumAuthorityFactory(java.lang.String authority,
                                                                                           Hints hints)
                                                                                    throws FactoryRegistryException

Returns the first implementation of DatumAuthorityFactory 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, or 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 the DatumAuthorityFactory interface.

getDatumAuthorityFactories

public static java.util.Set getDatumAuthorityFactories()

Returns a set of all available implementations for the DatumAuthorityFactory interface.

Returns:

Set of available datum authority factory implementations.

getCSAuthorityFactory

public static org.opengis.referencing.cs.CSAuthorityFactory getCSAuthorityFactory(java.lang.String authority,
                                                                                  Hints hints)
                                                                           throws FactoryRegistryException

Returns the first implementation of CSAuthorityFactory 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, or 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 the CSAuthorityFactory interface.

getCSAuthorityFactories

public static java.util.Set getCSAuthorityFactories()

Returns a set of all available implementations for the CSAuthorityFactory interface.

Returns:

Set of available coordinate system authority factory implementations.

getCRSAuthorityFactory

public static org.opengis.referencing.crs.CRSAuthorityFactory getCRSAuthorityFactory(java.lang.String authority,
                                                                                     Hints hints)
                                                                              throws FactoryRegistryException

Returns the first implementation of CRSAuthorityFactory 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, or 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 the CRSAuthorityFactory interface.

getCRSAuthorityFactories

public static java.util.Set getCRSAuthorityFactories()

Returns a set of all available implementations for the CRSAuthorityFactory 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 the CRS.decode(java.lang.String) convenience method.

Returns:

Set of available coordinate reference system authority factory implementations.

getCoordinateOperationAuthorityFactory

public static org.opengis.referencing.operation.CoordinateOperationAuthorityFactory getCoordinateOperationAuthorityFactory(java.lang.String authority,
                                                                                                                           Hints hints)
                                                                                                                    throws FactoryRegistryException

Returns the first implementation of CoordinateOperationAuthorityFactory 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, or 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 the CoordinateOperationAuthorityFactory interface.

getCoordinateOperationAuthorityFactories

public static java.util.Set getCoordinateOperationAuthorityFactories()

Returns a set of all available implementations for the CoordinateOperationAuthorityFactory interface.

Returns:

Set of available coordinate operation authority factory implementations.

getMathTransformFactory

public static org.opengis.referencing.operation.MathTransformFactory getMathTransformFactory(Hints hints)
                                                                                      throws FactoryRegistryException

Returns the first implementation of MathTransformFactory 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, or 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 the MathTransformFactory interface.

getMathTransformFactories

public static java.util.Set getMathTransformFactories()

Returns a set of all available implementations for the MathTransformFactory interface.

setVendorOrdering

public static boolean setVendorOrdering(java.lang.String vendor1,
                                        java.lang.String vendor2)

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 and 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 which is preferred.

Returns:

if the ordering was set for at least one category.

unsetVendorOrdering

public static boolean unsetVendorOrdering(java.lang.String vendor1,
                                          java.lang.String vendor2)

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 and is returned.

Parameters:

vendor1 - The preferred vendor.

vendor2 - The vendor to which is preferred.

Returns:

if the ordering was unset for at least one category.

setAuthorityOrdering

public static boolean setAuthorityOrdering(java.lang.String authority1,
                                           java.lang.String authority2)

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 and 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 which is preferred.

Returns:

if the ordering was set for at least one category.

unsetAuthorityOrdering

public static boolean unsetAuthorityOrdering(java.lang.String authority1,
                                             java.lang.String authority2)

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 and is returned.

Parameters:

authority1 - The preferred authority.

authority2 - The vendor to which is preferred.

Returns:

if the ordering was unset for at least one category.

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

public static void listProviders(java.io.Writer out,
                                 java.util.Locale locale)
                          throws java.io.IOException

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, or .

Throws:

java.io.IOException - if an error occurs while writting to .

main

public static void main(java.lang.String[] args)

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 "" 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 "" command with no arguments. This argument need to be supplied only once.

Parameters:

args - Command line arguments.