Difference between revisions of "GVAdapterHttpConfiguration"

From GreenVulcano Wiki
Jump to: navigation, search
 
(4 intermediate revisions by the same user not shown)
Line 34: Line 34:
  
 
This element can contain more sub-elements:
 
This element can contain more sub-elements:
−
* [[#ActionMapping|ActionMapping]] '''(REMOVED in v3.4)'''
+
* [[#ActionMapping|ActionMapping]] '''(REMOVED in v3.3.4 and v3.4)'''
−
<div class="version_ge3.4">
+
<div class="version_ge3.4/3.3.4">
 
* [[#GVCoreActionMapping|GVCoreActionMapping]]
 
* [[#GVCoreActionMapping|GVCoreActionMapping]]
 
* [[#ForwardActionMapping|ForwardActionMapping]]
 
* [[#ForwardActionMapping|ForwardActionMapping]]
 +
</div>
 +
<div class="version_ge3.4.0.3/3.3.4.1">
 +
* [[#RESTActionMapping|RESTActionMapping]]
 
</div>
 
</div>
  
Line 102: Line 105:
 
|}
 
|}
  
−
Sets the following properties in input to GV workflow:
+
Sets the following properties in input to {{GVESB}} workflow:
 
{|class="gvtable"
 
{|class="gvtable"
 
! Property !! Description
 
! Property !! Description
Line 112: Line 115:
 
| HTTP_REMOTE_ADDR || Client remote address
 
| HTTP_REMOTE_ADDR || Client remote address
 
|}
 
|}
 +
<div class="version_ge3.4.0.2/3.3.4.1">
 +
{|class="gvtable"
 +
! Property !! Description
 +
|-
 +
| HTTP_PATH || Request URI path component
 +
|}
 +
</div>
 +
<div class="version_ge3.4.0.4/3.3.4.2">
 +
{|class="gvtable"
 +
! Property !! Description
 +
|-
 +
| HTTP_QUERY || Request URI query component
 +
|}
 +
</div>
  
 
Each '''GVCoreActionMapping''' can contain the following sub-elements:
 
Each '''GVCoreActionMapping''' can contain the following sub-elements:
Line 117: Line 134:
 
* [[#RetCodeConversionIn|RetCodeConversionIn]]
 
* [[#RetCodeConversionIn|RetCodeConversionIn]]
 
* [[#RetCodeConversionOut|RetCodeConversionOut]]
 
* [[#RetCodeConversionOut|RetCodeConversionOut]]
−
 
  
 
====ForwardActionMapping====
 
====ForwardActionMapping====
Line 142: Line 158:
 
* [[Http-call#endpoint|endpoint]]
 
* [[Http-call#endpoint|endpoint]]
  
 +
 +
====RESTActionMapping====
 +
 +
An '''RESTActionMapping''' defines a mapping between a request Action and a configured URI/Method Mapping in order to invoke a {{GVESB}} service.
 +
 +
The following table shows the '''RESTActionMapping''' attributes:
 +
{|class="gvtable"
 +
! Attribute !! Type !! Description
 +
|-
 +
| type || fixed || This attribute must assume the value '''action-mapping'''.
 +
|-
 +
| class || fixed || This attribute must assume the value '''it.greenvulcano.gvesb.adapter.http.mapping.RESTHttpServletMapping'''
 +
|-
 +
| Action || required || Defines the action name, must match or be a prefix in <action> part of request URL. The attribute's value cannot be null.
 +
|-
 +
| RespContentType || optional || ContentType to be declared while handling HTTP responses to the external system. Default to application/xml and is used only if not defined by the {{GVESB}} service.
 +
The possible values are:
 +
* text/html
 +
* text/xml
 +
* text/json
 +
* text/javascript
 +
* application/xml
 +
* application/json
 +
* application/x-www-form-urlencoded
 +
|-
 +
| RespCharacterEncoding || optional || Character encoding to be used while handling HTTP responses to the external system. Default to UTF-8 and is used only if not defined by the {{GVESB}} service.
 +
The possible values are:
 +
* US-ASCII
 +
* ISO-8859-1
 +
* ISO-LATIN-1
 +
* UTF-8
 +
* UTF-16BE
 +
* UTF-16LE
 +
* UTF-16
 +
|-
 +
| enabled || required || This parameter defines if an action must be processed.
 +
|-
 +
| dump-in-out || optional || If true enable the dump of the input/output HTTP data. Default false.
 +
|}
 +
 +
Sets the following properties in input to {{GVESB}} workflow:
 +
{|class="gvtable"
 +
! Property !! Description
 +
|-
 +
| HTTP_METHOD || Requested method
 +
|-
 +
| HTTP_ACTION || Request action
 +
|-
 +
| HTTP_PATH || Request URI path component
 +
|-
 +
| HTTP_REMOTE_ADDR || Client remote address
 +
|-
 +
| HTTP_REQ_CONTENT_TYPE || Request content type
 +
|-
 +
| HTTP_REQ_ACCEPT || Request Accept header value
 +
|-
 +
| HTTP_REQ_HEADERS || Contains, if configured in Mapping, the request HTTP headers as xml document, with the following structure
 +
    <Hdr>
 +
        <h n="hdr name" v="hdr value"/>
 +
        <h n="hdr name" v="hdr value"/>
 +
    </Hdr>
 +
|-
 +
|}
 +
<div class="version_ge3.4.0.2/3.3.4.2">
 +
{|class="gvtable"
 +
! Property !! Description
 +
|-
 +
| HTTP_QUERY || Request URI query component
 +
|}
 +
</div>
 +
 +
The query string parameters (or x-www-form-urlencoded parameters in POST/PUT) are set as GVBuffer properties.
 +
For POST/PUT requests, if the request content type is application/xml or application/json or text/* the request GVBuffer object will contain a String, for other request content types the request GVBuffer object will contain a byte[].
 +
 +
Set the following properties in output GVBuffer in order to control response parameters:
 +
{|class="gvtable"
 +
! Property !! Description
 +
|-
 +
| HTTP_RESP_STATUS_CODE || Optional, define the HTTP status response code
 +
|-
 +
| HTTP_RESP_STATUS_MSG || Optional, if defined the couple HTTP_RESP_STATUS_CODE and HTTP_RESP_STATUS_MSG defines the error response code
 +
|-
 +
| HTTP_RESP_CHAR_ENCODING || Optional, defines the response character encoding
 +
|-
 +
| HTTP_RESP_CONTENT_TYPE || Optional, defines the rsponse content type:
 +
*if the response content type is application/xml or application/json or text/* the response GVBuffer object must contains a byte[], a String or a Document to be serialized
 +
*for other response content types the response GVBuffer object must contains a byte[]
 +
|-
 +
|}
 +
 +
<div class="version_ge3.4.0.8">
 +
{|class="gvtable"
 +
! Property !! Description
 +
|-
 +
|  HTTP_RESP_FILE_NAME || Optional, to define the name of the file to be downloaded through an HTTP request.
 +
|}
 +
</div>
 +
 +
Each '''RESTActionMapping''' can contain the following sub-elements:
 +
* [[Description]]
 +
* [[#Mapping|Mapping]]
 +
 +
====Mapping====
 +
This element contains the mappings from request URI/Method and GV ESB service.
 +
The following table shows the Mapping element's attributes:
 +
{|class="gvtable"
 +
! Attribute !! Type !! Description
 +
|-
 +
| method || required || Defines the HTTP Method to match.
 +
The possible values are:
 +
* GET
 +
* PUT
 +
* POST
 +
* DELETE
 +
|-
 +
| pattern || required || Defines the rules to be matched in order to identify the request URI.
 +
    The URI pattern refers to the Path component only:
 +
    http://localhost:8080/gvhttp/inbound/AddressBook/entry/123
 +
    Path -> /AddressBook/entry/123
 +
    Sample mapping: /APPLICATION=AddressBook/E_COLLECTION=entry/E_UUID=\d+
 +
    The URL is splitted on / and must start with the string 'AddressBook', then must contain the string 'entry',
 +
    then the last tocken must match the regular expression '\d+' (must be a number of at least 1 digit).
 +
    On match, the input GVBuffer will contain the following properties:
 +
        APPLICATION  = AddressBook
 +
        E_COLLECTION = entry
 +
        E_UUID      = 123
 +
|-
 +
| service || required || The {{GVESB}} service to invoke
 +
|-
 +
| operation || required || The service operation to invoke
 +
|-
 +
| system || optional || The {{GVESB}} system to impersonate
 +
|-
 +
| extract-headers || optional || Defines if the request headers must be extracted. Default to false.
 +
|}
  
 
====RetCodeConversionIn====
 
====RetCodeConversionIn====
Line 166: Line 317:
 
* 1to0
 
* 1to0
 
|}
 
|}
−
 
  
 
===InboundTransactions===
 
===InboundTransactions===

Latest revision as of 14:36, 4 November 2015

Description

The HTTP inbound adapter works identifying an Action and then defining a mapping between the Action and a Formatter.

The Action is defined by the value of the request parameter GV_ACTION (REMOVED in v3.4).

The formatter defines how to parse the request parameters and how to build the response in case of successful or failed ESB's invocation.

The client can send HTTP requests at two url: 

  • http://<host>:<port>/gvhttp/inbound/<action>
  • http://<host>:<port>/gvhttp/secure/inbound/<action>    (requires authentication)


GreenVulcano® ESB Configuration

The GVAdapterHttpConfiguration Element is used by: GVAdapters.

The following table shows the GVAdapterHttpConfiguration attributes:

Attribute Type Description
type fixed This attribute must assume the value module.
name fixed Module Id always set to HTTP_ADAPTER.

Contains the sub-elements InboundConfiguration Formatters.

InboundConfiguration

Contains the sub-elements:

ActionMappings

This element can contain more sub-elements:

ActionMapping

An ActionMapping defines a mapping between a request Action and a configured Formatter.

The following table shows the ActionMapping attributes:

Attribute Type Description
Action required Defines the action name, referenced by the request parameter GV_ACTION. The attribute's value cannot be null.
FormatterID required References a Formatter to be used to marshall/unmarshall the data. The attribute's value cannot be null.
RespContentType optional ContentType to be declared while handling HTTP responses to the external system. Default to text/html and is used only if not defined by the formatter.

The possible values are:

  • text/html
  • text/xml
  • text/json
  • text/javascript
  • application/xml
  • application/json
  • application/x-www-form-urlencoded
enabled required This parameter defines if an action must be processed.

Each ActionMapping can contain the following sub-elements:


GVCoreActionMapping

An GVCoreActionMapping defines a mapping between a request Action and a configured Formatter in order to invoke a GreenVulcano® ESB service.

The following table shows the GVCoreActionMapping attributes:

Attribute Type Description
type fixed This attribute must assume the value action-mapping.
class fixed This attribute must assume the value it.greenvulcano.gvesb.adapter.http.mapping.GVCoreHttpServletMapping
Action required Defines the action name, must match or be a prefix in <action> part of request URL. The attribute's value cannot be null.
FormatterID required References a Formatter to be used to marshall/unmarshall the data. The attribute's value cannot be null.
RespContentType optional ContentType to be declared while handling HTTP responses to the external system. Default to text/html and is used only if not defined by the formatter.

The possible values are:

  • text/html
  • text/xml
  • text/json
  • text/javascript
  • application/xml
  • application/json
  • application/x-www-form-urlencoded
enabled required This parameter defines if an action must be processed.
dump-in-out optional If true enable the dump of the input/output HTTP data. Default false.

Sets the following properties in input to GreenVulcano® ESB workflow:

Property Description
HTTP_METHOD Requested method
HTTP_ACTION Request action
HTTP_REMOTE_ADDR Client remote address
Property Description
HTTP_PATH Request URI path component
Property Description
HTTP_QUERY Request URI query component

Each GVCoreActionMapping can contain the following sub-elements:

ForwardActionMapping

An ForwardActionMapping defines a mapping to a request Action in order to forward the request to a remote HTTP server.

The following table shows the ForwardActionMapping attributes:

Attribute Type Description
type fixed This attribute must assume the value action-mapping.
class fixed This attribute must assume the value it.greenvulcano.gvesb.adapter.http.mapping.ForwardHttpServletMapping
Action required Defines the action name, must match or be a prefix in <action> part of request URL. The attribute's value cannot be null.
enabled required This parameter defines if an action must be processed.
dump-in-out optional If true enable the dump of the input/output HTTP data. Default false.

Each ForwardActionMapping can contain the following sub-elements:


RESTActionMapping

An RESTActionMapping defines a mapping between a request Action and a configured URI/Method Mapping in order to invoke a GreenVulcano® ESB service.

The following table shows the RESTActionMapping attributes:

Attribute Type Description
type fixed This attribute must assume the value action-mapping.
class fixed This attribute must assume the value it.greenvulcano.gvesb.adapter.http.mapping.RESTHttpServletMapping
Action required Defines the action name, must match or be a prefix in <action> part of request URL. The attribute's value cannot be null.
RespContentType optional ContentType to be declared while handling HTTP responses to the external system. Default to application/xml and is used only if not defined by the GreenVulcano® ESB service.

The possible values are:

  • text/html
  • text/xml
  • text/json
  • text/javascript
  • application/xml
  • application/json
  • application/x-www-form-urlencoded
RespCharacterEncoding optional Character encoding to be used while handling HTTP responses to the external system. Default to UTF-8 and is used only if not defined by the GreenVulcano® ESB service.

The possible values are:

  • US-ASCII
  • ISO-8859-1
  • ISO-LATIN-1
  • UTF-8
  • UTF-16BE
  • UTF-16LE
  • UTF-16
enabled required This parameter defines if an action must be processed.
dump-in-out optional If true enable the dump of the input/output HTTP data. Default false.

Sets the following properties in input to GreenVulcano® ESB workflow:

Property Description
HTTP_METHOD Requested method
HTTP_ACTION Request action
HTTP_PATH Request URI path component
HTTP_REMOTE_ADDR Client remote address
HTTP_REQ_CONTENT_TYPE Request content type
HTTP_REQ_ACCEPT Request Accept header value
HTTP_REQ_HEADERS Contains, if configured in Mapping, the request HTTP headers as xml document, with the following structure 
   <Hdr>
       <h n="hdr name" v="hdr value"/>
       <h n="hdr name" v="hdr value"/>
   </Hdr>
Property Description
HTTP_QUERY Request URI query component

The query string parameters (or x-www-form-urlencoded parameters in POST/PUT) are set as GVBuffer properties. For POST/PUT requests, if the request content type is application/xml or application/json or text/* the request GVBuffer object will contain a String, for other request content types the request GVBuffer object will contain a byte[].

Set the following properties in output GVBuffer in order to control response parameters:

Property Description
HTTP_RESP_STATUS_CODE Optional, define the HTTP status response code
HTTP_RESP_STATUS_MSG Optional, if defined the couple HTTP_RESP_STATUS_CODE and HTTP_RESP_STATUS_MSG defines the error response code
HTTP_RESP_CHAR_ENCODING Optional, defines the response character encoding
HTTP_RESP_CONTENT_TYPE Optional, defines the rsponse content type:
  • if the response content type is application/xml or application/json or text/* the response GVBuffer object must contains a byte[], a String or a Document to be serialized
  • for other response content types the response GVBuffer object must contains a byte[]
Property Description
HTTP_RESP_FILE_NAME Optional, to define the name of the file to be downloaded through an HTTP request.

Each RESTActionMapping can contain the following sub-elements:

Mapping

This element contains the mappings from request URI/Method and GV ESB service. The following table shows the Mapping element's attributes:

Attribute Type Description
method required Defines the HTTP Method to match.

The possible values are:

  • GET
  • PUT
  • POST
  • DELETE
pattern required Defines the rules to be matched in order to identify the request URI. 
   The URI pattern refers to the Path component only:
   http://localhost:8080/gvhttp/inbound/AddressBook/entry/123
   Path -> /AddressBook/entry/123
   Sample mapping: /APPLICATION=AddressBook/E_COLLECTION=entry/E_UUID=\d+
   The URL is splitted on / and must start with the string 'AddressBook', then must contain the string 'entry',
   then the last tocken must match the regular expression '\d+' (must be a number of at least 1 digit).
   On match, the input GVBuffer will contain the following properties:
       APPLICATION  = AddressBook
       E_COLLECTION = entry
       E_UUID       = 123
service required The GreenVulcano® ESB service to invoke
operation required The service operation to invoke
system optional The GreenVulcano® ESB system to impersonate
extract-headers optional Defines if the request headers must be extracted. Default to false.

RetCodeConversionIn

The following table shows the RetCodeConversionIn element's attributes:

Attribute Type Description
RetCodeConversion optional The attribute's admitted values are:
  • ignore
  • 0to1
  • 1to0

RetCodeConversionOut

The following table shows the RetCodeConversionOut element's attributes:

Attribute Type Description
RetCodeConversion optional The attribute's admitted values are:
  • ignore
  • 0to1
  • 1to0

InboundTransactions

This element contains the transaction definitions for the managed services.

Can contain the sub-element Transaction.

Transaction

This element contains the transaction definitions for a given service.

All service managed by the GVAdapterHttpConfiguration should have a Transaction element that defines the transaction requirements.

The following table shows the Transactionattributes:

Attribute Type Description
service required The service name. The attribute's value can't be null.
system optional Default is ALL.
transacted required This parameter defines if a service must be executed in transaction.

The attribute's admitted values are:

  • true
  • false
timeout optional This parameter defines the transaction timeout in seconds. Default is 30s.
close-on-response optional This parameter defines when transaction must be committed: before or after sending the response to the client. The default is before.

The attribute's admitted values are:

  • after
  • before

Can contain the sub-element Description.

Formatters

The Formatters are responsible for decoding the client request's parameters in order to create the input for a GreenVulcano® ESB service and to convert the service's output into a HTTP response.

Can contain the sub-elements:

Retrieved from "https://gvwiki.greenvulcano.com/gvwiki/index.php?title=GVAdapterHttpConfiguration&oldid=4454"