Getting Started

This document explains the usage of the On-Prem Java Library; reference the Javadoc that ships with the On-Prem Java Library to consult detailed information on the classes themselves, and see the On-Prem Overview for a higher-level introduction to the On-Prem product.

Performance

Expected performance is on the order of five microseconds (0.005 milliseconds) per Set.

Installation

See the On-Prem Overview for details on provisioning, hardware, and memory.

On-Prem Java Library requires Oracle JDK 7 to be installed on your machine.

Configuration

Instances of On-Prem require your Foursquare account API Key and Secret Key, which are found after logging in with your account at targeting.foursquare.com.

Note:

If you cannot locate your API/Secret keys, please contact your Foursquare representative.

The credentials are requested as a part of the signatures for the On-Prem classes:

public static synchronized AudienceSetClient newClient(
    String organizationId,
    String apiKey,
    String secretKey,
    String path,
    long maxMemory,
    List<String> deploymentTags)

public static synchronized ProximityClient newClient(
    String organizationId,
    String apiKey,
    String secretKey,
    String path,
    long maxMemory,
    List<String> deploymentTags)

Using On-Prem Java

Test for Hits Against Active Audience Sets

Use the AudienceSetClient Java Class in the com.factual.geopulse.audience package to interact with Audience Sets.

Use the test method in the AudienceSetClient Class to get Audience Set matches for a specific user/device. The signature differs depending on the version of the On-Prem Java Library you’re using; everything after v4.0 returns a List of “Match Objects”:/geopulse-on-prem-overview#response.

Instructions for querying Audience Sets for your version of the Java Library are documented in the Javadoc that accompanies the Java Library. The method signatures:

public java.util.List<Match> test(java.lang.String canonicalId)
    throws java.io.IOException

Test for Hits Against Active Proximity Filters

Use the ProximityClient in the com.factual.geopulse.proximity package when looking up Proximity matches.

The Proximity service does not need to be restarted when new sets are added. If enough memory has been allocated (as specified in the config file), the new configuration will be automatically loaded.

On-Prem instances will cache the Proximity Sets on disk, and only download sets that weren’t previously used.

The method is called testPoint. Similar to Audience Sets, On-Prem Java Library v4.0 introduced the concept of the Match Object and it caused a change in the method’s signatures as well.

Started from the On-Prem Java Library v3.1.2, the validate flag was also added to the signature. This tells the ProximityClient that any invalid lat/long locations should throw an error.

Here are some examples of the testPoint method’s signature:

public java.util.List<Match> testPoint(double latitude,
    double longitude,
    boolean validate,
    boolean omitPayload)
        throws java.io.IOException,
               ProximityClient.InvalidLocationException

public java.util.List<Match> testPoint(double latitude,
    double longitude,
    boolean validate)
        throws java.io.IOException,
               ProximityClient.InvalidLocationException

public java.util.List<Match> testPoint(double latitude, double longitude)
        throws java.io.IOException

Responses

The response for the ProximityClient and AudienceSetClient Classes are matched to Geopulse Sets.

The details on fetching and parsing responses are well documented in all versions of the On-Prem Java Library’s javadocs, and an overview of the Match Object is provided in the On-Prem Overview.

Thread Safety

The Java Library is thread-safe and can be called simultaneously from multiple threads without any locks or contention. However, it takes time to spin up new threads, so Foursquare recommends against creating new threads in the middle of handling bid requests from the bid stream.

It is better to pre-start threads with Java’s ThreadPoolExecutor. When using the thread pool, you’ll need to handle a RejectedExecutionException when the threads are all busy, which you can treat as a timeout and is handled by processes upstream.

Logs

On-Prem logs to /var/log/factual/outpost/outpost.log by default. It logs a JSON-encoded digest of requests every 10 seconds. Per the init script, logs are rotated daily and can be cleaned up. Under normal conditions it should only be about 1MB a day. The most recent request digest can be fetched from /zz/status. See Server Status for an example of what you should expect to see on that page.