gerrit.onap Code Review - policy/apex-pdp.git/blob

   1 //
   2 // ============LICENSE_START=======================================================
   3 //  Copyright (C) 2016-2018 Ericsson. All rights reserved.
   4 // ================================================================================
   5 // This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
   6 // Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
   7 //
   8 // SPDX-License-Identifier: CC-BY-4.0
   9 // ============LICENSE_END=========================================================
  10 //
  11 // @author Sven van der Meer (sven.van.der.meer@ericsson.com)
  12 //
  13
  14 == REST Server IO
  15
  16 APEX supports a REST server for input and output.
  17
  18 The REST server plugin always uses a synchronous mode.
  19 A client does a HTTP GET on the APEX REST server with the input event and receives the generated output event in the server reply.
  20 This means that for the REST server there has to always to be an input with an associated output.
  21 Input or output only are not permitted.
  22
  23 The plugin will start a Grizzly server as REST server for a normal APEX engine.
  24 If the APEX engine is executed as a servlet, for instance inside Tomcat, then Tomcat will be used as REST server (this case requires configuration on Tomcat as well).
  25
  26 Some configuration restrictions apply for all scenarios:
  27
  28 - Minimum port: 1024
  29 - Maximum port: 65535
  30 - The media type is `application/json`, so this plugin does only work with the JSON Event protocol.
  31
  32 The URL the client calls is created using
  33
  34 - the configured host and port, e.g. `http://localhost:12345`
  35 - the standard path, e.g. `/apex/`
  36 - the name of the input/output, e.g. `FirstConsumer/`
  37 - the input or output name, e.g. `EventIn`.
  38
  39 The examples above lead to the URL `http://localhost:12345/apex/FirstConsumer/EventIn`.
  40
  41 A client can also get status information of the REST server using `/Status`, e.g. `http://localhost:12345/apex/FirstConsumer/Status`.
  42
  43
  44 === REST Server Stand-alone
  45
  46 We need to configure a REST server input and a REST server output.
  47 Input and output are associated with each other via there name.
  48
  49 Timeouts for REST calls need to be set carefully.
  50 If they are too short, the call might timeout before a policy finished creating an event.
  51
  52 The following example configures the input named as `MyConsumer` and associates an output named `MyProducer` with it.
  53
  54 [source%nowrap,json]
  55 ----
  56 "eventInputParameters": {
  57   "MyConsumer": {
  58     "carrierTechnologyParameters" : {
  59       "carrierTechnology" : "RESTSERVER", <1>
  60       "parameterClassName" :
  61         "org.onap.policy.apex.plugins.event.carrier.restserver.RESTServerCarrierTechnologyParameters",
  62       "parameters" : {
  63         "standalone" : true, <2>
  64         "host" : "localhost", <3>
  65         "port" : 12345 <4>
  66       }
  67     },
  68     "eventProtocolParameters":{
  69       "eventProtocol" : "JSON" <5>
  70     },
  71     "synchronousMode"    : true, <6>
  72     "synchronousPeer"    : "MyProducer", <7>
  73     "synchronousTimeout" : 500 <8>
  74   }
  75 }
  76 ----
  77 <1> set REST server as carrier technology
  78 <2> set the server as stand-alone
  79 <3> set the server host
  80 <4> set the server listen port
  81 <5> use JSON event protocol
  82 <6> activate synchronous mode
  83 <7> associate an output `MyProducer`
  84 <8> set a timeout of 500 milliseconds
  85
  86
  87 The following example configures the output named as `MyProducer` and associates the input `MyConsumer` with it.
  88 Note that for the output there are no more paramters (such as host or port), since they are already configured in the associated input
  89
  90 [source%nowrap,json]
  91 ----
  92 "eventOutputParameters": {
  93   "MyProducer": {
  94     "carrierTechnologyParameters":{
  95       "carrierTechnology" : "RESTSERVER",
  96       "parameterClassName" :
  97         "org.onap.policy.apex.plugins.event.carrier.restserver.RESTServerCarrierTechnologyParameters"
  98     },
  99     "eventProtocolParameters":{
 100       "eventProtocol" : "JSON"
 101     },
 102     "synchronousMode"    : true,
 103     "synchronousPeer"    : "MyConsumer",
 104     "synchronousTimeout" : 500
 105   }
 106 }
 107 ----
 108
 109
 110 === REST Server Stand-alone, multi input
 111
 112 Any number of input/output pairs for REST servers can be configured.
 113 For instance, we can configure an input `FirstConsumer` with output `FirstProducer` and an input `SecondConsumer` with output `SecondProducer`.
 114 Important is that there is always one pair of input/output.
 115
 116
 117 === REST Server Stand-alone in Servlet
 118
 119 If APEX is executed as a servlet, e.g. inside Tomcat, the configuration becomes easier since the plugin can now use Tomcat as the REST server.
 120 In this scenario, there are not parameters (port, host, etc.) and the key `standalone` must not be used (or set to false).
 121
 122 For the Tomcat configuration, we need to add the REST server plugin, e.g.
 123
 124 [source%nowrap,xml]
 125 ----
 126 <servlet>
 127   ...
 128   <init-param>
 129     ...
 130     <param-value>org.onap.policy.apex.plugins.event.carrier.restserver</param-value>
 131   </init-param>
 132   ...
 133 </servlet>
 134 ----