Task Service Tutorial

1.0 Overview

This page gives you an introduction to writing a task service in Xenon. A task service will perform long-running tasks on behalf of a client (a user or another Xenon service). Because Xenon is architected to be highly scalable and asynchronous, a service should not delay its response while a long-running task is running. Instead, it should accept the task and allow clients to query for the results later.

1.1 Task Service Workflow

The workflow for a task service is simple, but may be surprising if you have not seen the pattern before.

1. A client (user or another Xenon service) does a POST to the task factory service to create a task. The POST will include all parameters needed to describe the task.
2. The task factory service creates the task service
3. The task factory service will go through a series of steps. For each step, it will:
4. Make some action. In Xenon, this will generally be an asynchronous action that completes at some future time
5. When the action completes, update the state of the task service by doing a PATCH back to the service.
6. When the PATCH is processed, this process repeats with the next action

IMAGE HERE SOON

Task services are good examples of the uniform use of REST throughout Xenon: all state changes and queries between services happen via REST. A service does not treat a request differently if it comes from an external client, another service, or itself.

In a strict technical sense, requests are often not "REST" in that when services are running in the same process, they are optimized, in-process communication instead of HTTP. However, that distinction is transparent to the author of a service: requests are handled identically.

1.2 Assumptions

This tutorial assumes that you have gone through the introductory Example Service Tutorial as well as the Introduction to Service Queries.

This tutorial assumes you have installed Xenon and can run it from the command-line. It also assumes you have installed the "curl" command-line tool. If you don't want to use curl, the examples should be easily converted to use another tool, such as Postman. It also assumes you have installed the jq tool, which we use for formatting JSON responses from Xenon. If you do not have it installed, you can simply remove it from the commands below.

2.0 Starting the Xenon host

We are going to start the Xenon host differently than the previous tutorials:

1. We are going to start a different host, the ExampleServiceHost. This host provides extra arguments to make it easier to work with authorization.
2. We are going to provide an argument for the sandbox (where all service documents are stored), instead of relying on the Java temporary directory. When the host is not running, you can delete the sandbox if you need to get back to "factory settings".

Please note that you will need to change the name of the JAR file to match the version of Xenon you have.

% java -cp xenon-host/target/xenon-host-0.4.1-SNAPSHOT-jar-with-dependencies.jar com.vmware.xenon.services.common.ExampleServiceHost --sandbox=/tmp/xenon
[0][I][1452210831944][ExampleServiceHost:8000][startImpl][ServiceHost/1161b183 listening on 127.0.0.1:8000]

3.0 Experimenting with the ExampleTaskService

The ExampleTaskService is a service that will delete all example service documents. This is a two step process:

1. Make a query for all example service documents
2. Delete all of them.

This will usually run rather quickly (unless you have a huge number of example services to delete), but is a good illustration of how an ExampleTask is written.