<commit_before># java-iod-client

Java Client for communicating with [IDOL OnDemand](http://www.idolondemand.com)

## About
java-iod-client provides a Java Interface to the IDOL OnDemand APIs to simplify calling the IDOL OnDemand APIs from Java,
allowing consumers of java-iod-client to access IDOL OnDemand in a typesafe way.

## Goals
Currently only a small subset of IDOL OnDemand APIs are supported. The eventual aim to support all the IDOL OnDemand
APIs. We also plan to provide support for asynchronous APIs, and automated error handling of IDOL OnDemand error codes.

If an API you need is not supported, submit a pull request!

## Usage

java-iod-client is available from the central Maven repository.

    <dependency>
        <groupId>com.hp.autonomy.iod</groupId>
        <artifactId>java-iod-client</artifactId>
        <version>0.5.0</version>
    </dependency>

java-iod-client uses [Retrofit](http://square.github.io/retrofit/) as the basis of its HTTP implementation. This
requires the use of a RestAdapter to use the services. We have used [Jackson](https://github.com/FasterXML/jackson) for
JSON transformation, so you will need to use the Jackson Converter. To send multipart requests to IDOL OnDemand
correctly, you will need to wrap this in an IodConverter. An error handler is supplied for parsing error responses from
IDOL OnDemand.

    final RestAdapter restAdapter = new RestAdapter.Builder()
        .setEndpoint("https://api.idolondemand.com/1")
        .setConverter(new IodConverter(new JacksonConverter()))
        .setErrorHandler(new IodErrorHandler())
        .build();

    final QueryTextIndexService queryTextIndexService = restAdapter.create(QueryTextIndexService.class);

You can then call the methods on queryTextIndexService to communicate with IDOL OnDemand.

    final Map<String, Object> params = new QueryTextIndexRequestBuilder()
        .setAbsoluteMaxResults(10)
        .setTotalResults(true)
        .setIndexes("wiki_eng")
        .build();

    final Documents documents = queryTextIndexService.queryTextIndexWithText(
        "myApiKey",
        "cats",
        params);

## Library structure
APIs can be found in the com.hp.autonomy.iod.client.api package. There is one package per category as seen in the IDOL
OnDemand documentation. There is one service per API.

## Asynchronous requests
For asynchronous actions the Retrofit service returns a JobId. We also provide a service which will track the status of
the job IDs.

    final AddToTextIndexJobService addToTextIndexService = new AddToTextIndexJobService(restAdapter.create(AddToTextIndexJobService.class));

The methods on this service take a callback which will be called when the job is completed

    addToTextIndexService.addFileToTextIndex(getApiKey(), file, getIndex(), params, new IodJobCallback<AddToTextIndexResponse>() {
        @Override
        public void success(final AddToTextIndexResponse result) {
            // called if the job succeeds
        }

        @Override
        public void error(final IodErrorCode error) {
            // called if the job fails
        }

        @Override
        public void handleException(final RuntimeException exception) {
            // called if a RuntimeException is thrown during the process
        }
    });


The APIs which are currently asynchronous are

* AddToTextIndex
* DeleteFromTextIndex

## Request Interceptors
For cases where you want to send the same API key with every request, we provide RequestInterceptors. These are
configured when the RestAdapter is created. Most API methods have a version which does not take an API, which can be used
in conjunction with a request interceptor.

    // set up a RestAdapter using a request interceptor
    final RestAdapter restAdapter = new RestAdapter.Builder()
        .setEndpoint("https://api.idolondemand.com/1")<commit_msg>Update README.<commit_after># java-iod-client

Java Client for communicating with [IDOL OnDemand](http://www.idolondemand.com)

## About
java-iod-client provides a Java Interface to the IDOL OnDemand APIs to simplify calling the IDOL OnDemand APIs from Java,
allowing consumers of java-iod-client to access IDOL OnDemand in a typesafe way.

## Goals
Currently only a small subset of IDOL OnDemand APIs are supported. The eventual aim to support all the IDOL OnDemand
APIs. We also plan to provide support for asynchronous APIs, and automated error handling of IDOL OnDemand error codes.

If an API you need is not supported, submit a pull request!

## Usage

java-iod-client is available from the central Maven repository.

    <dependency>
        <groupId>com.hp.autonomy.iod</groupId>
        <artifactId>java-iod-client</artifactId>
        <version>0.5.0</version>
    </dependency>

java-iod-client uses [Retrofit](http://square.github.io/retrofit/) as the basis of its HTTP implementation. This
requires the use of a RestAdapter to use the services. We have used [Jackson](https://github.com/FasterXML/jackson) for
JSON transformation, so you will need to use the Jackson Converter. To send multipart requests to IDOL OnDemand
correctly, you will need to wrap this in an IodConverter. An error handler is supplied for parsing error responses from
IDOL OnDemand.

    final RestAdapter restAdapter = new RestAdapter.Builder()
        .setEndpoint("https://api.idolondemand.com/1")
        .setConverter(new IodConverter(new JacksonConverter()))
        .setErrorHandler(new IodErrorHandler())
        .build();

    final QueryTextIndexService queryTextIndexService = restAdapter.create(QueryTextIndexService.class);

You can then call the methods on queryTextIndexService to communicate with IDOL OnDemand.

    final Map<String, Object> params = new QueryTextIndexRequestBuilder()
        .setAbsoluteMaxResults(10)
        .setTotalResults(true)
        .setIndexes("wiki_eng")
        .build();

    final Documents documents = queryTextIndexService.queryTextIndexWithText(
        "myApiKey",
        "cats",
        params);

## Library structure
APIs can be found in the com.hp.autonomy.iod.client.api package. There is one package per category as seen in the IDOL
OnDemand documentation. There is one service per API.

## Asynchronous requests
For asynchronous actions the Retrofit service returns a JobId. We also provide a service which will track the status of
the job IDs.

    final AddToTextIndexJobService addToTextIndexService = new AddToTextIndexJobService(restAdapter.create(AddToTextIndexJobService.class));

The methods on this service take a callback which will be called when the job is completed

    addToTextIndexService.addFileToTextIndex(getApiKey(), file, getIndex(), params, new IodJobCallback<AddToTextIndexResponse>() {
        @Override
        public void success(final AddToTextIndexResponse result) {
            // called if the job succeeds
        }

        @Override
        public void error(final IodErrorCode error) {
            // called if the job fails
        }

        @Override
        public void handleException(final RuntimeException exception) {
            // called if a RuntimeException is thrown during the process
        }
    });


The APIs which are currently asynchronous are

* AddToTextIndex
* DeleteFromTextIndex
* CreateTextIndex
* DeleteTextIndex

## Request Interceptors
For cases where you want to send the same API key with every request, we provide RequestInterceptors. These are
configured when the RestAdapter is created. Most API methods have a version which does not take an API, which can be used
in conjunction with a request interceptor.

    // set up a RestAdapter using a request interceptor
    final RestAdapter restAdapter = new RestAdapter.Builder()
        .setEndpoint("https://api.idolondemand.com/1")
{'fraction_non_alphanumeric': 0.0648446564393451, 'fraction_numerical': 0.0018048214515921104, 'mean_word_length': 3.670680313064419, 'pattern_counts': {'":': 0, '<': 23, '<?xml version=': 0, '>': 23, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7527607', 'n_tokens_mistral': 2075, 'n_tokens_neox': 1978, 'n_words': 822}