Listeners
Listeners receive messages from external systems. A separate listener implementation is needed
for each supported protocol (eg: REST, SOAP, Kafka, JMS, etc). The key design concepts of the MDW listener
pattern are spelled out here.
-
Listeners are protocol-specific, and implement the bare minimum functionality to accept messages off
the wire. Real processing is delegated to protocol-independent Request Handlers.
This allows handlers to be used across protocols, and to focus on business requirements instead of protocol details.
-
The responsibilities of a Listener include creating a string value representing the request content, and to
populate a
Map<<String,String>> containing protocol headers, or metaInfo.
Listeners can call ListenerHelper.processRequest()
to invoke the appropriate handler. A listener must also populate response content and response headers based on
string values provided by the handler.
-
MDW provides listeners for many common protocols (listed below). Usually an MDW application should implement
one or more Request Handlers instead of a listener. The use case for implementing
a custom listener is when a required protocol is missing from the built-in list.
Camel Routes
An alternative approach to MDW's Listener/Handler pattern is to process external requests through
Apache Camel. This approach can be especially useful when no built-in
protocol Listener is available, or when Camel's advanced message filtering capabilities are needed.
See the MDW Camel Routes documentation for details.
Built-In Listeners
RESTful Service Listener
MDW's REST listener handles three types of HTTP requests:
-
Requests whose paths start with
<context-root>/REST are mapped to handlers by path or
by content as described in the Request Handlers documentation.
-
Applications can expose a REST endpoint through the JAX-RS
@Path annotation as described
in the MDW Cookbook's section on
exposting a REST endpoint.
-
Workflow processes can be registered to directly handle REST endpoint paths. See the relevant section
of the process documentation for details.
Document (SOAP) Web Service Listener
MDW includes a number of prebuilt, extensible options for hosting SOAP Web services.
See the SOAP Web Service documentation for details.
To expose document-literal style services using a custom WSDL definition, MDW provides a mechanism whereby the WSDL document is created as an asset.
An HTTP GET request against a custom WSDL asset called Employee looks like:
http://localhost:8080/mdw/services/SOAP/Employee.wsdl
A similar URL can be used as the endpoint for an HTTP POST request which will invoke the service.
In this case the request is unwrapped from the SOAP envelope, and based on the top-level element the usual message pattern matching procedure is followed.
Likewise, the response content is presumed to be XML and is inserted into a SOAP envelope.
The endpoint location in the WSDL asset can be parameterized as follows based on environment-specific property settings:
<soap:address location="${mdw.services.url}/SOAP/Employee.wsdl" />
RPC SOAP Listener
MDW has a standard WSDL/endpoint
for handling SOAP RPC requests at <context-root>/SOAP/MDWWebService.
Kafka Listener
The Kafka listener is provided in an optional asset package:
https://github.com/CenturyLinkCloud/mdw/blob/master/mdw-workflow/assets/com/centurylink/mdw/kafka/readme.md
JMS Listener
External JMS messages are handled through the com.centurylink.mdw.external.event.queue.