Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

On This Page:

Table of Contents

EagleML REST API

The EagleML API library can execute requests in asynchronous or synchronous mode.

  • The asynchronous mode receives the reply from EagleML API through 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 executes the request and waits for the TSR/reply on the same connection.

...

To use the library, add the following dependency:

...

On this page

Table of Contents
minLevel1
maxLevel2
outlinefalse
styledefault
typelist
printabletrue

 Execute Requests in the Eagle ML APL Library

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

To use the library, add the following dependency: In the gradle.build script add:

...

Code Block
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 example should be executed only once.

Code Block
languagejava

...

...

// 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");

// Optional - set the name of the stream to which RTR will be sent.
//eaglemlApi.setSendToStream("eagle_ml-2-0_default_out_extract_service");

// 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);

...

After the initial request, you can execute multiple requests concurrently on the eaglemlApi object.

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

Code Block
languagejava

...

...

eaglemlApi.stop();

Execute the Request Asynchronously

You can execute the requests only after EagleML Client API is started using the EagleApi.start() method. You can execute the asynchronous requests in two modes:

  • Wait on a Future<IEagleApiResult> object

  • Asynchronous execution with a callback

Wait on a Future<IEagleApiResult> object

The following is an example of a wait on a Future<IEagleApiResult> object.

Code Block
languagejava

...

// 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

The following is an example of an asynchronous execution with a callback.

Code Block
languagejava

...

...

•	// 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, businessTaskId, 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;
        }
   

...

 }
});

Execute the Request Synchronously

You can execute the request synchronously by following the sample below. Requests can be executed only after the eaglemlApi.start() has been called.

Code Block
languagejava

...

...

// 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 the following in the console:

...

Code Block
-execution=sync -rest

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

...

(The contentType and pathToFile are optional.)

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

The contentType and pathToFile are optional.

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

...

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

In synchronous mode, the client:

  1. Sends a REST request.

  2. Saves the response in the temporary folder with correlation id as its name. The temporary folder is the system %TEMP%. For example: C:\Users\admin\AppData\Local\Temp\. This folder is not purged automatically.

  3. Moves to the next request on the list.

Asynchronous Mode

To enable asynchronous mode, enter the following in the console:

...

Code Block
-execution=async -rest

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

...

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

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

...

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

In asynchronous mode,

...

 do the following:

  1. Create a callback. 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 is unregistered and the timeout error is displayed. For example, a 5 min t/o:

...

Code Block
-timeout=300

2.

...

 Execute a REST request. The request contains x-eagle-rest-callback header with the IP address of the Eagle API client, the communication port and /eagleapicallback suffix. For example:

...

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

3. 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.

4. The client receives the ACK and waits for incoming multiparts (TSR+data).

5. On multipart arrival it switches off the callback (the port is free now).

6. Parses the TaskStatusResponse to understand if its task status is SUCCESS, FAILED or NO_DATA.

- If the status is SUCCESS, the result data is uploaded as an archive file and saved in the temporary folder with correlation id as its name. The temporary folder is the system %TEMP%. For example: C:\Users\admin\AppData\Local\Temp\. This folder is not purged automatically.

- If a folder is specified in the resultsdir parameter, the result data is 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, an error description is displayed.

- If the multipart does not arrive before the timeout expires, the callback is unregistered and a timeout error is displayed.

Available Settings

Name

Valid Values

Description

-login

username

The username to log in the environment

EAGLEAPIPASS

password

The 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

The Endpoint address

-file

file path

The path to the file with the query.

-execution

sync or async

The execution mode. This can be synchronous or asynchronous.

Query File Details

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

...

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

It should be formatted as follows:

...

Code Block
httpMethod|httpPath|basecorrid|contentType|pathToFile

contentType and pathToFile are not necessaryoptional.

For example:

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

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

Examples of Use

Synchronous Mode

In the example below, the EagleMLAPI Client is launched in synchronous mode from the command line.

The request is formed in this query:

...

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

To start execution, execute the following command:

...

Code Block
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, two asynchronous requests are launched.

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

...

Code Block
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, execute the following command:

...

Code Block
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