Idibon Java SDK

Requires JDK 7 or newer, and Maven 3. Some example applications require JDK 8.

The SDK is structured as a multimodule Maven project, with the core API client as

<groupId>com.idibon.api.java-sdk</groupId>
<artifactId>java-api-client</artifactId>
<version>1.0.2-SNAPSHOT</version>

Example apps are located in the examples/ subdirectory.

• To build the API client and all of the example apps, run mvn package from the top-level directory.

• To install the API client JAR in your local maven repository, run mvn install from the top-level directory.

• To generate JavaDocs for the API client, run mvn javadoc:javadoc from the java-api-client/ directory.

Example Apps

All example applications require a valid Idibon Terminal account or, where noted, a locally-installed Idibon Public server.

Name	Description
list-documents	Lists all of the document names in a collection
upload-json-documents	Upload one or more JSON documents to a collection
annotate-document	Add an assignment annotation for a document-scope task to a document
predict-content	Generate text classifications from the command line, using Idibon Terminal
predict-idibon-public	Generate text classifications using an Idibon Public server
print-ontology	Prints a collection ontology, or branch of an ontology, to the console.
show-updated-tasks	List all tasks in a collection updated since a specific time (JDK 8)
batch-predict	Batch classifies documents in a collection or text file against a task in parallel (JDK 8).

list-documents Example App

To run

cd examples/list-documents/target
java -cp list-documents-$SDK_VERSION-jar-with-dependencies.jar \
  com.idibon.ListDocuments $API_KEY $COLLECTION

upload-json-documents Example App

To run

cd examples/upload-json-documents/target
java -cp upload-json-documents-$SDK_VERSION-jar-with-dependencies.jar \
  com.idibon.UploadJsonDocuments $API_KEY $COLLECTION files.json...

JSON files should have the following structure:

{
  "content":$CONTENT,
  "metadata":$METADATA,
  "name":$NAME
}

• $CONTENT should be a String, and include the document content (e.g., e-mail, tweet, or SMS message text).

• $METADATA should be a JSON object of metadata for the document. Any metadata may be submitted, there are no restrictions or expectations about the data that is included. If no metadata is needed, this key can be excluded.

• $NAME should be a String. It is optional; if present, the document will be created using the provided name.

annotate-document Example App

To run

cd examples/annotate-document/target
java -cp annotate-document-$SDK_VERSION.jar-with-dependencies.jar \
  com.idibon.AnnotateDocument $API_KEY $COLLECTION $DOCUMENT $TASK $LABEL

• $DOCUMENT should be the name of a document inside $COLLECTION

• $TASK should be the name of a document-scope task inside $COLLECTION

• $LABEL should be the name of a label within $TASK

predict-content Example App

This example app demonstrates Idibon Terminal's streaming predictive classification capabilities by taking an arbitrary string of text provided on the command line and generating a prediction against a user-defined task. The full classification results, including confidences for each label and significant features, are printed to the console.

To run

cd examples/predict-content/target
java -cp predict-content-$SDK_VERSION-jar-with-dependencies.jar \
  com.idibon.PredictContent $API_KEY $COLLECTION $TASK "Some content..."

• $TASK should be the name of a document-scope task inside $COLLECTION

• Some content should be whatever text you want to predict. It may be provided in quotes or unquoted.

predict-idibon-public Example App

This example is based off of predict-content, but uses an Idibon Public server running on the local system rather than Idibon Terminal.

To run

cd examples/predict-idibon-public/target
java -cp predict-idibon-public-$SDK_VERSION-jar-with-dependencies.jar \
  com.idibon.PredictIdibonPublic $COLLECTION $TASK "Some content..."

• $TASK should be the name of a document-scope task inside $COLLECTION

• Some content should be whatever text you want to predict. It may be provided in quotes or unquoted.

print-ontology Example App

This example app prints an ontology, or a branch of an ontology, using a tree view style visualization to the console. It demonstrates using the task and sub-task navigation features of the SDK.

To run

cd examples/print-ontology/target
java -cp print-ontology-$SDK_VERSION-jar-with-dependencies.jar \
  com.idibon.PrintOntology $API_KEY $COLLECTION [$TASK]

• $TASK is an optional parameter, restricting the print out to just the ontology branch starting at the named task.

show-updated-tasks Example App (JDK 8)

This example app demonstrates how to filter tasks using JDK 8 streams and lambdas based on task metadata properties; in this case, the property is the task's updated_at property.

To run

cd examples/show-updated-tasks/target
java -cp show-updated-tasks-$SDK_VERSION-jar-with-dependencies.jar \
  com.idibon.ShowUpdatedTasks $API_KEY $COLLECTION ISO-8601-Date

• ISO-8601-Date should be an ISO-8601 date string (YYYY-mm-dd'T'HH:mm:ss'Z'); tasks last updated before this time will not be reported.

batch-predict Example App (JDK 8)

This example app uses highly-parallel connections to classify documents stored in a collection, or document content provided by a text file (each line in the text file is treated as an individual document) using a task provided on the command line.

This example uses Java 8 streams and lambdas to sequentially process the classification results.

To run and see the command line options:

cd examples/batch-predict/target
java -cp batch-predict-$SDK_VERSION-jar-with-dependencies.jar \
  com.idibon.BatchPredict -h

Command line options include

Flag	Description
-k <key>	API Key
-c <string>	Collection name
-t <string>	Task name
-n <int>	Maximum number of documents to read from the collection
-i <filename>	Filename of newline-separated documents to classify
-p <int>	Set prediction parallelism (1 - 1000, default 10)