MagicLogic BlackBox Gateway ServiceUnits Class Hierarchy Classes, Interfaces, Objects and Records Types Variables Constants Functions and Procedures Identifiers |
Class TGateway
Unit
GatewayImplementation
Declaration
type TGateway = class(TIdSoapBaseImplementation, IGateway)
Description
This document describes the API for the BlackBox Cartonization / Palletization / Load Planning software. These methods allow the developer to make calls to the BlackBox system to optimize orders ("loads") and retrieve the results using a standard SOAP interface.
Sample code in several common programming languages are available. Please contact support@magiclogic.com for details.
Glossary
BlackBox - an instance of the MagicLogic Optimization software. Job / Job Id - used within the API to uniquely identiy each load (or optimization call). Every call made to the API is assigned a unique Job Id. Load - another name for an order, or shipment. Each load must be sent in a separate method call.
Hierarchy
- TIdSoapBaseImplementation
- TGateway
Overview
Methods
 |
function ClearDatabase(const Username: string; const Password: string; const IPAddress: string; const Port: integer): string; stdcall; |
|
function ClearDatabaseB(const Username: string; const Password: string): string; stdcall; |
|
function ClearJobs(const Username: string; const Password: string; const IPAddress: string; const Port: integer): string; stdcall; |
|
function ClearJobsB(const Username: string; const Password: string): string; stdcall; |
|
function GetAuthorization(const Username: string; const Password: string): Boolean; stdcall; |
|
function GetStats(Username: string; Password: string; IPAddress: string; Port: integer): string; stdcall; |
|
function GetStatus(Username: string; Password: string; IPAddress: string; Port: integer): string; stdcall; |
|
function GetOptimizationProgress(const Username: string; const Password: string; const Job: string): string; stdcall; |
|
function GetOptimization(const Username: string; const Password: string; const Job: string): string; stdcall; |
|
function GetOptimizationZipped(const Username: string; const Password: string; const Job: string): string; stdcall; |
|
function GetCurrentJobs(const Username: string; const Password: string; const IPAddress: string; const Port: integer): string; stdcall; |
|
function GetCurrentJobsB(const Username: string; const Password: string): string; stdcall; |
|
function IsOptimizationComplete(const Username: string; const Password: string; const Job: string): boolean; stdcall; |
|
function PutOptimization(const Username: string; const Password: string; const IPAddress: string; const Port: integer; const Payload: string): string; stdcall; |
|
function PutOptimizationB(const Username: string; const Password: string; const Payload: string): string; stdcall; |
|
function PutOptimizationAsync(const Username: string; const Password: string; const IPAddress: string; const Port: integer; const Payload: string): string; stdcall; |
|
function PutOptimizationAsyncB(const Username: string; const Password: string; const Payload: string): string; stdcall; |
|
function PutInterrupt(const Username: string; const Password: string; const Job: string): string; stdcall; |
|
function PutReloadStaticData(const Username: string; const Password: string; const IPAddress: string; const Port: integer): string; stdcall; |
|
function PutReloadStaticDataB(const Username: string; const Password: string): string; stdcall; |
Description
Methods
|
function ClearDatabase(const Username: string; const Password: string; const IPAddress: string; const Port: integer): string; stdcall; |
|
Clear the in-memory database from the BlackBox running on address IPAddress and port Port
Note that this call will return to the client immedidately, but the database is not necessarily cleared right away.
If the BlackBox is currently processing any orders, it will queue this call until the entire database can be locked, i.e. when all processing has completed.
So you may find it important to schedule this call between submitting orders if the database needs to be guaranteed empty.
Parameters
- Username
- - a valid BlackBox service username
- Password
- - the matching password for the username
- IPAddress
- - the IP address of the BlackBox for which you wish to clear the database
- Port
- - the Port or socket of the BlackBox for which you wish to clear the database
Returns
string - always 200 <blackbox reply="OK"/> |
|
function ClearDatabaseB(const Username: string; const Password: string): string; stdcall; |
|
Clear the in-memory database from ALL BlackBoxes that are known to this service.
Note that this call will return to the client immedidately, but the databases are not necessarily cleared right away.
If any BlackBox is currently processing any orders, it will queue this call until the entire database can be locked, i.e. when all processing has completed.
So you may find it important to schedule this call between submitting orders if the database needs to be guaranteed empty.
Parameters
- Username
- - a valid BlackBox service username
- Password
- - the matching password for the username
Returns
string |
|
function ClearJobs(const Username: string; const Password: string; const IPAddress: string; const Port: integer): string; stdcall; |
|
Remove all running and queued jobs (orders) from the BlackBox on address IPAddress and port Port.
This command can be used to 'reset' a BlackBox, by removing all jobs that the BlackBox is currently handling. It will also clear any jobs which are in its queue (waiting to be processed).
Parameters
- Username
- - a valid BlackBox service username
- Password
- - the matching password for the username
- IPAddress
- - the IP address of the BlackBox for which you wish to clear all jobs
- Port
- - the Port or socket of the BlackBox for which you wish to clear all jobs
Returns
string |
|
function ClearJobsB(const Username: string; const Password: string): string; stdcall; |
|
Remove all running and queued jobs (orders) from all of the BlackBox instances known to this service.
This command can be used to 'reset' all BlackBoxes, by removing all jobs that they are currently handling. It will also clear any jobs which are queued (waiting to be processed).
Parameters
- Username
- - a valid BlackBox service username
- Password
- - the matching password for the username
Returns
string |
|
function GetAuthorization(const Username: string; const Password: string): Boolean; stdcall; |
|
A convenience function to check that the Username and Password provided are known to the service.
This function does not need to be called before other methods are used; it is provided purely for validation purposes.
Parameters
- Username
- - a valid BlackBox service username
- Password
- - the matching password for the username
Returns
boolean: true - username/password combination is valid, false - username/password combination is not valid |
|
function GetStats(Username: string; Password: string; IPAddress: string; Port: integer): string; stdcall; |
|
Fetch the usage and performance statistics for the BlackBox on address IPAddress and port Port.
The reply takes the form of a small XML document. Please refer to the appendix for an example.
Parameters
- Username
- - a valid BlackBox service username
- Password
- - the matching password for the username
- IPAddress
- - the IP address of the BlackBox for which you wish to clear all jobs
- Port
- - the Port or socket of the BlackBox for which you wish to clear all jobs
Returns
string: XML-formatted text containing the statistics |
|
function GetStatus(Username: string; Password: string; IPAddress: string; Port: integer): string; stdcall; |
|
Requests the BlackBox to return its current status. Status messages are short XML strings in the following form: <blackbox status="ok" usage="5909" uptime="8 3:48:28"/>
Status is currently always reported as “ok”. Usage is an integer value which simply represents the total number of orders optimized since the BlackBox was started. Uptime is in the format “days hours:minutes:seconds”
Parameters
- Username
- - a valid BlackBox service username
- Password
- - the matching password for the username
- IPAddress
- - the IP address of the BlackBox for which you wish to clear all jobs
- Port
- - the Port or socket of the BlackBox for which you wish to clear all jobs
Returns
string: XML-formatted text containing the status text |
|
function GetOptimizationProgress(const Username: string; const Password: string; const Job: string): string; stdcall; |
|
This function can be called to find out the current status of a job that was previously submitted using PutOptimizationAsync or PutOptimizationAsyncB.
It can be called any number of times for the same job id, and should be used to ensure that this job is complete before trying to retrieve the results (using GetOptimization or GetOptimizationZipped).
This meothd is extremely useful since it means that you can call this function in a loop to monitor the status of the optimization, to provide feedback if you would like to update a user as to its status and progress.
Parameters
- Username
- - a valid BlackBox service username.
- Password
- - the matching password for the username.
- Job
- - a valid BlackBox job id, as returned from a prior call to either PutOptimizationAsync or PutOptimizationAsyncB.
Returns
string: XML document describing the current status of the job (see appendix for more information). |
|
function GetOptimization(const Username: string; const Password: string; const Job: string): string; stdcall; |
|
Retrieve a completed job that was previously sent to a BlackBox using the PutOptimizationAsync or PutOptimizationAsyncB methods.
This method should be only used when an optimization is known to be complete (see GetOptimizationProgress).
This method deletes the job from the BlackBox's internal database. It cannnot be retrieved again.
Parameters
- Username
- - a valid BlackBox service username.
- Password
- - the matching password for the username.
- Job
- - a valid BlackBox job id, as returned from a prior call to either PutOptimizationAsync or PutOptimizationAsyncB.
Returns
string: a complete XML self-contained document defining the optimzation results. |
|
function GetOptimizationZipped(const Username: string; const Password: string; const Job: string): string; stdcall; |
|
Retrieve a completed job that was previously sent to a BlackBox using the PutOptimizationAsync or PutOptimizationAsyncB methods.
XML strings returned from the BlackBox can be extremely large if the order itself is complex, and it can be useful to have the document compressed before transmission. Zip compresses XML extremely efficiently, to the order of 95% or better.
The XML document is returned in a Zipped and then Base-64 encoded format to minimize bandwidth and transmission time. So you will need to first decode, then unzip the returned string before it can be parsed.
This method should be only used when an optimization is known to be complete (see GetOptimizationProgress).
This method deletes the job from the BlackBox's internal database. It cannnot be retrieved again.
Parameters
- Username
- - a valid BlackBox service username.
- Password
- - the matching password for the username.
- Job
- - a valid BlackBox job id, as returned from a prior call to either PutOptimizationAsync or PutOptimizationAsyncB.
Returns
string: Zipped and Base64 encoded XML document, which contains the optimzation results. |
|
function GetCurrentJobs(const Username: string; const Password: string; const IPAddress: string; const Port: integer): string; stdcall; |
|
Retrieve a complete list of all jobs that are currently in the indicated BlackBox database. This list may contain jobs that are:
Queued - job is waiting in the BlackBox internal queue and has not yet started to optimize. In Progress - job is being processed right now. Completed - job is ready to be collected by the client.
Parameters
- Username
- - a valid BlackBox service username.
- Password
- - the matching password for the username.
- IPAddress
- - the IP address of the BlackBox for which you wish to retrieve the job list.
- Port
- - the Port or socket of the BlackBox for which you wish to retrieve the job list.
Returns
string: XML-formatted text containing a list of all jobs in the BlackBox database. |
|
function GetCurrentJobsB(const Username: string; const Password: string): string; stdcall; |
|
Retrieve a complete list of all jobs that are currently in all BlackBox databases known to the service. This list may contain jobs that are:
Queued - job is waiting in the BlackBox internal queue and has not yet started to optimize. In Progress - job is being processed right now. Completed - job is ready to be collected by the client.
Parameters
- Username
- - string: a valid BlackBox service username.
- Password
- - string: the matching password for the username.
Returns
string: XML-formatted text containing a list of all jobs in all BlackBox databases. |
|
function IsOptimizationComplete(const Username: string; const Password: string; const Job: string): boolean; stdcall; |
|
Use this method to find out if the asynchronous Job identified by 'Job' is complete and ready for collection.
Parameters
- Username
- - string: a valid BlackBox service username.
- Password
- - string: the matching password for the username.
- Job
- - a valid BlackBox job id, as returned from a prior call to either PutOptimizationAsync or PutOptimizationAsyncB.
Returns
boolean: true - this job is complete and can be retrieved, false - this job is still being processed |
|
function PutOptimization(const Username: string; const Password: string; const IPAddress: string; const Port: integer; const Payload: string): string; stdcall; |
|
The method is a synchronous (or blocking) call to the service, requesting that a single load be optimized by a specific BlackBox on address IPAddress and port Port. This load is defined in an XML document passed in the payload paramter.
Since this call blocks, you must ensure an adequate timeout period on the client side.
Parameters
- Username
- - string: a valid BlackBox service username.
- Password
- - string: the matching password for the username.
- IPAddress
- - string: the IP address of the BlackBox for which you wish to retrieve the job list.
- Port
- - integer: the Port or socket of the BlackBox for which you wish to retrieve the job list.
- Payload
- - string: the XML document that defines the load to be optimized.
Returns
string: XML document that defines the completed optimization results. Refer to the appendix for an example document. |
|
function PutOptimizationB(const Username: string; const Password: string; const Payload: string): string; stdcall; |
|
The method is a synchronous (or blocking) call to the service, requesting that a single load be optimized by one of the available BlackBox instances. The best BlackBox is selected by the service from the pool of all known BlackBox instances that are currently responding. ("Best" in this context is derived by a load-balancing algorithm within in the service, which takes into account the most responsive BlackBox based on its current processing load, latency, CPU spec. and usage.)
The load is defined in an XML document passed in the payload paramter.
Since this call blocks, you must ensure an adequate timeout period on the client side.
Parameters
- Username
- - string: a valid BlackBox service username.
- Password
- - string: the matching password for the username.
- IPAddress
- - string: the IP address of the BlackBox for which you wish to retrieve the job list.
- Port
- - integer: the Port or socket of the BlackBox for which you wish to retrieve the job list.
- Payload
- - string: the XML document that defines the load to be optimized.
Returns
string: XML document that defines the completed optimization results. Refer to the appendix for an example document. |
|
function PutOptimizationAsync(const Username: string; const Password: string; const IPAddress: string; const Port: integer; const Payload: string): string; stdcall; |
|
This is an asynchronous call to the service. The call will return immediately with a job id, which is a reference used in subsequent calls to obtain the status and results of the optimization.
The response is a small XML document of the following form: <blackbox jobid="IPAddress:Port|12345678-12345678"/>
The caller is required to parse the jobid attribute from this XML, and use it when calling the gateway to obtain a status or the results for the load.
There are several advantages to using this method:
Calls do not block. This means your application is freed up for other processing. Calls can be queued. This means that you can send as many optimization requests as required in rapid succession. The BlackBox takes care of all scheduling, queueing etc. You can check the progress of any current optimization job using the GetOptimizationProgress method.
Parameters
- Username
- - string: a valid BlackBox service username.
- Password
- - string: the matching password for the username.
- IPAddress
- - string: the IP address of the BlackBox for which you wish to retrieve the job list.
- Port
- - integer: the Port or socket of the BlackBox for which you wish to retrieve the job list.
- Payload
- - string: the XML document that defines the load to be optimized.
|
|
function PutOptimizationAsyncB(const Username: string; const Password: string; const Payload: string): string; stdcall; |
|
This is an asynchronous call to the service. The call will return immediately with a job id, which is a reference used in subsequent calls to obtain the status and results of the optimization.
The response is a small XML document of the following form: <blackbox jobid="IPAddress:Port|12345678-12345678"/>
The caller is required to parse the jobid attribute from this XML, and use it when calling the gateway to obtain a status or the results for the load.
There are several advantages to using this method:
Calls do not block. This means your application is freed up for other processing. Calls are automatically balanced across all available BlackBox instances to maximize efficiency. Calls can be queued. This means that you can send as many optimization requests as required in rapid succession. The service will load-balance, and each BlackBox takes care of its own scheduling, queueing etc. You can check the progress of any current optimization job using the GetOptimizationProgress method.
Parameters
- Username
- - string: a valid BlackBox service username.
- Password
- - string: the matching password for the username.
- Payload
- - string: the XML document that defines the load to be optimized.
|
|
function PutInterrupt(const Username: string; const Password: string; const Job: string): string; stdcall; |
|
Use this method to cancel an existing job in the BlackBox. The BlackBox will immediately cease processing this job and delete it from its internal database.
Parameters
- Username
- - string: a valid BlackBox service username.
- Password
- - string: the matching password for the username.
- Job
- - string: the id of the job to be interrupted and deleted.
Returns
string: XML status |
|
function PutReloadStaticData(const Username: string; const Password: string; const IPAddress: string; const Port: integer): string; stdcall; |
|
This function triggers the specified BlackBox to reload its database from the static data file (XML database file) on disk. This file is the one defined as “StaticDataFile” in the BlackBox's .ini file.
This is a useful feature if you have updated your container and or product data and need the BlackBox to reflect the same changes.
The update happens on-the-fly, so the BlackBox service is not interrupted by this call. Once the static data has been reloaded, this function will return the reply from the BlackBox as a small XML string in the following form:
<blackbox reply="OK"/>
Parameters
- Username
- - a valid BlackBox service username.
- Password
- - the matching password for the username.
- IPAddress
- - the IP address of the BlackBox for which you wish to reload the data.
- Port
- - the Port or socket of the BlackBox for which you wish to reload the data.
Returns
string: XML status |
|
function PutReloadStaticDataB(const Username: string; const Password: string): string; stdcall; |
|
This function triggers all known BlackBox instances to reload their database from the static data file (XML database file) on disk. This file is the one defined as “StaticDataFile” in the BlackBox's .ini file.
This is a useful feature if you have updated your container and or product data and need the BlackBox to reflect the same changes.
The update happens on-the-fly, so the BlackBox service is not interrupted by this call. Once the static data has been reloaded across all instances, this function will return a reply as a small XML string in the following form:
<blackbox reply="OK"/>
Parameters
- Username
- - string: a valid BlackBox service username.
- Password
- - string: the matching password for the username.
- IPAddress
- - string: the IP address of the BlackBox for which you wish to reload the data.
- Port
- - integer: the Port or socket of the BlackBox for which you wish to reload the data.
Returns
string: XML status |
Copyright (c) 2014 MagicLogic Optimization Inc.
Generated by PasDoc 0.13.0 on 2014-01-12 14:34:35
|