GVAdapterHttpConfiguration

From GreenVulcano Wiki
(Redirected from GVHTTPAdapter)
Jump to: navigation, search

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: