Package com.iizix.geo

Class RegionLocationService

  • Direct Known Subclasses:
    GeoPlugin, IPStack, IPWhoIs

    public abstract class RegionLocationService
    extends java.lang.Object
    Region location service that is used to find the region location information from an IP address.
    Author:
    Christopher Mindus
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.nio.charset.Charset ENCODING
      Always UTF-8 encoded.
      static java.lang.String ENCODING_NAME
      The "UTF-8" string.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected RegionLocationService​(java.lang.String name, long defaultTimeout)
      Constructs the service provider for the region location information.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void configure​(int localCacheSize, boolean useGlobalCache, boolean doSaveToGlobalCache)
      Configures the service provider.
      HostNameRegionLocation createRegionLocation​(HostNameOrAddress host)
      Requests a region location for a host name or IP address (version 4 or 6).
      HostNameRegionLocation createRegionLocation​(java.lang.String host)
      Requests the region location from a host name or IP address (version 4 or 6).
      HostNameRegionLocation createRegionLocation​(java.net.InetAddress address)
      Requests the region location from an IP address (version 4 or 6).
      static java.lang.String getDefaultName()
      Gets the default region location provider name.
      static RegionLocationService getInstance​(java.lang.String name)
      Gets an instance of a RegionLocationDetectionService.
      java.lang.String getName()
      Gets the name of the region location service.
      static java.lang.String[] getNames()
      Gets the available names for the region location providers.
      static void initialize​(RegionLocationService service)
      Initializes the region location detection service with the service provider.
      protected boolean isAvailable()
      Returns if the service provider is available to use.
      boolean isDisposed()
      Checks if the service provider is disposed of.
      protected void onDisposed()
      Disposes of the region service provider.
      protected JSONObject parse​(java.net.URLConnection uc)
      Process a HTTP[S] URL connection and return a JSONObject.
      protected abstract RegionLocation request​(java.lang.String ipAddress)
      Requests region location information from the service provider.
      static void setGlobalCacheSize​(int size, boolean useDaemonThreads)
      Sets the maximum global cache size.
      static void shutdown()
      Called when the server is shutting down and disposes all service providers.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • ENCODING

        public static final java.nio.charset.Charset ENCODING
        Always UTF-8 encoded.
      • ENCODING_NAME

        public static final java.lang.String ENCODING_NAME
        The "UTF-8" string.
    • Constructor Detail

      • RegionLocationService

        protected RegionLocationService​(java.lang.String name,
                                        long defaultTimeout)
        Constructs the service provider for the region location information. The server will once constructed, register the service with its name.
        Parameters:
        name - The service name.
        defaultTimeout - The default timeout.
        Throws:
        java.lang.NullPointerException - If name is null.
        java.lang.IllegalArgumentException - If the defaultTimeout is less than 5000ms.
    • Method Detail

      • setGlobalCacheSize

        public static void setGlobalCacheSize​(int size,
                                              boolean useDaemonThreads)
        Sets the maximum global cache size.
        Parameters:
        size - The size: must be larger than 100.
        useDaemonThreads - Flag to use daemon threads, true for normal server operations, false for testing.
        Throws:
        java.lang.IllegalArgumentException - If size is smaller than 100.
        java.lang.IllegalStateException - If not called from the server.
      • initialize

        public static void initialize​(RegionLocationService service)
        Initializes the region location detection service with the service provider. This code is called from the server.
        Parameters:
        service - The RegionLocationDetectionService instance.
        Throws:
        java.lang.NullPointerException - If the service is null.
        RegionLocationService - If service's name is already initialized.
      • shutdown

        public static void shutdown()
        Called when the server is shutting down and disposes all service providers.
        Throws:
        java.lang.IllegalStateException - If this method is not called from the server.
      • getNames

        public static java.lang.String[] getNames()
        Gets the available names for the region location providers.
        Returns:
        The names.
      • getDefaultName

        public static java.lang.String getDefaultName()
        Gets the default region location provider name.
        Returns:
        The name, or null if no providers are initialized.
      • getInstance

        public static RegionLocationService getInstance​(java.lang.String name)
        Gets an instance of a RegionLocationDetectionService.
        Parameters:
        name - The name of the RegionLocationDetectionService, null for default.
        Throws:
        java.lang.IllegalArgumentException - If the name is invalid.
        java.lang.IllegalStateException - If the service is not initiated with correct settings (such as keys, etc).
      • configure

        public final void configure​(int localCacheSize,
                                    boolean useGlobalCache,
                                    boolean doSaveToGlobalCache)
        Configures the service provider.
        Parameters:
        localCacheSize - Local cache size, zero for none.
        useGlobalCache - Flag to enable usage of global cache prior to asking the service provider.
        doSaveToGlobalCache - Flag to save requests answered by the service provider to the global cache.
        Throws:
        java.lang.IllegalStateException - If provider is already configured.
      • isAvailable

        protected boolean isAvailable()
        Returns if the service provider is available to use.

        Subclasses override this method to return another value than true.

        Returns:
        true for OK to use, false if not properly configured.
      • getName

        public final java.lang.String getName()
        Gets the name of the region location service.
        Returns:
        The name.
      • createRegionLocation

        public final HostNameRegionLocation createRegionLocation​(java.net.InetAddress address)
        Requests the region location from an IP address (version 4 or 6).
        Parameters:
        address - The IPv4/IPv6 address.
        Throws:
        java.lang.NullPointerException - If address is null.
      • createRegionLocation

        public final HostNameRegionLocation createRegionLocation​(java.lang.String host)
                                                          throws java.net.UnknownHostException
        Requests the region location from a host name or IP address (version 4 or 6).
        Parameters:
        host - The host name or IPv4/IPv6 address.
        Throws:
        java.lang.NullPointerException - If hostName is null.
        java.net.UnknownHostException - If hostName InetAddress cannot be determined.
      • createRegionLocation

        public final HostNameRegionLocation createRegionLocation​(HostNameOrAddress host)
        Requests a region location for a host name or IP address (version 4 or 6).
        Parameters:
        host - The host name or IPv4/IPv6 address.
        Throws:
        java.lang.NullPointerException - If host is null.
      • parse

        protected final JSONObject parse​(java.net.URLConnection uc)
                                  throws java.io.IOException
        Process a HTTP[S] URL connection and return a JSONObject.
        Parameters:
        uc - The URLConnection, should be Http(s)UrlConnection.
        Returns:
        A JSONObject.
        Throws:
        java.io.IOException - For failures.
      • isDisposed

        public boolean isDisposed()
        Checks if the service provider is disposed of.
        Returns:
        true if service provider is disposed of, false otherwise.
      • request

        protected abstract RegionLocation request​(java.lang.String ipAddress)
                                           throws java.io.IOException,
                                                  java.io.InterruptedIOException,
                                                  java.lang.InterruptedException
        Requests region location information from the service provider. When the request has completed with or without error, call
        Parameters:
        ipAddress - The IP address request.
        Returns:
        The region location information, must always be non-null.
        Throws:
        java.io.IOException - For I/O errors.
        java.io.InterruptedIOException - If an I/O operation is interrupted.
        java.lang.InterruptedException - If thread is interrupted.
      • onDisposed

        protected void onDisposed()
        Disposes of the region service provider. This is done by the server when it is shutting down. Any pending requests that are not yet processed are canceled by the framework.

        Subclasses override this method to perform some kind of custom clean-up such as e.g. closing a database.