EagleML REST API

The EagleMLApi library can execute the requests in Asynchronous or Synchronous mode.

The Asynchronous mode will receive the reply from EagleML API thru a callback. The EagleML API client sends a REST request to MC2 and waits for the Task Status Reply and the extract data to be delivered asynchronously when ready via a callback.

The Synchronous mode will execute the request and will wait for the TSR/reply on the same connection.

To use the library add the following dependency:

dependencies {
    compile 'com.eagleinvsys.eaglemlapi:eaglemlapiclient:1.2.0'
}

In your gradle.build script add:

repositories {
    maven {
        url "http://inno-artifactory/artifactory/libs-release"
    }
}

Initialization

Before using the EagleML API for REST calls it should be initialized as described here:

// This is the initialization and shutdown code

// Create the eaglemlApi object
String endpoint = "http://url.to.mcserviceeagle.web.server:port";
String login = "eagleuser";
String password = "eaglepassword";
com.eagleinvsys.eagleapi.client.EagleApi eaglemlApi = new EagleApi(endpoint, login, password, null /* by default use java.io.tmpdir temp folder, or specify the path to the temporary folder for big extracts */, true);

// Optional - Add this to enable the CSV metrics reporting
File csvmetricsdir = new File("/apps/eagle/csvmetrics");
eaglemlApi.enableCsvMetricReporter(csvmetricsdir, 0);

// Optional - set the threshold on the extract result size, after which the data is saved to a temporary file. Default is 1MB
//eaglemlApi.setTempFileThreshold(10000000);

// Optional - set the starting callback port number and the number of ports to try. 
// If not specified the operating system will use a random port number.
// You need to do this only if there is a firewall between the EaglemlApi object and Message CenterEagle THICK Application Server, preventing the callback to complete
//eaglemlApi.setStartingCallbackPort(40000);
// Optional - set the number of ports to try. In this example eaglemlApi will attempt to use ports in the range of 40000 to 40020
// If it can not listen to any of these ports it will fail to start.
//eaglemlApi.setNumberOfPortsToTry(20);


// Optional - set the published host address for callbacks. If not set the local host address (one of the interfaces) will be used.
// This is needed only if there is a firewall/NAT between EaglemlApi Client and MessageCenter Eagle THICK Application Servr and Message Center needs a specific IP to execute the callback.
//eaglemlApi.setPublishedHostAddress("192.168.1.104");

// Start the EagleApi listener and initialize the objects required to parse the results.
// Pass true as a parameter to wait for initialization to complete.
// Pass false as a parameter to complete the initialization asynchronously
eaglemlApi.start(true);

The above should be executed only once. After that multiple requests can be executed concurrently on the eaglemlApi object.

To stop the eaglemlApi instance and clean up the resources run:

eaglemlApi.stop();

Executing the request Asynchronously

The requests can be executed only after EagleML Client API was started using the EagleApi.start() method.

The asynchronous requests can be executed in two modes - with an asynchronous callback or by waiting on Future<IEagleApiResult> object.

Waiting on a Future<IEagleApiResult> object

// THIS IS A SAMPLE OF THE REQUEST EXECUTION. REQUESTS CAN BE EXECUTED ONLY AFTER THE eaglemlApi.start() is called.

Map<String, String> parameters = new HashMap<String, String>();

// Add the parameters required to build an URI
// Generate a unique correlationId
// Add the attachments for the POST request
Future<IEagleApiResult> futureResult = eaglemlApi.executeRestRequestAsync("GET", "/eagle/v2/manager-relationships", parameters, correlationId, null, 600 /* timeout in seconds */);
try (IEagleApiResult result = futureResult.get()) {
    switch(result.getResultStatus()) {
        case EagleApiResultStatus.SUCCESS:
            List<IEagleApiResultDataFile> files = result.getDataFiles();
            for (IEagleApiResultDataFile file : files) {
                // See the java doc for the IEagleApiResultDataFile. The file will represent one result.
                // Currently EaglemlApi will produce only one file.
                // You can get a stream of uncompressed data:
                try(InputStream stream = file.getStream()) {
                    // Parse the extract and execute any transformations - for example to JSON
                }
                // If needed you can get the compressed data and get access to the file with the file.isInMemory(), file.getData(), file.getFile()
                // The temporary files (if any) created while processing the extracts will be removed when you close the IEagleApiResult instance.
                // If you want to preserve you'll have to move/copy them here.
            }
            break;
        case EagleApiResultStatus.TIMEOUT:
            // TIMEOUT - report an error
            break;
        case EagleApiResultStatus.ERROR:
            // ERROR - use result.getErrorMessage to get the error message
            break;
        case EagleApiResultStatus.STOPPED:
            // The request execution was stopped, when eaglemlApi.stop() is called
            break;
        case EagleApiResultStatus.NO_DATA:
            // The no data result retrieved. Report this back.
            break;
    }
}

