Package org.geotools.util.factory

Class GeoTools

  • public final class GeoTools
extends Object
    Static methods relative to the global GeoTools configuration. GeoTools can be configured in a system-wide basis through system properties, some of them are declared as String constants in this class.

    There are many aspects to the configuration of GeoTools:

    • Default Settings: Are handled as the Hints returned by getDefaultHints(), the default values can be provided in application code, or specified using system properties.
    • Integration JNDI: Telling the GeoTools library about the facilities of an application, or application container takes several forms. This class provides the init(InitialContext) method allowing to tell GeoTools about the JNDI context to use.
    • Integration Plugins: If hosting GeoTools in a alternate plugin system such as Spring or OSGi, application may needs to hunt down the FactoryFinders and register additional "Factory Iterators" for GeoTools to search using the addFactoryIteratorProvider(org.geotools.util.factory.FactoryIteratorProvider) method.
    Since:
    2.4
    Author:
    Jody Garnett, Martin Desruisseaux

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static void addChangeListener​(ChangeListener listener)
      Adds the specified listener to the list of objects to inform when system-wide configuration changed.
      static void addClassLoader​(ClassLoader classLoader)
      Adds a class loader to be included in the list of class loaders that are used to locate GeoTools plug-ins.
      static Hints addDefaultHints​(Hints hints)
      Used to combine provided hints with global GeoTools defaults.
      static void addFactoryIteratorProvider​(FactoryIteratorProvider provider)
      Adds an alternative way to search for factory implementations.
      static void clearInitialContext()
      Clears the initial context (closes it if not null)
      static void fireConfigurationChanged()
      Informs every listeners that system-wide configuration changed.
      static String fixName​(String name)
      Deprecated.
      With no replacement, GeoTools now uses JNDI lookups as instructed in jndiLookup(String), but does not put any object in the contex, the downstream application should do it if necessary instead.
      static String fixName​(Context context, String name)
      Deprecated.
      With no replacement, GeoTools now uses JNDI lookups as instructed in {@link * #jndiLookup(String)}, but does not put any object in the contex, the downstream * application should do it if necessary instead.
      static String getAboutInfo()
      Returns summary information about GeoTools and the current environment.
      static Properties getBuildProperties()
      Returns the raw properties object containing all properties about this GeoTools build.
      static String getBuildRevision()
      Reports back the vcs revision at which the version of GeoTools was built.
      static String getBuildTimestamp()
      Reports back the timestamp at which the version of GeoTools of built.
      static Hints getDefaultHints()
      Returns the default set of hints used for the various utility classes.
      static EntityResolver getEntityResolver​(Hints hints)
      Returns the default entity resolver, used to configure SAXParser.
      static String getEnvironmentInfo()
      Returns summary information about the GeoTools version and the host environment.
      static String getGeoToolsJarInfo()
      Returns the names of the GeoTools jars on the classpath.
      static InitialContext getInitialContext()
      Deprecated.
      Please use jndiLookup(String) instead, or provide an InitialContext to the init(InitialContext) method and use it directly.
      static Manifest getManifest​(Class<?> type)
      Lookup the MANIFEST.MF for the provided class.
      static Version getVersion()
      Reports back the version of GeoTools being used.
      static Version getVersion​(Class<?> type)
      Lookup version for provided class.
      static void init()
      Initializes GeoTools for use.
      static void init​(InitialContext initialContext)
      Provides GeoTools with the JNDI context for resource lookup.
      static void init​(Hints hints)
      Initializes GeoTools for use.
      static boolean isJNDIAvailable()
      Checks if JNDI is available, either because it was initialized, or because it was possible to create one.
      static Object jndiLookup​(String name)
      Looks up an object from the JNDI InitialContext.
      static void main​(String... args)
      Reports the GeoTools version number to the standard output stream.
      static void removeChangeListener​(ChangeListener listener)
      Removes the specified listener from the list of objects to inform when system-wide configuration changed.
      static void removeFactoryIteratorProvider​(FactoryIteratorProvider provider)
      Removes a provider that was previously added.
      static void setJNDINameValidator​(Predicate<String> validator)
      Sets up a function that will be called to validate the JNDI lookups.
      static void setLoggerFactory​(LoggerFactory<?> factory)
      Sets the global logger factory.

      • Methods inherited from class Object

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

    • Method Detail

      • getAboutInfo

        public static String getAboutInfo()
        Returns summary information about GeoTools and the current environment. Calls getEnvironmentInfo() followed by getGeoToolsJarInfo() and concatenates their results.
        Returns:
        requested information as a string

      • getEnvironmentInfo

        public static String getEnvironmentInfo()
        Returns summary information about the GeoTools version and the host environment.
        Returns:
        information as a String

      • getGeoToolsJarInfo

        public static String getGeoToolsJarInfo()
        Returns the names of the GeoTools jars on the classpath.
        Returns:
        list of jars as a formatted string

      • getBuildRevision

        public static String getBuildRevision()
        Reports back the vcs revision at which the version of GeoTools was built.
        Returns:
        The svn revision.

      • getBuildTimestamp

        public static String getBuildTimestamp()
        Reports back the timestamp at which the version of GeoTools of built.
        Returns:
        The build timestamp.

      • getBuildProperties

        public static Properties getBuildProperties()
        Returns the raw properties object containing all properties about this GeoTools build.

        Example from the 14.3 release:

        • version=14.3
        • build.revision=2298d56000bef6f526b521a480316ea544c74571
        • build.branch=rel_14.3
        • build.timestamp=21-Mar-2016 21:30

      • getVersion

        public static Version getVersion()
        Reports back the version of GeoTools being used.
        Returns:
        The current GeoTools version.

      • getVersion

        public static Version getVersion​(Class<?> type)
        Lookup version for provided class.

        Version number is determined by either:

        • Use of jar naming convention, matching jars such as jts-1.13.jar
        • Use of MANIFEST.MF (to check Implementation-Version, Project-Version)
        • To assist
        Returns:
        Version (or null if unavailable)

      • getManifest

        public static Manifest getManifest​(Class<?> type)
        Lookup the MANIFEST.MF for the provided class.

        This can be used to quickly verify packaging information.

        Returns:
        MANIFEST.MF contents, please note contents may be empty when running from IDE

      • setLoggerFactory

        public static void setLoggerFactory​(LoggerFactory<?> factory)
        Sets the global logger factory.

        This method is the same as calling Logging#setLoggerFactory(factory) to configure both Logging.ALL logger creation.

        GeoTools provides logback, log4j, reload4j, and commons-logging factories. This method exists to allow you supply your own implementation (when using a GeoTools library in an exotic environment like Eclipse, OC4J or your application).

        If null is used, the Java logging formatter for console output is replaced by a monoline formatter.

        Parameters:
        factory - The logger factory to use, or null for native java util logging.
        Since:
        2.4
        See Also:
        Logging.setLoggerFactory(LoggerFactory)

      • init

        public static void init​(Hints hints)
        Initializes GeoTools for use. This convenience method performs various tasks (more may be added in the future), including setting up the Java logging framework in one of the following states:

        • If Logback is available, then messages in org.geotools and javax.media.jai namespace sent to logger are redirected to SL4J API used by logback.
        • Otherwise if Log4J is available, then messages in org.geotools and javax.media.jai namespace sent to Java logger are redirected to Log4J API.
        • Otherwise if Reload4J is available, then messages in org.geotools and javax.media.jai namespace sent to Java logger are redirected to Log4J 1 API used by Reload4J.
        • finally if Commons-logging is available, then messages in org.geotools and javax.media.jai namespaces sent to the Java logger are redirected to Commons-logging.
        • Otherwise, the Java logging formatter for console output is replaced by a monoline formatter.

        In addition, the default hints are initialized to the specified hints.

        Invoking this method is not required for the GeoTools library to function. It is just a convenience method for overwriting select Java and GeoTools default settings. Supplying these defaults is not desirable in all settings, such as writing test cases.

        Example of typical invocation in a GeoServer environment: 

        
 Hints hints = new Hints();
 hints.put(Hints.FORCE_LONGITUDE_FIRST_AXIS_ORDER, Boolean.TRUE);
 hints.put(Hints.FORCE_AXIS_ORDER_HONORING, "http");
 GeoTools.init(hints);
        Parameters:
        hints - The hints to use.
        See Also:
        Logging.setLoggerFactory(String), Logging.forceMonolineConsoleOutput(), Hints.putSystemDefault(java.awt.RenderingHints), getDefaultHints()

      • init

        public static void init()
        Initializes GeoTools for use. This convenience method performs various tasks (more may be added in the future)

        Primary task is setting up the Java logging framework with a logging factory (if it has not been done already):

        • If Logging.ALL has already been configured no further work is required.
        • Otherwise if Logback is available, then messages in org.geotools and javax.media.jai namespace sent to logger are redirected to SL4J API used by logback.
        • Otherwise if Log4J is available, then messages in org.geotools and javax.media.jai namespace sent to Java logger are redirected to Log4J API.
        • Otherwise if Reload4J is available, then messages in org.geotools and javax.media.jai namespace sent to Java logger are redirected to Log4J 1 API used by Reload4J.
        • Otherwise if Commons-logging is available, then messages in org.geotools and javax.media.jai namespaces sent to the Java logger are redirected to Commons-logging.
        • Otherwise, the Java logging formatter for console output is replaced by a monoline formatter.

        Invoking this method is not required fpr the GeoTools library to function. It is just a convenience method for overwriting select Java and GeoTools default settings. Supplying these defaults is not always desirable, for example when quickly writing test cases.

        See Also:
        Logging.setLoggerFactory(String), Logging.forceMonolineConsoleOutput(), Hints.putSystemDefault(java.awt.RenderingHints), getDefaultHints()

      • init

        public static void init​(InitialContext initialContext)
        Provides GeoTools with the JNDI context for resource lookup.
        Parameters:
        initialContext - The initial context to use for JNDI lookup
        Since:
        2.4
        See Also:
        jndiLookup(String)

      • getDefaultHints

        public static Hints getDefaultHints()
        Returns the default set of hints used for the various utility classes. This default set is determined by:

        Long term plan: We would like to transition the utility classes to being injected with their required factories, either by taking Hints as part of their constructor, or otherwise. Making this change would be a three step process 1) create instance methods for each static final class method 2) create an singleton instance of the class 3) change each static final class method into a call to the singleton. With this in place we could then encourage client code to make use of utility class instances before eventually retiring the static final methods.

        Returns:
        A copy of the default hints. It is safe to add to it.

      • addDefaultHints

        public static Hints addDefaultHints​(Hints hints)
        Used to combine provided hints with global GeoTools defaults.

      • getEntityResolver

        public static EntityResolver getEntityResolver​(Hints hints)
        Returns the default entity resolver, used to configure SAXParser.
        Parameters:
        hints - An optional set of hints, or null if none, see Hints.ENTITY_RESOLVER.
        Returns:
        An entity resolver (never null)

      • getInitialContext

        @Deprecated
