.. _java_sdk:

Java SDK
========


==========
QuickStart
==========
The quickest way to get started with Taskmonk is use the upload file and download of output features as shown below. The projectId will be provided by the annotation partner

.. code-block:: java
   :linenos:

    import io.taskmonk.auth.OAuthClientCredentials;
    import io.taskmonk.client.TaskMonkClient;

    import java.io.File;

    public class Test {
        public static void main(String[] args) throws InterruptedException {
            String projectId = "projectId";
            /**
             * Initialize the taskmonk client witht he oauth credentials and projectId
             */
            TaskMonkClient client = new TaskMonkClient(projectId, "demo.taskmonk.io",
                    new OAuthClientCredentials("uIUSPlDMnH8gLEIrnlkdIPRE6bZYhHpw", "zsYgKGLUnftFgkASD8pndMwn3viA0IPoGKAiw6S7aVukgMWI8hGJflFs0P2QYxTg"));

            /*
             * Upload the tasks csv to a new batch that will be created with name batchName
             */
            String batchId = client.uploadTasks("batchName", new File("/Users/taskmonk/tmp.csv")).batchId;

            /*
             * check the returned batch id
             */
            System.out.println("task batch id = " + batchId);

            /*
             * Wait while the tasks are being uploaded to the database
             */
            while (!client.isUploadComplete(batchId)) {
                System.out.println("Upload Not Completed");
                Thread.sleep(1000);
            }
            System.out.println("Upload Completed");

            /*
             * Wait while the tasks are being processed by the analysts
             */
            while (!client.isProcessComplete(batchId)) {
                System.out.println("Processing not complete");
                Thread.sleep(1000);
            }

            /*
             * Get the output in a local csv file
             */
            String outputPath = client.getBatchOutput(batchId);
            System.out.println("outputPath = " + outputPath);
        }
    }

The sample code can be cloned from `Github <https://github.com/taskmonk/taskmonkSDK/tree/master/java/samples>`

===========
Integration
===========
A more detailed version for further integration is shown below:

.. code-block:: java
   :linenos:


    import io.taskmonk.auth.OAuthClientCredentials;
    import io.taskmonk.client.TaskMonkClient;
    import io.taskmonk.entities.*;

    import java.io.File;
    import java.time.LocalDate;
    import java.time.ZoneId;
    import java.util.*;

    public class Test {
        public static Date getDate(LocalDate localDate) {
            return Date.from(localDate.atStartOfDay(ZoneId.systemDefault()).toInstant());
        }

        public static void main(String[] args) throws Exception {

            TaskMonkClient client = new TaskMonkClient("https://preprod.taskmonk.io",
                    new OAuthClientCredentials("client_id", "client_secret"));
            String projectId = "1";
            /*
             * Create a new batch
             */
            String comments = "Special Directions to Annotation Partner";
            Map<String, String> metaData = new HashMap<String, String>();
            metaData.put("email_address", "info@taskmonk.ai");
            Notification notification = new Notification("Email", metaData);

            List<Notification> notifications = new ArrayList<Notification>();
            notifications.add(notification);

            LocalDate tomorrow = LocalDate.now().plusDays(1);
            NewBatchData newBatchData = new NewBatchData()
                    .setPriority(5)
                    .setNotifications(notifications)
                    .setComments(comments)
                    .setStartTime(getDate(tomorrow));
            String batchId = client.createBatch("newBatch", newBatchData);
            System.out.println("batchId = " + batchId);

            // Update the priority
            System.out.println(client.updateBatchPriority(batchId, 20));


            /*
             * Upload files from a file
             */
            TaskImportResponse taskImportResponse = client.uploadTasks(projectId, batchId, new File("/Users/taskmonk/tmp.xlsx"));
            System.out.println("task import job id = " + taskImportResponse.job_id);

            JobProgressResponse jobProgressResponse = client.getJobProgress(taskImportResponse.job_id);
            while (!jobProgressResponse.isCompleted()) {
                System.out.println("waiting for job to complete = " + jobProgressResponse.percentage);
                Thread.sleep(1000);
                jobProgressResponse = client.getJobProgress(taskImportResponse.job_id);
            }
            System.out.println("Completed task import for batch " + batchId);

            Map<String, String> input = new HashMap<String, String>();
            input.put("Serial", "1");
            Task task = new Task(batchId, "1", input);
            List<Task> tasks = new ArrayList<Task>();
            tasks.add(task);
            String uploadJobId = client.uploadTasks(batchId, tasks);

            jobProgressResponse = client.getJobProgress(uploadJobId);
            while (!jobProgressResponse.isCompleted()) {
                System.out.println("waiting for job to complete = " + jobProgressResponse.percentage);
                Thread.sleep(1000);
                jobProgressResponse = client.getJobProgress(uploadJobId);
            }

            /*
             * Get status of batch completion by analysts
             */

            BatchStatus batchStatus = client.getBatchStatus(batchId);
            System.out.println("Completed = " + batchStatus.getCompleted());
            if (batchStatus.getCompleted() == batchStatus.getTotal()) {
                System.out.println("Batch is complete");
                // Get the output of the batch
                String outputPath = "/tmp/output.xlsx";
                client.getBatchOutput(batchId, "Excel", outputPath);
                System.out.println("Batch output saved in " + outputPath);
            }

        }
    }


