To declare a factory implementation, a services subdirectory is placed within the * {@code 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 * {@code com.mycompany.DatumFactoryImpl} which implements the {@link 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 {@link javax.imageio.spi.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.
* *This class is thread-safe. However, calls to any {@link #setAuthorityOrdering} or * {@link #setVendorOrdering} methods have a system-wide effect. If two threads or two * applications need a different ordering, they shall manage their own instance of * {@link FactoryRegistry}. This {@code FactoryFinder} class is simply a convenience * wrapper around a {@code FactoryRegistry} instance.
* * @since 2.4 * * @source $URL$ * @version $Id$ * @author Martin Desruisseaux (IRD) */ public final class ReferencingFactoryFinder extends FactoryFinder { /** * The service registry for this manager. * Will be initialized only when first needed. */ private static FactoryRegistry registry; /** * The authority names. Will be created only when first needed. */ private static Set
* Hints that may be understood includes
* {@link Hints#MATH_TRANSFORM_FACTORY MATH_TRANSFORM_FACTORY},
* {@link Hints#DATUM_SHIFT_METHOD DATUM_SHIFT_METHOD},
* {@link Hints#LENIENT_DATUM_SHIFT LENIENT_DATUM_SHIFT} and
* {@link Hints#VERSION VERSION}.
*
* @param hints An optional map of hints, or {@code null} if none.
* @return The first coordinate operation factory that matches the supplied hints.
* @throws FactoryRegistryException if no implementation was found or can be created for the
* {@link CoordinateOperationFactory} interface.
*/
public static CoordinateOperationFactory getCoordinateOperationFactory(final Hints hints)
throws FactoryRegistryException
{
return getFactory(CoordinateOperationFactory.class, hints,
Hints.COORDINATE_OPERATION_FACTORY);
}
/**
* Returns a set of all available implementations for the
* {@link CoordinateOperationFactory} interface.
*
* @param hints An optional map of hints, or {@code null} if none.
* @return Set of available coordinate operation factory implementations.
*/
public static Set
* Hints that may be understood includes
* {@link Hints#FORCE_LONGITUDE_FIRST_AXIS_ORDER FORCE_LONGITUDE_FIRST_AXIS_ORDER},
* {@link Hints#FORCE_STANDARD_AXIS_UNITS FORCE_STANDARD_AXIS_UNITS} and
* {@link Hints#FORCE_STANDARD_AXIS_DIRECTIONS FORCE_STANDARD_AXIS_DIRECTIONS} and
* {@link Hints#VERSION VERSION}.
*
* @param authority The desired authority (e.g. "EPSG").
* @param hints An optional map of hints, or {@code null} if none.
* @return The first coordinate system authority factory that matches the supplied hints.
* @throws FactoryRegistryException if no implementation was found or can be created for the
* {@link CSAuthorityFactory} interface.
*/
public static CSAuthorityFactory getCSAuthorityFactory(final String authority,
final Hints hints)
throws FactoryRegistryException
{
return getAuthorityFactory(CSAuthorityFactory.class, authority, hints,
Hints.CS_AUTHORITY_FACTORY);
}
/**
* Returns a set of all available implementations for the {@link CSAuthorityFactory} interface.
*
* @param hints An optional map of hints, or {@code null} if none.
* @return Set of available coordinate system authority factory implementations.
*/
public static Set
* Hints that may be understood includes
* {@link Hints#FORCE_LONGITUDE_FIRST_AXIS_ORDER FORCE_LONGITUDE_FIRST_AXIS_ORDER},
* {@link Hints#FORCE_STANDARD_AXIS_UNITS FORCE_STANDARD_AXIS_UNITS},
* {@link Hints#FORCE_STANDARD_AXIS_DIRECTIONS FORCE_STANDARD_AXIS_DIRECTIONS} and
* {@link Hints#VERSION VERSION}.
*
* TIP: The EPSG official factory and the EPSG extensions (additional CRS provided by
* ESRI and others) are two distinct factories. Call to {@code 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:
*
*
* The example below said that an ESRI implementation (if available) is
* preferred over the Geotools one:
*
*
* The example below said that EPSG {@linkplain AuthorityFactory authority factories}
* are preferred over ESRI ones:
*
* where options are: Note for Windows users: If the output contains strange
* symbols, try to supply an "{@code -encoding}" argument. Example: The codepage number (850 in the previous example) can be obtained from the DOS
* commande line using the "{@code chcp}" command with no arguments.
*
* @param authority The desired authority (e.g. "EPSG").
* @param hints An optional map of hints, or {@code null} if none.
* @return 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
* {@link CRSAuthorityFactory} interface.
*/
public static CRSAuthorityFactory getCRSAuthorityFactory(final String authority,
final Hints hints)
throws FactoryRegistryException
{
return getAuthorityFactory(CRSAuthorityFactory.class, authority, hints,
Hints.CRS_AUTHORITY_FACTORY);
}
/**
* Returns a set of all available implementations for the {@link 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 {@link CRS#decode} convenience method.
*
* @param hints An optional map of hints, or {@code null} if none.
* @return Set of available coordinate reference system authority factory implementations.
*/
public static Set
* {@linkplain org.geotools.referencing.factory.FallbackAuthorityFactory#create(Class,
* java.util.Collection) FallbackAuthorityFactory.create}(CRSAuthorityFactory.class,
* {@linkplain #getCRSAuthorityFactories getCRSAuthorityFactories}(hints));
*
*
* @param vendor1 The preferred vendor.
* @param vendor2 The vendor to which {@code vendor1} is preferred.
* @return {@code true} if the ordering was set for at least one category.
*/
public static synchronized boolean setVendorOrdering(final String vendor1,
final String vendor2)
{
return getServiceRegistry().setOrdering(Factory.class, true,
new VendorFilter(vendor1),
new VendorFilter(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 {@code false} is returned.
*
* @param vendor1 The preferred vendor.
* @param vendor2 The vendor to which {@code vendor1} is preferred.
* @return {@code true} if the ordering was unset for at least one category.
*/
public static synchronized boolean unsetVendorOrdering(final String vendor1,
final String vendor2)
{
return getServiceRegistry().setOrdering(Factory.class, false,
new VendorFilter(vendor1),
new VendorFilter(vendor2));
}
/**
* A filter for factories provided by a given vendor.
*/
private static final class VendorFilter implements ServiceRegistry.Filter {
/** The vendor to filter. */
private final String vendor;
/** Constructs a filter for the given vendor. */
public VendorFilter(final String vendor) {
this.vendor = vendor;
}
/** Returns {@code true} if the specified provider is built by the vendor. */
public boolean filter(final Object provider) {
return Citations.titleMatches(((Factory)provider).getVendor(), vendor);
}
}
/**
* 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 {@code false} is returned.
* FactoryFinder.setVendorOrdering("ESRI", "Geotools");
*
* @param authority1 The preferred authority.
* @param authority2 The authority to which {@code authority1} is preferred.
* @return {@code true} if the ordering was set for at least one category.
*/
public static synchronized boolean setAuthorityOrdering(final String authority1,
final String authority2)
{
return getServiceRegistry().setOrdering(AuthorityFactory.class, true,
new AuthorityFilter(authority1),
new AuthorityFilter(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 {@code false} is returned.
*
* @param authority1 The preferred authority.
* @param authority2 The vendor to which {@code authority1} is preferred.
* @return {@code true} if the ordering was unset for at least one category.
*/
public static synchronized boolean unsetAuthorityOrdering(final String authority1,
final String authority2)
{
return getServiceRegistry().setOrdering(AuthorityFactory.class, false,
new AuthorityFilter(authority1),
new AuthorityFilter(authority2));
}
/**
* A filter for factories provided for a given authority.
*/
private static final class AuthorityFilter implements ServiceRegistry.Filter {
/** The authority to filter. */
private final String authority;
/** Constructs a filter for the given authority. */
public AuthorityFilter(final String authority) {
this.authority = authority;
}
/** Returns {@code true} if the specified provider is for the authority. */
public boolean filter(final Object provider) {
if (authority == null) {
// If the user didn't specified an authority name, then the factory to use must
// be specified explicitly through a hint (e.g. Hints.CRS_AUTHORITY_FACTORY).
return false;
}
return Citations.identifierMatches(((AuthorityFactory)provider).getAuthority(), authority);
}
}
/**
* Programmatic management of authority factories.
* Needed for user managed, not plug-in managed, authority factory.
* Also useful for test cases.
*
* @param authority The authority factory to add.
*/
public static synchronized void addAuthorityFactory(final AuthorityFactory authority) {
if (registry == null) {
scanForPlugins();
}
getServiceRegistry().registerServiceProvider(authority);
authorityNames = null;
}
/**
* Programmatic management of authority factories.
* Needed for user managed, not plug-in managed, authority factory.
* Also useful for test cases.
*
* @param authority The authority factory to remove.
*/
public static synchronized void removeAuthorityFactory(final AuthorityFactory authority) {
getServiceRegistry().deregisterServiceProvider(authority);
authorityNames = null;
}
/**
* Returns {@code true} if the specified factory is registered. A factory may have been
* registered by {@link #scanForPlugins()} if it was declared in a {@code META-INF/services}
* file, or it may have been {@linkplain #addAuthorityFactory added programmatically}.
*
* @since 2.4
*/
public static synchronized boolean isRegistered(final Factory factory) {
return factory.equals(getServiceRegistry().getServiceProviderByClass(factory.getClass()));
}
/**
* 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.
*/
public static void scanForPlugins() {
synchronized (ReferencingFactoryFinder.class) {
authorityNames = null;
if (registry != null) {
registry.scanForPlugins();
}
}
GeoTools.fireConfigurationChanged();
}
/**
* 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.
*
* @param out The output stream where to format the list.
* @param locale The locale for the list, or {@code null}.
* @throws IOException if an error occurs while writting to {@code out}.
*/
public static synchronized void listProviders(final Writer out, final Locale locale)
throws IOException
{
final FactoryRegistry registry = getServiceRegistry();
new FactoryPrinter().list(registry, out, locale);
}
/**
* Resets the factory finder and prepares for a new full scan of the SPI subsystems
*/
public static void reset() {
FactoryRegistry copy = registry;
registry = null;
if(copy != null) {
copy.deregisterAll();
}
}
/**
* 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:
* FactoryFinder.setAuthorityOrdering("EPSG", "ESRI");
*
*
*
* java org.geotools.referencing.FactoryFinder <options>
*
*
*
* -encoding <code> Set the character encoding -locale <language> Set the language for the output (e.g. "fr" for French)
*
*
* java org.geotools.referencing.FactoryFinder -encoding Cp850
*