public static InitialContext getInitialContext()
                                        throws NamingException
        Deprecated.
        Please use jndiLookup(String) instead, or provide an InitialContext to the init(InitialContext) method and use it directly.
        Returns the default initial context.
        Returns:
        The initial context (never null).
        Throws:
        NamingException - if the initial context can't be created.

      • isJNDIAvailable

        public static boolean isJNDIAvailable()
        Checks if JNDI is available, either because it was initialized, or because it was possible to create one.

      • setJNDINameValidator

        public static void setJNDINameValidator​(Predicate<String> validator)
        Sets up a function that will be called to validate the JNDI lookups. If not set, the DEFAULT_JNDI_VALIDATOR is used. The function may want to log the reason why a given name was denied lookup.
        Parameters:
        validator - A function returning true if the lookups are meant to be performed, false otherwise.

      • jndiLookup

        public static Object jndiLookup​(String name)
                         throws NamingException
        Looks up an object from the JNDI InitialContext. By default, it only allows lookups with no scheme, or inside the java scheme. One can set up a custom name validation routine using
        Parameters:
        name -
        Returns:
        Throws:
        NamingException

      • clearInitialContext

        public static void clearInitialContext()
                                throws NamingException
        Clears the initial context (closes it if not null)
        Throws:
        NamingException
        Since:
        15.0

      • fixName

        @Deprecated
