SMILA 1.3.M1 API documentation

Package org.eclipse.smila.http.client

This package provides an easy-to-use helper library to access the SMILA REST API.

See: Description

Package org.eclipse.smila.http.client Description

This package provides an easy-to-use helper library to access the SMILA REST API. The library hides all the HTTP communication and JSON conversion stuff so that you can use the REST API elements using the SMILA data model classes.

See also:

Basics

The following examples and code snippets all apply when you are running SMILA out-of-the box on localhost.

If you are running SMILA on a different host or with a different port (or an altered root context), please see non-default configuration on how to use the Rest Client in these cases.

Interfaces and default implementations

The RestClient interface encapsulates the REST access to SMILA. It provides methods for GET, POST, PUT and DELETE calls to the REST API and represents data using SMILA's Any interface and attachments using the Attachments interface. The latter allow working with binary data in SMILA.

The package org.eclipse.smila.http.client.impl provides a default implementation for the RestClient named DefaultRestClient.

There are two helper classes providing the resources as described in REST API Reference:

Accessing SMILA

To access SMILA via its REST interface, instantiate the DefaultRestClient, like: 
 RestClient restClient = new DefaultRestClient();
The following code snippet creates a job definition, sends it to the JobManager and starts it if posting was successful: 
 final RestClient restClient = new DefaultRestClient();
 final ResourceHelper resourceHelper = new ResourceHelper();
 final String jobName = "crawlCData";
 
 // create job description as an AnyMap
 final AnyMap jobDescription = DataFactory.DEFAULT.createAnyMap();
 jobDescription.put("name", jobName);
 jobDescription.put("workflow", "fileCrawling");
 final AnyMap parameters = DataFactory.DEFAULT.createAnyMap();
 parameters.put("tempStore", "temp");
 parameters.put("jobToPushTo", "importJob");
 parameters.put("dataSource", "file_data");
 parameters.put("rootFolder", "c:/data");
 jobDescription.put("parameters", parameters);
 
 // the resourcehelper provides us with the resource to the jobs API
 // we send the (AnyMap) job description in the POST body
 restClient.post(resourceHelper.getJobsResource(), jobDescription);
 
 // POST (here without a body) to start the Job,
 // the ResourceHelper provides the resource to the named job
 restClient.post(resourceHelper.getJobResource(jobName));
The following snippet checks if the job with the given name is already running, if not, it is started, and a record with an attachment is sent to it. 
 final RestClient restClient = new DefaultRestClient();
 final ResourceHelper resourceHelper = new ResourceHelper();
 final String jobName = "indexUpdate";
 
 // check for a current run of this job
 final AnyMap currentJobRun =
   restClient.get(resourceHelper.getJobResource(jobName)).getMap("runs").getMap("current");
 if (currentJobRun != null && !currentJobRun.isEmpty()) {
   // a current run exists, so we don't need to start one but it may not be running.
   if (!"RUNNING".equalsIgnoreCase(currentJobRun.getStringValue("state"))) {
     // well it's just an example...
     throw new IllegalStateException("Job '" + jobName + "' is not running but has status '"
       + currentJobRun.getStringValue("state") + "'.");
   }
 } else {
   // no current job run, start another one.
   restClient.post(resourceHelper.getJobResource(jobName));
 }
 
 // create attachment with a file's content
 final File file = new File("c:/data/notice.html");
 final Attachments attachments = new AttachmentWrapper("file", file);
 // put some sample metadata
 final AnyMap metadata = DataFactory.DEFAULT.createAnyMap();
 metadata.put("_recordid", "1");
 metadata.put("fileName", file.getCanonicalPath());
 // now post metadata with an attachment from a file.
 // if we had a Record with attachments, we could POST that one...
 // note: we could add more than one attachment using the AttachmentWrapper.
 restClient.post(resourceHelper.getPushRecordToJobResource(jobName), metadata, attachments);

Using Attachments with the RestClient

As seen above, this bundle provides an Attachments interface allowing attachments to be POSTed. An attachment consists of a string key and binary data that will be POSTed as application/octet-stream in a multi-part message.

Handling attachments manually

