public class ProximityClient extends Object implements Closeable
To create a client, you must specify:
Modifier and Type | Class and Description |
---|---|
static class |
ProximityClient.ClientParams
Parameter object for configuring a
ProximityClient 's behavior. |
static interface |
ProximityClient.InnerClient |
static interface |
ProximityClient.Introspector
Methods that are not designed for high-throughput use, but for exploring or debugging the geopulse client
while developing.
|
static class |
ProximityClient.InvalidLocationException |
Modifier and Type | Method and Description |
---|---|
void |
awaitOK()
Blocks until the client is in SyncState.OK.
|
void |
close() |
Set<String> |
getActiveBuilds()
Returns a set representing the ids of the active builds.
|
String |
getDesignId(String buildId)
Returns the id of the design associated with the build.
|
String |
getDesignName(String buildId)
Returns the name of the design associated with the build.
|
long |
getMaxMemory()
Returns the specified maximum memory usage, in bytes
|
String |
getPartnerId()
Returns the associated partner id.
|
String |
getPath()
Returns the associated file system path.
|
long |
getRequiredMemory()
Returns the bytes required by the current configuration.
|
SyncState |
getSyncState()
Returns the current sync state for the client.
|
List<String> |
getTargetingCodes(String buildId)
Returns the targeting codes in the specified build.
|
ProximityClient.Introspector |
introspect() |
boolean |
isMerged(String buildId)
Return whether the index for given buildId is merged or not.
|
static ProximityClient |
newClient(ProximityClient.ClientParams clientParams)
Creates a new Proximity client.
|
static ProximityClient |
newClient(String organizationId,
String apiKey,
String secretKey,
String path,
long maxMemory)
Deprecated.
as of 5.0.0 - use
newClient(ClientParams) instead, as additional overloads
for newClient will not be added to correspond to new fields in ProximityClient.ClientParams . |
static ProximityClient |
newClient(String organizationId,
String apiKey,
String secretKey,
String path,
long maxMemory,
List<String> deploymentTags)
Creates a new Proximity client.
|
List<Match> |
testMultiplePoints(List<Coordinate> points,
int hitCountThreshold)
Deprecated.
as of 5.3.0
|
List<Match> |
testPoint(double latitude,
double longitude)
Test the given lat/lng point against all the current set of Proximity indices.
|
List<Match> |
testPoint(double latitude,
double longitude,
boolean validate)
Test the given lat/lng point against all the current set of Proximity indices.
|
List<Match> |
testPoint(double latitude,
double longitude,
boolean validate,
boolean omitPayload)
Test the given lat/lng point against all the current set of Proximity indices.
|
public static ProximityClient newClient(String organizationId, String apiKey, String secretKey, String path, long maxMemory) throws IllegalArgumentException
newClient(ClientParams)
instead, as additional overloads
for newClient
will not be added to correspond to new fields in ProximityClient.ClientParams
.ProximityClient
without setting any deployment tags. See newClient(String, String,
String, String, long, List)
for documentation on all the parameters.IllegalArgumentException
public static ProximityClient newClient(String organizationId, String apiKey, String secretKey, String path, long maxMemory, List<String> deploymentTags) throws IllegalArgumentException
organizationId
- the organization-id provided by FactualapiKey
- the API key, available via http://factual.comsecretKey
- the secret key, available via http://factual.compath
- the filesystem path for the directory which will be used for caching data filesmaxMemory
- the maximum memory, in bytes, which will be used by the client. If the required memory for
the latest configuration exceeds this value, getSyncState() will return
SyncState.INSUFFICIENT_MEMORYdeploymentTags
- specifies which indices should be loaded in this client. If more than one deployment
tag is specified, only indices which have ALL the tags will be loaded.IllegalArgumentException
- if another client has been created for the same organizationId on a different
path or with a different maxMemory.public static ProximityClient newClient(ProximityClient.ClientParams clientParams) throws IllegalArgumentException
clientParams
- IllegalArgumentException
- if another client has been created for the same organizationId on a different
path or with a different maxMemory.public void close()
close
in interface Closeable
close
in interface AutoCloseable
public ProximityClient.Introspector introspect()
public List<Match> testPoint(double latitude, double longitude, boolean validate, boolean omitPayload) throws IOException, ProximityClient.InvalidLocationException
latitude
- longitude
- validate
- if true, an InvalidLocationException will be thrown when the coordinates do not seem to be
from a valid sourceomitPayload
- if false, returns the payload and returns one ProximityMatch per location, rather than
per targeting code.IOException
ProximityClient.InvalidLocationException
public List<Match> testPoint(double latitude, double longitude, boolean validate) throws IOException, ProximityClient.InvalidLocationException
latitude
- longitude
- validate
- if true, an InvalidLocationException will be thrown when the coordinates do not seem to be
from a valid sourceIOException
ProximityClient.InvalidLocationException
public List<Match> testPoint(double latitude, double longitude) throws IOException
latitude
- longitude
- IOException
public List<Match> testMultiplePoints(List<Coordinate> points, int hitCountThreshold) throws IOException
hitCountThreshold
points.
Note that only Proximity builds with exactly one geofence set will be included in this query.
This method may have a lot of influence on overall performance: see the PERFORMANCE.html file for recommendations on how to get good QPS/latency from it.
points
- The points to test.hitCountThreshold
- The minimum number of points that must be matched by an index in order to return a
Match
. Should be in the range [0, points.size()]
.IOException
public Set<String> getActiveBuilds()
public String getDesignId(String buildId)
public String getDesignName(String buildId)
public List<String> getTargetingCodes(String buildId)
public boolean isMerged(String buildId)
public SyncState getSyncState()
SyncState.INITIALIZING
, the client is still loading the latest geofence configuration. It can
safely be queried during this time, but only a subset of geofences may be available.
SyncState.OK
, everything is working properly.
SyncState.CANNOT_CONNECT
, the client is unable to contact Factual to check for updated Proximity
geofences. The client will continue work normally during this state, but new configurations will not be
downloaded. If the outage lasts for months, the Proximity data may expire and become unusable.
SyncState.INSUFFICIENT_MEMORY
, the current set of Proximity geofences cannot fit in the size
specified by maxMemory. The required memory can be found by calling .getRequiredMemory(). A client in this
state cannot update, and this issue can only be resolved by increasing maxMemory, or decreasing the size of
the Proximity configuration.
public void awaitOK() throws InterruptedException
This function can be used in cases where you don't wish to use the client until the latest configuration is loaded. If the client is unable to reach Factual's servers, this may block for arbitrarily long times.
InterruptedException
public long getRequiredMemory()
public long getMaxMemory()
public String getPartnerId()
public String getPath()