public static String fixName​(String name)
        Deprecated.
        With no replacement, GeoTools now uses JNDI lookups as instructed in jndiLookup(String), but does not put any object in the contex, the downstream application should do it if necessary instead.
        Converts a GeoTools name to the syntax used by the GeoTools JNDI context. Names may be constructed in a variety of ways depending on the implementation of InitialContext. GeoTools uses "jdbc:EPSG" internally, but many implementaitons use the form "jdbc/EPSG". Calling this method before use will set the name right.
        Parameters:
        name - Name of the form "jdbc:EPSG", or null.
        Returns:
        Name fixed up with Context.composeName(String,String), or null if the given name was null.
        Since:
        2.4

      • fixName

        @Deprecated
public static String fixName​(Context context,
                             String name)
        Deprecated.
        With no replacement, GeoTools now uses JNDI lookups as instructed in {@link * #jndiLookup(String)}, but does not put any object in the contex, the downstream * application should do it if necessary instead.
        Converts a GeoTools name to the syntax used by the specified JNDI context. This method is similar to fixName(String), but uses the specified context instead of the GeoTools one.
        Parameters:
        context - The context to use, or null if none.
        name - Name of the form "jdbc:EPSG", or null.
        Returns:
        Name fixed up with Context.composeName(String,String), or null if the given name was null.
        Since:
        2.4

      • addFactoryIteratorProvider

        public static void addFactoryIteratorProvider​(FactoryIteratorProvider provider)
        Adds an alternative way to search for factory implementations. FactoryRegistry has a default mechanism bundled in it, which uses the content of all META-INF/services directories found on the classpath. This addFactoryIteratorProvider method allows to specify additional discovery algorithms. It may be useful in the context of some frameworks that use the constructor injection pattern, like the Spring framework.
        Parameters:
        provider - A new provider for factory iterators.

      • removeFactoryIteratorProvider

        public static void removeFactoryIteratorProvider​(FactoryIteratorProvider provider)
        Removes a provider that was previously added. Note that factories already obtained from the specified provider will not be deregistered by this method.
        Parameters:
        provider - The provider to remove.

      • addChangeListener

        public static void addChangeListener​(ChangeListener listener)
        Adds the specified listener to the list of objects to inform when system-wide configuration changed.
        Parameters:
        listener - The listener to add.

      • removeChangeListener

        public static void removeChangeListener​(ChangeListener listener)
        Removes the specified listener from the list of objects to inform when system-wide configuration changed.
        Parameters:
        listener - The listener to remove.

      • fireConfigurationChanged

        public static void fireConfigurationChanged()
        Informs every listeners that system-wide configuration changed.

      • addClassLoader

        public static void addClassLoader​(ClassLoader classLoader)
        Adds a class loader to be included in the list of class loaders that are used to locate GeoTools plug-ins.

        Client code that calls this method may also need to call FactoryRegistry.scanForPlugins() on any existing registry to force it to clear its cache and use the added class loader to locate plugins.

        Parameters:
        classLoader - The class loader.

      • main

        public static void main​(String... args)
        Reports the GeoTools version number to the standard output stream.
        Parameters:
        args - Command line arguments.