You can use the AttachmentWrapper in order to add attachments from the following sources if you want to handle attachments manually: There are convenience constructors to provide an attachment when constructing an AttachmentWrapper but you can add more than one attachment and mix the types.

Example: 

 final RestClient restClient = new DefaultRestClient();
 byte[] byteAttachment = new byte[1000];
 String stringAttachment = "string attachment";
 File fileAttachment = new File("c:/data/notice.html");
 InputStream inputStreamAttachment = new FileInputStream(fileAttachment);
 
 AttachmentWrapper attachments = new AttachmentWrapper("byte-data", byteAttachment);
 attachments.add("string-data", stringAttachment);
 attachments.add("file-data", fileAttachment);
 attachments.add("stream-data", inputStreamAttachment);
 
 restClient.post(resource, parameters, attachments);

Handling attachments with records

SMILA Records can also include attachments, and since SMILA's target data units are Records, it is natural, that the RestClient also supports Records (with attachments) directly.

That means that the record's metadata will be sent with the Records' attachments as parts of a multipart message.

Example: 

  final byte[] data1 = ...;
  final byte[] data2 = ...;
  record.setAttachment("data1", data1);
  record.setAttachment("data2", data2);
 
  // POST the record with the attachments
  restClient.post(resourceHelper.getPushRecordToJobResource(jobName), record);

Using the RestClient without the complete development environment

Setting up the classpath

This section describes the steps to follow when using the RestClient from a Java application outside SMILA's JRE. Now you have all means to access SMILA's REST API from another Java application.

E.g. you could now write a simple program that creates and starts up a crawl job and the indexUpdate-job: 

 public class CrawlMyData {
 
   public static void main(String[] args) {
     final RestClient restClient = new DefaultRestClient();
     final ResourceHelper resourceHelper = new ResourceHelper();
     final String jobName = "crawlCData";
 
     // create job description as an AnyMap
     final AnyMap jobDescription = DataFactory.DEFAULT.createAnyMap();
     jobDescription.put("name", jobName);
     jobDescription.put("workflow", "fileCrawling");
     final AnyMap parameters = DataFactory.DEFAULT.createAnyMap();
     parameters.put("tempStore", "temp");
     parameters.put("jobToPushTo", "indexUpdate");
     parameters.put("dataSource", "file_data");
     parameters.put("rootFolder", "c:/data");
     jobDescription.put("parameters", parameters);
 
     try {
       // start the referred job "indexUpdate" that indexes our sent data.
       // We should check if it is still be running, etc..
       restClient.post(resourceHelper.getJobResource("indexUpdate"));
     } catch (RestException e) {
       e.printStackTrace();
     } catch (IOException e) {
       e.printStackTrace();
     }
 
     try {
       // create (or update) the job, we could check if it exists or is running, etc...
       restClient.post(resourceHelper.getJobsResource(), jobDescription);
 
       // POST with no body to start the Job in default mode
       restClient.post(resourceHelper.getJobResource(jobName));
     } catch (RestException e) {
       e.printStackTrace();
     } catch (IOException e) {
       e.printStackTrace();
     }
 
   }
 }

Putting it together

Now start your SMILA application and when it's up, run the application from above and watch the jobs using your preferred REST client (e.g. browser plugin, see Interactive REST tools) at http://localhost:8080/smila/jobmanager/jobs/

You should see:

Wait a bit and you can search your crawled data at http://localhost:8080/SMILA/search.

Using non-default configuration

RestClient and ResourceHelper have default constructors using the standard values for the SMILA application. These are:

If your bundle uses a different root context path, you have to create your ResourceHelper using the actual context path. Also, if your application runs on a different server and/or using a different port, you will have to supply this information to the constructor of the DefaultRestClient (you can omit the leading http://).

E.g. the following code snippet: 

 final RestClient restClient = new DefaultRestClient("host.domain.org:80");
 final ResourceHelper resourceHelper = new ResourceHelper("/context");
creates a client and a resource helper connection to a SMILA instance running on http://host.domain.org:80/context.

You can also use your own connection manager or limit the number of total connections and max connections per host by using the respective constructors of DefaultRestClient.

Since:
1.1.0
SMILA 1.3.M1 API documentation