Asynchronous execution with a callback

•	// THIS IS A SAMPLE OF THE REQUEST EXECUTION. REQUESTS CAN BE EXECUTED ONLY AFTER THE eaglemlApi.start() is called.

Map<String, String> parameters = new HashMap<String, String>();

// Add the parameters required to build an URI
// Generate a unique correlationId
// Add the attachments for the POST request
eaglemlApi.executeRestRequestAsync("GET", "/eagle/v2/manager-relationships", parameters, correlationId, null, 600 /* timeout in seconds */, (result, exception) -> {
    if(exception != null) {
     // There was an exception while executing the request. Process it.
    } else {
        switch(result.getResultStatus()) {
            case EagleApiResultStatus.SUCCESS:
                List<IEagleApiResultDataFile> files = result.getDataFiles();
                for (IEagleApiResultDataFile file : files) {
                    // See the java doc for the IEagleApiResultDataFile. The file will represent one extract.
                    // Currently EaglemlApi will produce only one file.
                    // You can get a stream of uncompressed data:
                    try(InputStream stream = file.getStream()) {
                        // Parse the extract and execute any transformations - for example to JSON
                    }
                    // If needed you can get the compressed data and get access to the file with the file.isInMemory(), file.getData(), file.getFile()
                    // The temporary files (if any) created while processing the extracts will be removed when you close the IEagleApiResult instance.
                    // If you want to preserve you'll have to move/copy them here.
                }
                break;
            case EagleApiResultStatus.TIMEOUT:
                // TIMEOUT - report an error
                break;
            case EagleApiResultStatus.ERROR:
                // ERROR - use result.getErrorMessage to get the error message
                break;
            case EagleApiResultStatus.STOPPED:
                // The request execution was stopped, when eaglemlApi.stop() is called
                break;
            case EagleApiResultStatus.NO_DATA:
                // The extract resulted in no data retrieved. Report this back.
                break;
        }
    }
});

Executing the request Synchronously

// THIS IS A SAMPLE OF THE REQUEST EXECUTION. REQUESTS CAN BE EXECUTED ONLY AFTER THE eaglemlApi.start() is called.

Map<String, String> parameters = new HashMap<String, String>();

// Add the parameters required to build an URI
// Generate a unique correlationId
// Add the attachments for the POST request
try (IEagleApiResult result = eaglemlApi.executeRequestAsync("GET", "/eagle/v2/manager-relationships", parameters, correlationId, null, 600 /* timeout in seconds */))
{
        switch(result.getResultStatus()) {
            case EagleApiResultStatus.SUCCESS:
                List<IEagleApiResultDataFile> files = result.getDataFiles();
                for (IEagleApiResultDataFile file : files) {
                    // See the java doc for the IEagleApiResultDataFile. The file will represent one extract.
                    // Currently EaglemlApi will produce only one file.
                    // You can get a stream of uncompressed data:
                    try(InputStream stream = file.getStream()) {
                        // Parse the extract and execute any transformations - for example to JSON
                    }
                    // If needed you can get the compressed data and get access to the file with the file.isInMemory(), file.getData(), file.getFile()
                    // The temporary files (if any) created while processing the extracts will be removed when you close the IEagleApiResult instance.
                    // If you want to preserve you'll have to move/copy them here.
                }
                break;
            case EagleApiResultStatus.TIMEOUT:
                // TIMEOUT - report an error
                break;
            case EagleApiResultStatus.ERROR:
                // ERROR - use result.getErrorMessage to get the error message
                break;
            case EagleApiResultStatus.STOPPED:
                // The request execution was stopped, when eaglemlApi.stop() is called
                break;
            case EagleApiResultStatus.NO_DATA:
                // The extract resulted in no data retrieved. Report this back.
                break;
        }
} catch(EagleApiException e) {
  // Process the exception
};

Command line interface for executing REST requests

Synchronous Mode

To enable synchronous mode enter in the console:

-execution=sync -rest

To launch a single request you can determine all necessary parameters directly in console with the "-data=" option, for example:

-data="httpMethod|httpPath|basecorrid|contentType|pathToFile"

contentType and pathToFile are optional.

When you want to launch several extracts or just want to read all parameters from a file, use the "-file=" option:

-file="C:\Users\User\Documents\my_config.txt"

In synchronous mode the client works like this:

Sends a REST request.
Saved response in the temporary folder with correlation id as its name. (temporary folder is the system %TEMP%, e.g., C:\Users\admin\AppData\Local\Temp\ - this folder is not purged automatically).
The client will move to the next request on the list.

Asynchronous Mode

To enable asynchronous mode enter in the console:

-execution=async -rest

To launch a single request you can determine all necessary parameters directly in console with the "-data=" option, for example:

-data="httpMethod|httpPath|basecorrid|contentType|pathToFile"

When you want to launch several requests or just want to read all parameters from a file, use the "-file=" option:

