diff options
| -rw-r--r-- | docs/apex/APEX-User-Manual.rst | 466 |
1 files changed, 132 insertions, 334 deletions
diff --git a/docs/apex/APEX-User-Manual.rst b/docs/apex/APEX-User-Manual.rst index 106e1e81..b10dcf8a 100644 --- a/docs/apex/APEX-User-Manual.rst +++ b/docs/apex/APEX-User-Manual.rst @@ -1173,11 +1173,11 @@ Verify a Full Installation - REST Client .. container:: content - |REST Editor Start Screen| + |Policy Editor Start Screen| .. container:: title - Figure 1. REST Editor Start Screen + Figure 1. Policy Editor Start Screen .. container:: paragraph @@ -1192,17 +1192,17 @@ Verify a Full Installation - REST Client .. container:: content - |REST Editor with loaded SampleDomain Policy Model| + |Policy Editor with loaded SampleDomain Policy Model| .. container:: title - Figure 2. REST Editor with loaded SampleDomain Policy Model + Figure 2. Policy Editor with loaded SampleDomain Policy Model .. container:: paragraph - Now you can use the REST editor. To finish this verification, simply + Now you can use the Policy editor. To finish this verification, simply terminate your browser (or the tab), and then use ``CTRL+C`` in the - console where you started the REST editor. + console where you started the Policy editor. Installing the WAR Application ------------------------------ @@ -2873,7 +2873,12 @@ REST Client Input "org.onap.policy.apex.plugins.event.carrier.restclient.RESTClientCarrierTechnologyParameters", "parameters" : { "url" : "http://example.org:8080/triggers/events", (2) - "httpCodeFilter" : "[2][0-9][0-9]" (3) + "httpMethod": "GET", (3) + "httpCodeFilter" : "[2][0-9][0-9]", (4) + "httpHeaders" : [ (5) + ["Keep-Alive", "300"], + ["Cache-Control", "no-cache"] + ] } } @@ -2884,7 +2889,14 @@ REST Client Input +-------+--------------------------------------------------+ | **2** | the URL of the HTTP server for events | +-------+--------------------------------------------------+ - | **3** | use HTTP CODE FILTER for filtering status code | + | **3** | the HTTP method to use (GET/PUT/POST/DELETE), | + | | optional, defaults to GET | + +-------+--------------------------------------------------+ + | **4** | use HTTP CODE FILTER for filtering status code, | + | | optional, defaults to [2][0-9][0-9] | + +-------+--------------------------------------------------+ + | **5** | HTTP headers to use on the REST request, | + | | optional | +-------+--------------------------------------------------+ REST Client Output @@ -2920,8 +2932,11 @@ REST Client Output "parameters" : { "url" : "http://example.com:8888/actions/events", (2) "url" : "http://example.{site}.com:8888/{trig}/events", (2') - "httpMethod" : "PUT" (3) - } + "httpMethod" : "PUT". (3) + "httpHeaders" : [ (4) + ["Keep-Alive", "300"], + ["Cache-Control", "no-cache"] + ] } } .. container:: colist arabic @@ -2933,7 +2948,11 @@ REST Client Output +-------+--------------------------------------------------+ | **2'**| the tagged URL of the HTTP server for events | +-------+--------------------------------------------------+ - | **3** | use HTTP PUT (remove this line to use HTTP POST) | + | **3** | the HTTP method to use (GET/PUT/POST/DELETE), | + | | optional, defaults to POST | + +-------+--------------------------------------------------+ + | **4** | HTTP headers to use on the REST request, | + | | optional | +-------+--------------------------------------------------+ REST Server IO @@ -3148,14 +3167,81 @@ REST Requestor IO APEX can act as REST requestor on the input as well as on the output interface. The media type is ``application/json``, so this plugin only works with - the JSON Event protocol. + the JSON Event protocol. This plugin allows APEX to send REST requests + and to receive the reply of that request without tying up APEX resources + while the request is being processed. The REST Requestor pairs a REST + requestor producer and consumer together to handle the REST request + and response. The REST request is created from an APEX output event + and the REST response is input into APEX as a new input event. -REST Requestor Input -==================== +REST Requestor Output (REST Request Producer) +============================================= + + .. container:: paragraph + + APEX sends a REST request when events are output by APEX, the REST + request configuration is specified on the REST Request Consumer (see + below). + + .. container:: listingblock + + .. container:: content + + .. code:: + + "carrierTechnologyParameters": { + "carrierTechnology": "RESTREQUESTOR", (1) + "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters" + }, + + .. container:: colist arabic + + +-------+------------------------------------------+ + | **1** | set REST requestor as carrier technology | + +-------+------------------------------------------+ + + .. container:: paragraph + + The settings below are required on the producer to + define the event that triggers the REST request and + to specify the peered consumer configuration for the + REST request, for example: + + .. container:: listingblock + + .. container:: content + + .. code:: + + "eventNameFilter": "GuardRequestEvent", (1) + "requestorMode": true, (2) + "requestorPeer": "GuardRequestorConsumer", (3) + "requestorTimeout": 500 (4) + + .. container:: colist arabic + + +-------+-------------------------------------------+ + | **1** | a filter on the event | + +-------+-------------------------------------------+ + | **2** | requestor mode must be set to *true* | + +-------+-------------------------------------------+ + | **3** | the peered consumer for REST requests, | + | | that consumer specifies the full | + | | configuration for REST requests | + +-------+-------------------------------------------+ + | **4** | the request timeout in milliseconds, | + | | overridden by timeout on consumer if that | + | | is set, optional defaults to 500 | + | | millisconds | + +-------+-------------------------------------------+ + +REST Requestor Input (REST Request Consumer) +============================================ .. container:: paragraph - APEX will connect to a given URL to request an input. + APEX will connect to a given URL to issue a REST request and + wait for a REST response. The URL can be configured statically or tagged as ``?example.{site}.org:8080/{trig}/events``, all tags such as ``site`` and ``trig`` in the URL @@ -3186,9 +3272,14 @@ REST Requestor Input "url": "http://localhost:54321/some/path/to/rest/resource", (2) "url": "http://localhost:54321/{site}/path/to/rest/{resValue}", (2') "httpMethod": "POST", (3) - "restRequestTimeout": 2000, (4) - "httpCodeFilter" : "[2][0-9][0-9]" (5) - } + "requestorMode": true, (4) + "requestorPeer": "GuardRequestorProducer", (5) + "restRequestTimeout": 2000, (6) + "httpCodeFilter" : "[2][0-9][0-9]" (7) + "httpHeaders" : [ (8) + ["Keep-Alive", "300"], + ["Cache-Control", "no-cache"] + ] } }, .. container:: colist arabic @@ -3200,17 +3291,31 @@ REST Requestor Input +-------+--------------------------------------------------+ | **2'**| the tagged URL of the HTTP server for events | +-------+--------------------------------------------------+ - | **3** | use HTTP PUT (remove this line to use HTTP POST) | + | **3** | the HTTP method to use (GET/PUT/POST/DELETE), | + | | optional, defaults to GET | + +-------+--------------------------------------------------+ + | **4** | requestor mode must be set to *true* | + +-------+--------------------------------------------------+ + | **5** | the peered producer for REST requests, that | + | | producer specifies the APEX output event that | + | | triggers the REST request | +-------+--------------------------------------------------+ - | **4** | request timeout in milliseconds | + | **6** | request timeout in milliseconds, overrides any | + | | value set in the REST Requestor Producer, | + | | optional, defaults to 500 millisconds | +-------+--------------------------------------------------+ - | **5** | use HTTP CODE FILTER for filtering status code | + | **7** | use HTTP CODE FILTER for filtering status code | + | | optional, defaults to [2][0-9][0-9] | + +-------+--------------------------------------------------+ + | **8** | HTTP headers to use on the REST request, | + | | optional | +-------+--------------------------------------------------+ .. container:: paragraph - Further settings are required on the consumer to - define the event that is requested, for example: + Further settings may be required on the consumer to + define the input event that is produced and forwarded into + APEX, for example: .. container:: listingblock @@ -3219,10 +3324,7 @@ REST Requestor Input .. code:: "eventName": "GuardResponseEvent", (1) - "eventNameFilter": "GuardResponseEvent", (2) - "requestorMode": true, (3) - "requestorPeer": "GuardRequestorProducer", (4) - "requestorTimeout": 500 (5) + "eventNameFilter": "GuardResponseEvent" (2) .. container:: colist arabic @@ -3231,65 +3333,6 @@ REST Requestor Input +-------+---------------------------+ | **2** | a filter on the event | +-------+---------------------------+ - | **3** | the mode of the requestor | - +-------+---------------------------+ - | **4** | a peer for the requestor | - +-------+---------------------------+ - | **5** | a general request timeout | - +-------+---------------------------+ - -REST Requestor Output -===================== - - .. container:: paragraph - - APEX will connect to a given URL to send events, but - not receive any events. - - .. container:: listingblock - - .. container:: content - - .. code:: - - "carrierTechnologyParameters": { - "carrierTechnology": "RESTREQUESTOR", (1) - "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters" - }, - - .. container:: colist arabic - - +-------+------------------------------------------+ - | **1** | set REST requestor as carrier technology | - +-------+------------------------------------------+ - - .. container:: paragraph - - Further settings are required on the consumer to - define the event that is requested, for example: - - .. container:: listingblock - - .. container:: content - - .. code:: - - "eventNameFilter": "GuardRequestEvent", (1) - "requestorMode": true, (2) - "requestorPeer": "GuardRequestorConsumer", (3) - "requestorTimeout": 500 (4) - - .. container:: colist arabic - - +-------+---------------------------+ - | **1** | a filter on the event | - +-------+---------------------------+ - | **2** | the mode of the requestor | - +-------+---------------------------+ - | **3** | a peer for the requestor | - +-------+---------------------------+ - | **4** | a general request timeout | - +-------+---------------------------+ gRPC IO ####### @@ -4194,250 +4237,13 @@ The APEX CLI Tosca Editor %APEX_HOME%/\bin/\apexCLIToscaEditor.bat -c %APEX_HOME%\examples\PolicyModel.apex -ot %APEX_HOME%\examples\test.json -l %APEX_HOME%\examples\test.log -ac %APEX_HOME%\examples\RESTServerStandaloneJsonEvent.json -t %APEX_HOME%\examples\ToscaTemplate.json -The APEX REST Editor --------------------- - - .. container:: paragraph - - The standard way to use the APEX REST Editor is via an - installation of the *war* file on a webserver. However, the - REST editor can also be started via command line. This will - start a Grizzly webserver with the *war* deployed. Access to - the REST Editor is then via the provided URL - - .. container:: paragraph - - On UNIX and Cygwin systems use: - - .. container:: ulist - - - ``apexRESTEditor.sh`` - simply starts the webserver with - the REST editor - - - ``apexApps.sh rest-editor`` - simply starts the webserver - with the REST editor - - .. container:: paragraph - - On Windows systems use: - - .. container:: ulist - - - ``apexRESTEditor.bat`` - simply starts the webserver with - the REST editor - - - ``apexApps.bat rest-editor`` - simply starts the - webserver with the REST editor - - .. container:: paragraph - - Summary of alternatives to start the APEX REST Editor: - - +-------------------------------------------------------------+---------------------------------------------------------------+ - | Unix, Cygwin | Windows | - +=============================================================+===============================================================+ - | .. container:: | .. container:: | - | | | - | .. container:: listingblock | .. container:: listingblock | - | | | - | .. container:: content | .. container:: content | - | | | - | .. code:: | .. code:: | - | | | - | # $APEX_HOME/bin/apexRESTEditor.sh.sh [args] | > %APEX_HOME%\bin\apexRESTEditor.bat [args] | - | # $APEX_HOME/bin/apexApps.sh rest-editor [args] | > %APEX_HOME%\bin\apexApps.bat rest-editor [args] | - +-------------------------------------------------------------+---------------------------------------------------------------+ - - .. container:: paragraph - - The option ``-h`` provides a help screen with all command - line arguments. - - .. container:: listingblock - - .. container:: content - - .. code:: - - usage: org.onap.policy.apex.client.editor.rest.ApexEditorMain [options...] - -h,--help outputs the usage of this command - -l,--listen <ADDRESS> the IP address to listen on. Default value is localhost to restrict access to the - local machine only. - -p,--port <PORT> port to use for the Apex RESTful editor REST calls. - -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating. Default - value is -1 to run indefinitely. - - .. container:: paragraph - - If the REST Editor is started without any arguments the - final messages will look similar to this: - - .. container:: listingblock - - .. container:: content - - .. code:: - - Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . . - Sep 05, 2018 11:24:30 PM org.glassfish.grizzly.http.server.NetworkListener start - INFO: Started listener bound to [localhost:18989] - Sep 05, 2018 11:24:30 PM org.glassfish.grizzly.http.server.HttpServer start - INFO: [HttpServer] Started. - Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ - - .. container:: paragraph - - The last line states the URL on which the REST Editor can be - accessed. The example above stated - ``http://0.0.0.0:18989/apex/``. In a web browser use the URL - ``http://localhost:18989`` and the REST Editor will start. - -The APEX Monitoring Client --------------------------- - - .. container:: paragraph - - The standard way to use the APEX Monitoring Client is via an - installation of the *war* file on a webserver. However, the - Monitoring Client can also be started via command line. This - will start a Grizzly webserver with the *war* deployed. - Access to the Monitoring Client is then via the provided URL - - .. container:: paragraph - - On UNIX and Cygwin systems use: - - .. container:: ulist - - - ``apexApps.sh eng-monitoring`` - simply starts the - webserver with the Monitoring Client - - .. container:: paragraph - - On Windows systems use: - - .. container:: ulist - - - ``apexApps.bat eng-monitoring`` - simply starts the - webserver with the Monitoring Client - - .. container:: paragraph - - The option ``-h`` provides a help screen with all command - line arguments. - - .. container:: listingblock - - .. container:: content - - .. code:: - - usage: org.onap.policy.apex.client.monitoring.rest.ApexMonitoringRestMain [options...] - -h,--help outputs the usage of this command - -p,--port <PORT> port to use for the Apex Services REST calls - -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating - - .. container:: paragraph - - If the Monitoring Client is started without any arguments - the final messages will look similar to this: - - .. container:: listingblock - - .. container:: content - - .. code:: - - Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . . - Sep 05, 2018 11:26:20 PM org.glassfish.grizzly.http.server.NetworkListener start - INFO: Started listener bound to [localhost:18989] - Sep 05, 2018 11:26:20 PM org.glassfish.grizzly.http.server.HttpServer start - INFO: [HttpServer] Started. - Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ - - .. container:: paragraph - - The last line states the URL on which the Monitoring Client - can be accessed. The example above stated - ``http://localhost:18989/apexservices``. In a web browser - use the URL ``http://localhost:18989``. - -The APEX Deployment Client --------------------------- - - .. container:: paragraph - - The standard way to use the APEX Deployment Client is via an - installation of the *war* file on a webserver. However, the - Deployment Client can also be started via command line. This - will start a Grizzly webserver with the *war* deployed. - Access to the Deployment Client is then via the provided URL - - .. container:: paragraph - - On UNIX and Cygwin systems use: - - .. container:: ulist - - - ``apexApps.sh eng-deployment`` - simply starts the - webserver with the Deployment Client - - .. container:: paragraph - - On Windows systems use: - - .. container:: ulist - - - ``apexApps.bat eng-deployment`` - simply starts the - webserver with the Deployment Client - - .. container:: paragraph - - The option ``-h`` provides a help screen with all command - line arguments. - - .. container:: listingblock - - .. container:: content - - .. code:: - - usage: org.onap.policy.apex.client.deployment.rest.ApexDeploymentRestMain [options...] - -h,--help outputs the usage of this command - -p,--port <PORT> port to use for the Apex Services REST calls - -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating - - .. container:: paragraph - If the Deployment Client is started without any arguments - the final messages will look similar to this: - - .. container:: listingblock - - .. container:: content - - .. code:: - - Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . . - Sep 05, 2018 11:27:09 PM org.glassfish.grizzly.http.server.NetworkListener start - INFO: Started listener bound to [localhost:18989] - Sep 05, 2018 11:27:09 PM org.glassfish.grizzly.http.server.HttpServer start - INFO: [HttpServer] Started. - Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ - - .. container:: paragraph - - The last line states the URL on which the Deployment Client - can be accessed. The example above stated - ``http://localhost:18989/apexservices``. In a web browser - use the URL ``http://localhost:18989``. - -The APEX Full Client +The APEX Client -------------------- .. container:: paragraph - The APEX Full Client combines the REST Editor, the + The APEX Client combines the Policy Editor, the Monitoring Client, and the Deployment Client into a single application. The standard way to use the APEX Full Client is via an installation of the *war* file on a webserver. @@ -4510,7 +4316,7 @@ The APEX Application Launcher .. container:: paragraph - The standard applications (Engine, CLI Editor, REST Editor) + The standard applications (Engine and CLI Editor) come with dedicated start scripts. For all other APEX applications, we provide an application launcher. @@ -5937,13 +5743,5 @@ Send Events .. container:: :name: footer-text - 2.0.0-SNAPSHOT - Last updated 2018-09-10 15:38:16 IST - -.. |Extract the TAR archive| image:: images/install-guide/win-extract-tar-gz.png -.. |Extract the APEX distribution| image:: images/install-guide/win-extract-tar.png -.. |REST Editor Start Screen| image:: images/install-guide/rest-start.png -.. |REST Editor with loaded SampleDomain Policy Model| image:: images/install-guide/rest-loaded.png -.. |APEX Configuration Matrix| image:: images/apex-intro/ApexEngineConfig.png |