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 Geopulse On-Prem Overview for a higher-level introduction to the On-Prem product.
Expected performance is on the order of five microseconds (0.005 milliseconds) per Set.
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.
Instances of On-Prem require your Factual account API Key and Secret Key, which are found after logging in with your account at “www.factual.com”:http://www.factual.com. If you’re unsure about what credentials to use, please “contact us”:https://www.factual.com/contact#customer_support.
The credentials are requested as a part of the signatures for the On-Prem classes:
AudienceSetClient Java Class in the
com.factual.geopulse.audience package to interact with Geopulse Audience Sets.
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:
ProximityClient in the
com.factual.geopulse.proximity package when looking up Proximity matches.
The Proximity service does not need to be re-started 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:
The response for the
AudienceSetClient Classes are matches 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
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 Factual 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.
Geopulse 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.