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.