Overview
|
The purpose of this guide is to describe how to configure the Enterprise Gateway
to send messages to external Web Services. The Enterprise Gateway offers a number
of different filters that can be used to route messages. Depending on
how the Enterprise Gateway is perceived by the client, different combinations of
routing filters can be used.
For example, the Enterprise Gateway can act both as a proxy and an endpoint (i.e.
in-line) server for a client, depending on how the client is configured.
In each case the request received by the Enterprise Gateway appears slightly
different, a fact that the Enterprise Gateway can take advantage of when routing the
message onwards. Furthermore, the Enterprise Gateway can provide
service virtualization by shielding the underlying
hierarchy of back-end Web Services from clients.
In the next section, we will explain how clients can use the Enterprise Gateway as
both a proxy and as an endpoint server. We will then go on to show how
service virtualization works. Once these basic
concepts have been explained, we will help you to identify the
combination of routing filters that is best suited to your deployment
scenario.
|
Proxy or Endpoint Server
|
The Enterprise Gateway can be used by clients as both a proxy sever and an endpoint
server. When a client uses the Enterprise Gateway as a proxy server, it sends up
the complete URL of the destination Web Service in the HTTP request line.
The Enterprise Gateway can use the URL to determine the host and port to route the
message to. The following HTTP request shows an example of a request
received by the Enterprise Gateway when acting as a proxy for a client:
| | |
|
POST http://localhost:8080/services/getHello HTTP/1.1
| |
| | |
|
Alternatively, when the Enterprise Gateway is acting as an endpoint (i.e. in-line)
server, the client sends the request directly to the Enterprise Gateway. In this
case, the request line appears as follows:
| | |
|
POST /services/getHello HTTP/1.1
| |
| | |
|
In this case, only the path on the server is specified and no scheme,
host, or port number is included in the HTTP request line. Since this
information is not provided by the client, the Enterprise Gateway must be
explicitly configured to route the message on to the specific destination.
|
Service Virtualization
|
It is sometimes desirable to shield the underlying structure of the
directory hierarchy in which Web Services reside from external clients.
This can be done by providing a mapping between the path that the client
accesses and the actual path at which the Web Service resides.
For example, suppose we have 2 Web Services accessible at the URIs,
/helloService/getHello and
/financeService/getQuote . We may want to hide the
fact that these services are actually deployed under different paths,
perhaps exposing them under a common /services base
URI, for example, /services/getHello and
/services/getQuote . The client is therefore unaware
of the underlying hierarchy (e.g. directory structure) of the 2 Web
Services. This is called service virtualization.
|
Choosing the Correct Routing Filters
|
The purpose of this section is to identify, first, how your clients
perceive the Enterprise Gateway, and second, to determine whether or not you wish to
virtualize your back-end Web Services. Depending on these requirements,
different combinations of routing filters can be used, as outlined in
the 4 "cases" described in the subsequent sections.
In order to determine the combination of routing filters that is most
appropriate for your scenario, it is necessary to consider your answers
to the following simple questions:
Proxy or Endpoint
-
Is the client using the Enterprise Gateway as a proxy? If so, then you will
be interested in cases 1 or 2 below, depending on whether
service virtualization is required or not.
-
Alternatively, is the client using the Enterprise Gateway as the endpoint of
the connection, i.e. as an in-line server? If so, then you should
look at cases 3 or 4 below.
Service Virtualization
-
Do you want to shield the actual hierarchy of protected Web
Services by exposing a virtual view of these
services? If so, then cases 2, 4, and 5 below will be of interest.
-
Is service virtualization important? If not,
then you should refer to cases 1 and 3 below.
The above permutations can be summarized in the following table:
|
Case 1: Proxy without Service Virtualization
|
In this case, the Enterprise Gateway is configured as an HTTP proxy for the client
and will maintain the original path used by the client in the HTTP
request. So for example, if the Enterprise Gateway is listening at
http://localhost:8080/ , and the Web Service is
running at http://localhost:5050/services/getQuote ,
then the request line of the client HTTP request will appear as follows:
| | |
|
POST http://localhost:5050/services/getQuote HTTP/1.1
| |
| | |
|
Since the client has been configured to use the Enterprise Gateway instance
running on localhost at port 8080 as its HTTP proxy, the client will
automatically send all messages to the proxy. However, it will include
the full URL of the ultimate destination of the message in the request
line of the HTTP request.
When the Enterprise Gateway receives the request, it extracts this URL from the
request line and uses it to determine the destination of the message.
In the above example, the Enterprise Gateway will route the message onwards to
http://localhost:5050/services/getQuote .
The following policy can be configured to route the message to the URL
specified in the request line of the client request:
Policy 1: Proxy without Service Virtualization
|
The following table explains the role of each filter in the policy. For
more information on a particular filter, click on the appropriate link
in the Help column.
Filter |
Role in Policy |
Help |
Dynamic Router |
Extracts the URL of the destination Web Service from the
request line of the incoming HTTP request. The
Dynamic Router is usually used when
the Enterprise Gateway is perceived as a proxy by the client.
|
Dynamic Router
|
Connection |
Responsible for establishing the connection to the
destination Web Service and sending the message over this
connection. This connection can be mutually authenticated
if necessary.
|
Connection
|
|
Case 2: Proxy with Service Virtualization
|
In the second case, the Enterprise Gateway is also perceived as an HTTP proxy by the
client. However, this time the Enterprise Gateway exposes a
virtualized view of the services that it protects,
i.e. service virtualization.
To achieve this, the Enterprise Gateway must provide a mapping between the path used
by the client and the actual path under which the service is deployed.
Assuming the Enterprise Gateway is running at
http://localhost:8080/services and the Web Service
is deployed at
http://localhost:5050/financialServices/quotes/getQuote ,
the following is an example of what the client may send up in the HTTP
request line:
| | |
|
POST http://localhost:5050/services/getQuote HTTP/1.1
| |
| | |
|
To achieve this, the Enterprise Gateway must provide a mapping between what the
client requests, i.e. /services/getQuote , and the
actual address of the Web Service, i.e.
/financialServices/quotes/getQuote . The
Rewrite URL filter in the following policy fulfills
this role:
Policy 2: Proxy with Service Virtualization
|
The following table explains the roles of the 3 filters within the
policy:
Filter |
Role in Policy |
Help |
Dynamic Router |
Extracts the URL of the destination Web Service from the
request line of the incoming HTTP request. The
Dynamic Router is usually used when
the Enterprise Gateway is perceived as a proxy by the client.
|
Dynamic Router
|
Rewrite URL |
Specifies the mapping between the path requested by the
client and the actual path under which the Web Service is
deployed, therefore providing service virtualization.
|
Rewrite URL
|
Connection |
Responsible for establishing the connection to the destination
Web Service and sending the message over this connection.
This connection can be mutually authenticated if necessary.
|
Connection
|
|
Case 3: Endpoint without Service Virtualization
|
In this scenario, the client sees the Enterprise Gateway as the endpoint to its
connection, and the Enterprise Gateway must be configured to route messages on to
a specific destination. So, for example, assuming that the Enterprise Gateway is
running at http://localhost:8080/services , the
request line of the client's HTTP request will be received by the Enterprise Gateway
as follows:
It is clear from the request line above that no information about the
scheme, host, or port of the destination Web Service is specified.
Therefore, this information must be configured in the Enterprise Gateway so that it
knows where to route the message on to. The
Static Router allows the user to enter connection
details for the destination Web Service.
Assuming that the Web Service is running at
http://localhost:5050/stockquote/getPrice , the host,
port, and scheme respectively are as follows: "localhost", "5050", and
"http". This information must be explicitly configured in the
Static Router. The following policy illustrates this
scenario:
Policy 3: Endpoint without Service Virtualization
|
The following table explains the role of each filter in the above policy:
Filter |
Role in Policy |
Help |
Static Router |
Allows the user to explicitly specify the host, port, and
scheme at which the Web Service is listening. This filter
must be used when the client sees the Enterprise Gateway as the endpoint
to its connection, i.e. the Enterprise Gateway is not acting as a proxy
for the client.
|
Static Router
|
Connection |
Responsible for establishing the connection to the destination
Web Service and sending the message over this connection. This
connection can be mutually authenticated if necessary.
|
Connection
|
|
Case 4: Endpoint with Service Virtualization
|
In the last case, the Enterprise Gateway is acting as the endpoint to the client
connection (i.e. it is not acting as a proxy) and is hiding the
deployment hierarchy of protected Web Services from clients. In other
words, it is performing service virtualization.
In this scenario, the client will send messages directly to the Enterprise Gateway.
So, for example, assuming that the Enterprise Gateway is running at
http://localhost:8080/services , and the Web Service
is running at
http://localhost:5050/stockquote/getPrice , the
request line of the client's HTTP request will be received by the Enterprise Gateway
as follows:
The Static Router must then be configured to route the
message on to port 8080 on localhost using the http scheme, while the
Rewrite URL filter provides the mapping between the
path requested by the client (i.e. /services and
the path under which the Web Service is deployed (i.e.
/stockquote/getPrice ). The following policy
illustrates a sample policy that will provide
service virtualization when the Enterprise Gateway is used as
an endpoint:
Policy 4: Endpoint with Service Virtualization
|
The following table explains the role of each filter in the policy:
Filter |
Role in Policy |
Help |
Static Router |
Allows the user to explicitly specify the host, port, and scheme
at which the Web Service is listening. This filter must be used
when the client sees the Enterprise Gateway as the endpoint to its
connection, i.e. the Enterprise Gateway is not acting as a proxy for the
client.
|
Static Router
|
Rewrite URL |
Provides the mapping between the path requested by the client
and the path under which the Web Service is deployed.
|
Rewrite URL
|
Connection |
Responsible for establishing the connection to the destination
Web Service and sending the message over this connection. This
connection can be mutually authenticated if necessary.
|
Connection
|
|
Case 5: Simple Redirect
|
In some cases, it is necessary for the Enterprise Gateway to simply route the
incoming message to an entirely different URL. The
Rewrite URL filter can be used for this purpose, in
addition to simple rewriting the path on which the request was received
as described in cases 2 and 4 above. Note that the full URL of the
destination Web Service should be specified in this case in the
Rewrite URL filter.
The following policy illustrates the use of the
Redirect URL filter to route messages to a fully
qualified URL:
Policy 5: Simple Redirect
|
The following table describes the role of each filter in the policy
above:
Filter |
Role in Policy |
Help |
Rewrite URL |
Used to specify the fully qualified URL of the destination
Web Service.
|
Rewrite URL
|
Dynamic Router |
In this case, the Dynamic Router is used to
parse the URL specified in the Rewrite URL
filter into its constituent parts. The HTTP scheme, port, and
host of the Web Service are extracted and set to the internal
message object for use by the Connection filter.
|
Dynamic Router
|
Connection |
Responsible for establishing the connection to the destination
Web Service and sending the message over this connection. This
connection can be mutually authenticated if necessary.
|
Connection
|
|
Case 6: Routing via an HTTP Proxy
|
The Enterprise Gateway can be configured to route through an HTTP proxy in cases
where the back-end Web Service sits behind a proxy. When the Enterprise Gateway
is configured to route through a proxy, it connects directly to the proxy
and sends a request including the full URL of the target Web Service in
the HTTP request URI. When the HTTP proxy receives this request it uses
the URL in the request line to determine where to route the message on to.
The following example shows the request line of a request made through a
proxy:
| | |
|
POST http://localhost:8080/services/getQuote HTTP/1.1
| |
| | |
|
The following filters are required to configure the Enterprise Gateway to route
through an HTTP proxy:
Filter |
Role in Policy |
Help |
Static Router |
You must explicitly specify the host, port, and scheme
of the HTTP proxy in this filter.
|
Static Router
|
Rewrite URL |
Enter the full URL of the Web Service in this filter, for
example, http://HOST:8080/myServices. Because we are routing
through a proxy, the full URL specified here will be sent in
the request line of the HTTP request.
|
Rewrite URL
|
Connection |
In this case, the Connection filter connects to the HTTP proxy,
which in turn routes the message on to the destination server
named in the request URI. The Send via Proxy
switch must be enabled on the Connection filter to facilitate
this.
|
Connection
|
It is important to note the differences between how the filters are
configured to route through a proxy and the situation described in
case 4
above where no proxy is involved.
-
Static Router Filter:
When the Enterprise Gateway is to route via an HTTP proxy, the
Static Router is configured with the details of the HTTP proxy.
Otherwise, the Static Router is given the details of the Web Service
endpoint directly.
-
Rewrite URL Filter:
The full URL of the Web Service endpoint must be specified in this
filter when the Enterprise Gateway routes through a proxy. The full URL
is then included in the request line of the HTTP request to the
proxy. In cases where no proxy is involved, the Rewrite URL is
only necessary when the back-end Web Services are virtualized. In
this case, the Enterprise Gateway must send the request to a different URI
than that requested by the client.
-
Connection Filter:
When routing through a proxy, the Send via Proxy
switch must be enabled on the Connection filter. This is not
necessary when no proxy sits between the Enterprise Gateway and the
back-end Web Service.
|
Summary
|
The following points illustrate the key concepts to consider when
configuring the Enterprise Gateway to connect to external Web Services:
-
The Connection filter must
always be used since it is responsible for establishing the
connection to the Web Service.
-
Service virtualization can be achieved using
the Rewrite URL filter.
-
If the client is configured to use the Enterprise Gateway as a proxy,
the Enterprise Gateway can use the Dynamic Router to extract
the URL from the request line of the HTTP request. It can then
route the message on to this URL.
-
If the client sees the Enterprise Gateway as the endpoint of the connection
(i.e. not as a proxy), then the Static Router
must be used to explicitly configure the host, port, and scheme of
the destination Web Service.
|
|