On This Page:
Table of Contents |
---|
...
To use the library, add the following dependency:
...
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 | ||
---|---|---|
|
...
...
// 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 | ||
---|---|---|
|
...
...
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 | ||
---|---|---|
|
...
// 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 | ||
---|---|---|
|
...
...
• // 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 | ||
---|---|---|
|
...
...
// 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:
Sends a REST request.
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.
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:
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 |