-file="C:\Users\User\Documents\my_config.txt"

In asynchronous mode the client works like this:

First of all, a callback is created. It is represented by a Jetty HTTP Servlet server which starts to listen on a random free port. You can set a timeout here, when it expires, the callback will be unregistered and the timeout error will be displayed. For example, a 5 min t/o:

-timeout=300

The client then executes REST request. The request will contain x-eagle-rest-callback header with the IP address of the Eagle API client, the communication port and /eagleapicallback suffix, for example:

x-eagle-rest-callback: http://99.99.99.999:63345/eagleapicallback

When the server receives a request with x-eagle-rest-callback header, it sends the TaskAcknowledged (ACK) message back to the client, performs the request, archives the result data, then tries to send a multipart message consisting of the TaskStatusResponse and the result data.
The client receives the ACK and starts to await incoming multiparts (TSR+data).
On multipart arrival it switched off the callback (the port is free now) and:
Parses the TaskStatusResponse to understand if its task status is SUCCESS, FAILED or NO_DATA.
If the status is SUCCESS, the result data will be uploaded as an archive file and saved in the temporary folder with correlation id as its name. (temporary folder is the system %TEMP%, e.g., C:\Users\admin\AppData\Local\Temp\ - this folder is not purged automatically)
If a folder is specified in the “resultsdir” parameter, the result data will be unzipped and stored in this particular folder.
If “resultsdir” is not specified or empty, the extract remains unzipped in the temp folder.
If the status is FAILED or NO_DATA, error description will be displayed.
If the multipart does not arrive before the -timeout expires, the callback will be unregistered and the timeout error will be displayed.

Available Settings

Name	Valid Values	Description
-login	username	Username to log in the environment
EAGLEAPIPASS	password	Password for the environment set as a global system variable. Can be defined in the command line, for example: set EAGLEAPIPASS=my_password
-resultsdir	empty or folder path	The folder in which unzipped result file will be stored. If not specified, the result will remain unzipped in the temp folder
-csvmetricsdir	empty or folder path	The folder in which metrics will be stored
-threads	even number, 1 or greater	Defines the number of separate threads for an async process. For each thread a separate listener are created.
-endpoint	address of the environment	Endpoint address
-file	file path	Path to the file with the query
-execution	sync or async	Execution mode - synchronous or asynchronous

Query File Details

The file with the query is selected by the -file command, for example:

-file="C:\Users\User\Documents\my_config.txt"

It should be formatted as follows:

httpMethod|httpPath|basecorrid|contentType|pathToFile

contentType and pathToFile are not necessaryoptional.

For example:

GET|/eagle/v2/manager-relationships?entityselectiontype=EntityID&entityselectionvalue=EMLFUN10&outputformat=XML|ABCDEF

POST|/eagle/v2|ABCDEF|application/xml|test.xml

Example of Use

Synchronous Mode

In this example we launch EagleMLAPI Client in synchronous mode from the command line.

Request is formed from this query:

-data="GET|/eagle/v2/manager-relationships?entityselectiontype=EntityID&entityselectionvalue=EMLFUN10&outputformat=XML|ABCDEF"

To start execution we execute the following command:

SET EAGLEAPIPASS=eagle1
java -jar eaglemlapiclient-1.0.3-SNAPSHOT.jar "-data=GET|/eagle/v2/manager-relationships?entityselectiontype=EntityID&entityselectionvalue=EMLFUN10&outputformat=XML|ABCDEF" -execution=sync -login=eagleadmin -endpoint=http://sbnyl1312qa003.eagleinvsys.com:20427 -rest

Asynchronous Mode

In this example we are launching 2 asynchronous requests.

Requests are formed from the request.txt query file located in testFolder:

GET|/eagle/v2/manager-relationships?entityselectiontype=EntityID&entityselectionvalue=EMLFUN10&outputformat=XML|ABCDEF

GET|/eagle/v2/manager-relationships?entityselectiontype=EntityID&entityselectionvalue=EMLFUN10|ABCDEF

Two queries are executed in parallel (-threads=2)
To start execution we execute the following command:

SET EAGLEAPIPASS=eagle1
java -jar eaglemlapiclient-1.0.3-SNAPSHOT.jar "-data=GET|/eagle/v2/manager-relationships?entityselectiontype=EntityID&entityselectionvalue=EMLFUN10&outputformat=XML|ABCDEF" -login=eagleadmin -endpoint=http://sbnyl1312qa003.eagleinvsys.com:20427 -threads=2 -rest

Java EagleML API Client

EagleML REST API

Initialization

Executing the request Asynchronously

Waiting on a Future<IEagleApiResult> object

Asynchronous execution with a callback

Executing the request Synchronously

Command line interface for executing REST requests

Synchronous Mode

Asynchronous Mode

Available Settings

Query File Details

Example of Use

Synchronous Mode

Asynchronous Mode