=========
Streaming
=========

Taskmonk supports a streaming interface built over Azure queues. A send and receive queue pair is created for each project and real-time information can be shared accross this. The queue identifiers and the accessKey for the queues will be provided by Taskmonk for each project. 

The following events are supported from Taskmonk to the client:

**Task Update**


This is sent when a task is completed by the Annotation Partner. The format is shown below::
   
    {
        "message_type": "task_update",
        "task": {
            "project_id": "projectid1",
            "batch_id": "batchid1",
            "fields": {
                "in_fielda": "valuea",
                "in_fieldb": "valueb",
                "out_fieldc": "valuec",
                "out_fieldd": "valued"
            }
        }
    }


**Batch Status**


This is sent whenever a batch event occurs. Some of the events include

* Change in ETA
* Change in Status - Completed, Cancelled, Active

The format is shown below::

    {
        "message_type": "batch_status",
        "batch": {
        {
            "completed": 0,
            "rejected": 0,
            "batch_id": "string",
            "state": "string",
            "eta": "string",
            "created_date": "2019-10-09",
            "batch_name": "string",
            "total": 0,
            "pending": 0,
            "eta_type": "string"
        }
    }


The following events can be sent from the client to Taskmonk:

**New Task**

This is used to upload a set of tasks to Taskmonk. The format is shown below::

    {
        "message_type": "new_tasks",
        "task": [{
                "batch_id": "batchid1",
                "external_id": "item1",
                "data": {
                    "in_fielda": "valuea1",
                    "in_fieldb": "valueb1",
            },
            {
                "batch_id": "batchid1",
                "external_id": "item1",
                "data": {
                    "in_fielda": "valuea2",
                    "in_fieldb": "valueb2",
                }
        ]

        }
    }

-------------
Sample Code
-------------

.. code-block:: java
   :linenos:

        /*
         * Setup the task streamer
         */

        String queueName = "testqueue_fomclient";
        String accessKey = "access_key";
        StreamWriter sender = new StreamWriter(queueName, accessKey);

        /*
         * Send a task on the stream
         */
        Map<String, String> input = new HashMap<String, String>();
        input.put("input1", "value1");
        Map<String, String> output = new HashMap<String, String>();
        Task task = new Task(UUID.randomUUID().toString(),
                "batch_id",
                input);
        List<Task> tasks = new ArrayList<Task>();
        tasks.add(task);
        sender.send("project_id", "batch_id", tasks);
        
        /*
         * Consume results on the stream
         */
        queueName = "testqueue_toclient";
        accessKey = "access_key";
        StreamListener listener = new StreamListener(queueName, accessKey);
        listener.addListener(new MessageListener() {
            @Override
            public MessageAction onTaskUpdate(Task task) {
                System.out.println("Got updated task {}" + task.externalId);
                return MessageAction.COMPLETE;
            }

            @Override
            public MessageAction onBatchStatus(BatchStatus batchStatus) {
                System.out.println("Got batch status {}" + batchStatus);
                return MessageAction.COMPLETE;
            }

            @Override
            public MessageAction onGenericMessage(String message) {
                return null;
            }
        });

** Contact TaskMonk for the queue and access keys to use for the project. **

=============
Documentation
=============

SDK documentation is available at :ref:`api`.

======================
Quickstart with maven
======================


Add the following dependency ::

            <dependency>
                <groupId>ai.taskmonk</groupId>
                <artifactId>taskmonk-sdk</artifactId>
                <version>1.16.2</version>
            </dependency>