Overview
|
This topic describes 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 as an endpoint
(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,
and the Enterprise Gateway can take advantage of this 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.
This topic explains how clients can use the Enterprise Gateway both as a proxy and as
an endpoint server. It then shows how service virtualization
works. When these basic concepts are explained, this topic helps 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 (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. Because 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.
You can do this by providing a mapping between the path that the client
accesses and the actual path at which the Web Service resides.
For example, suppose you have two Web Services accessible at the
/helloService/getHello and
/financeService/getQuote URIs. You may wish to
hide that these services are 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 (for example, directory structure)
of the two Web Services. This is termed service
virtualization.
|
Choosing the Correct Routing Filters
|
This section first identifies how your clients perceive the Enterprise Gateway,
and then determines whether you wish to virtualize your back-end Web Services.
Depending on these requirements, you can use different combinations of routing
filters, as described in the use cases in the subsequent sections.
Consider the following to determine which combination of routing filters is most
appropriate for your scenario:
Proxy or Endpoint?
-
If the client is using the Enterprise Gateway as a proxy server, see cases 1 or 2 below,
depending on whether service virtualization is required.
-
Alternatively, if the client using the Enterprise Gateway as the endpoint of
the connection (as an in-line server), see cases 3 or 4 below.
Service Virtualization?
-
If you want to shield the hierarchy of protected Web Services by exposing a
virtual view of these services, see cases 2, 4, and 5 below.
-
If service virtualization is not important, see cases 1
and 3 below.
These permutations are 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
maintains the original path used by the client in the HTTP request. For example,
if the Enterprise Gateway is listening at http://localhost:8080/ ,
and the Web Service is running at http://localhost:5050/services/getQuote ,
the request line of the client HTTP request appears as follows:
| | |
|
POST http://localhost:5050/services/getQuote HTTP/1.1
| |
| | |
|
Because the client is configured to use the Enterprise Gateway instance running on
localhost at port 8080 as its HTTP proxy, the client
automatically sends all messages to the proxy. However, it includes 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 routes the message on to
http://localhost:5050/services/getQuote .
You can configure the following policy 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 specific filter, click the appropriate link in the
Details column.
Filter |
Role in Policy |
Details |
Dynamic Router |
Extracts the URL of the destination Web Service from the
request line of the incoming HTTP request. The
Dynamic Router is normally used when
the Enterprise Gateway is perceived as a proxy by the client.
|
Dynamic Router
|
Connection |
Establishes the connection to the destination Web Service,
and sends the message over this connection. This connection
can be mutually authenticated if necessary.
|
Connection
|
|
Case 2: Proxy with Service Virtualization
|
In this case, the Enterprise Gateway is also perceived as an HTTP proxy by the
client. However, the Enterprise Gateway exposes a virtualized
view of the services that it protects. This is termed service
virtualization.
To achieve this, the Enterprise Gateway must provide a mapping between the path used
by the client and the 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 example shows 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 (/services/getQuote ), and the address
of the Web Service (/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 each filter in the policy:
Filter |
Role in Policy |
Details |
Dynamic Router |
Extracts the URL of the destination Web Service from the
request line of the incoming HTTP request. The
Dynamic Router is normally 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 path under which the Web Service is
deployed, therefore providing service virtualization.
|
Rewrite URL
|
Connection |
Establishes the connection to the destination Web Service,
and sends 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. For example, assuming that the Enterprise Gateway is running
at http://localhost:8080/services , the request line of
the client's HTTP request is received by the Enterprise Gateway as follows:
The request line above shows 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 enables 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: localhost , 5050 ,
and http . You must explicitly configure this information 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 |
Details |
Static Router |
Enables 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 (the Enterprise Gateway is not acting as a proxy
for the client).
|
Static Router
|
Connection |
Establishes the connection to the destination Web Service,
and sends the message over this connection. This connection
can be mutually authenticated if necessary.
|
Connection
|
|
Case 4: Endpoint with Service Virtualization
|
In this case, the Enterprise Gateway acts as the endpoint to the client connection
(and not as a proxy), and hides the deployment hierarchy of protected Web
Services from clients. In other words, it performs service
virtualization.
In this scenario, the client sends messages directly to the Enterprise Gateway.
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 HTTP request is received by the Enterprise Gateway
as follows:
You can then configure the Static Router filter 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 (/services ) and the path under
which the Web Service is deployed (/stockquote/getPrice ). The
following policy illustrates a sample policy that provides 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 |
Details |
Static Router |
Enables you to explicitly specify the host, port, and scheme
at which the Web Service is listening. This filter can be used
when the client sees the Enterprise Gateway as the endpoint to its
connection (not 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 |
Establishes the connection to the destination Web Service,
and sends the message over this connection. This connection
can be mutually authenticated if necessary.
|
Connection
|
Important Note:
Alternatively, instead of using the Static Router, Rewrite
URL, and Connection filters, you can use the Connect
to URL filter, which is equivalent to using these three filters combined.
You can configure the Connect to URL filter to send messages to a
Web Service simply by specifying the destination URL. For more details, see the
Connect to URL topic.
|
Case 5: Simple Redirect
|
In some cases, the Enterprise Gateway must route the incoming message to an
entirely different URL. You can use the Rewrite URL
filter for this purpose, in addition to rewriting the path on which
the request is 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:
Filter |
Role in Policy |
Details |
Rewrite URL |
Used to specify the fully qualified URL of the destination
Web Service.
|
Rewrite URL
|
Dynamic Router |
In this case, the Dynamic Router filter 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 |
Establishes the connection to the destination Web Service,
and sends the message over this connection. This connection
can be mutually authenticated if necessary.
|
Connection
|
|
Case 6: Routing on to an HTTP Proxy
|
This is a more advanced case where the Enterprise Gateway is configured to route
on through an HTTP proxy to the back-end Web Service, which sits behind the 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 |
Details |
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 you are routing
through a proxy, the full URL specified here is 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 option must
be enabled in the Connection filter to facilitate this.
|
Connection
|
Important Note:
It is important to note the differences between how the filters are
configured to route on through a proxy and the scenario described in
Case 4:
Endpoint with Service Virtualization where no proxy is involved:
-
Static Router:
When the Enterprise Gateway routes on to an HTTP proxy, the Static
Router filter is configured with the details of the HTTP proxy.
Otherwise, the Static Router filter is given the details
of the Web Service endpoint directly.
-
Rewrite URL:
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 filter 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:
When routing through a proxy, the Send via Proxy
option must be enabled in the Connection filter.
This is not necessary when no proxy sits between the Enterprise Gateway
and the back-end Web Service.
|
Summary
|
The following are the key concepts to consider when configuring the
Enterprise Gateway to connect to external Web Services:
-
The Connection or Connect to URL
filter must always be used because it establishes
the connection to the Web Service.
-
Service virtualization can be achieved using
the Rewrite URL or Connect to URL
filter.
-
If the client is configured to use the Enterprise Gateway as a proxy, the
Enterprise Gateway can use the Dynamic Router filter 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
(not as a proxy), the Static Router filter can be
used to explicitly configure the host, port, and scheme of the
destination Web Service. Alternatively, you can use the Connect
to URL to specify a URL.
Routing Wizard
Finally, the Enterprise Gateway provides a Routing Wizard to enable you
to quickly configure and auto-generate the filters necessary to route messages on to
a specific destination. For more details, see the
Routing Wizard topic.
|
|