Developing and deploying a proxy gateway using WebSphere ESB V7, WebSphere Integration Developer V7, and Business Space powered by WebSphere

In WebSphere ESB V7, a proxy gateway provides an out-of-the-box, end-to-end, Web services-based service gateway that enables new services to be added without stopping and starting the gateway application. It provides a built in mechanism to identify the message and route it to the service provider endpoint. In this article, you will learn the basic characteristics of service gateways and then the details of proxy gateways, including the runtime architecture, how to develop and deploy the gateway, and how to administer the repository of services. The article then provides an example that you build with WebSphere Integration Developer V7 and deploy, configure, and run on WebSphere ESB V7. Finally, the article provides guidelines to help you understand which service gateway types are best in various situations.

Callum Jackson (callumj@uk.ibm.com), Software Engineer, IBM

Photo of Callum Jackson Callum Jackson is a Software Engineer on the WebSphere ESB team at the IBM Hursley Software Lab in the UK. He has worked on the WebSphere ESB team since 2005, and before that he worked in Software Services on SOA applications for the telecommunications industry. You can contact Callum at callumj@uk.ibm.com.



Russ Newcombe (russnewcombe@us.ibm.com), Software Engineer, IBM

PhotoRuss Newcombe is a Senior Software Engineer on the WebSphere Early Programs team at the IBM Lab in Austin Texas. He is involved in betas and other early adoption programs for WebSphere products, focusing primarily on WebSphere ESB. He provides technical support to beta customers, and develops and delivers education on new product features. Prior to this, he worked for over 25 years as a software architect and developer, most recently as designer of naming services on the WebSphere Application Server team.



14 July 2010

Introduction

This article will help you understand the proxy gateway pattern, which provides a Web service gateway that is fast to build and meets the majority of requirements with out-of-the-box capabilities. It was introduced in IBM® WebSphere® Enterprise Service Bus V7.0 (hereafter called WebSphere ESB) to extend the service gateway capabilities of WebSphere ESB. Service gateways were introduced in WebSphere ESB V6.2 with support for the dynamic service gateway and static service gateway patterns. The article contains the following sections:

What is a service gateway?
Describes the characteristics of a service gateway and introduces the supported patterns.
Architecture of a proxy gateway
Provides the details of the proxy gateway pattern, defines terms, and describes the essential parts of the pattern and how they relate and interact.
Administering the configuration store
Shows the administrative tools provided to organize and configure endpoint data used by a proxy gateway.
Tooling support for building a proxy gateway
Describes the tooling provided by WebSphere Integration Developer V7.0 to generate and configure a proxy gateway implementation.
Hands-on proxy gateway example
Shows you how to build, deploy, configure, and test a proxy gateway.
Guidelines for selecting an appropriate service gateway pattern
Generic guidelines to help you understand when it is appropriate to use each of the service gateway patterns.

What is a service gateway?

To understand the motivation behind the service gateway patterns, it is helpful to first understand the characteristics of typical service mediations. Service mediations have typed client-side interfaces and typed service provider interfaces. The mediation acts as an intermediary between a consumer of a service and the service provider. A service consumer invokes the mediation, which then performs the required processing (such as message manipulation) and forwards the request to a service provider. For each operation of the client side interfaces, there must be a separate mediation defined. The scenario is shown in Figure 1:

Figure 1. Typical service mediation
Typical service mediations require a separate mediation for each consumer/provider pair

To further illustrate this point, if A, B, and C have ten operations each, a total of thirty separate mediation implementations are required. In some situations the logic within each of these mediations may be similar, such as security, logging, or adding protocol headers before forwarding to the service provider. Therefore, it would be beneficial if the logic within the mediation could be written once and used across all service consumer/provider interactions. This is where the service gateway pattern can be helpful. It can provide a single mediation that handles the requests for multiple typed service consumers and providers, as shown in Figure 2:

Figure 2. Service gateway meditation
A service gateway handles all consumer/provider pairs with a single mediation

Processing stages of a service gateway

To illustrate the types of processing that occur in a service gateway, a general processing template is shown in Figure 3:

Figure 3. General processing template for a service gateway
Four processing stages typical of any service gateway

The four processing stages are:

Common processing
When a message is received by the gateway, common processing that occurs for all messages can be completed, such as adding protocol level headers, logging the entire message, or emitting infrastructure events.
Service identification
The message being processed by the gateway needs to be identified as a certain type. For instance, the message needs to be queried to determine if it is for service provider A, B, or C.
Endpoint routing
Once the message has been identified as destined for a particular service, it needs to be mapped to a network-addressable endpoint so that the message can be forwarded to the ultimate destination.
Service-specific processing
Finally, any required processing for the particular target service is performed.

You can rearrange the order of the above steps as needed for your scenario.

Supported service gateway patterns

Three service gateway patterns are supported by WebSphere ESB V7:

Dynamic service gateway
A flexible, customizable service gateway that allows users to route messages from any protocol to any protocol. Access to the body of the message is limited to the raw protocol encoding unless the schema information (WSDL and XSD files) are available.
Static service gateway
A flexible, customizable service gateway that allows users to route messages from any protocol to any protocol for a defined set of services. In this case it is always required for the schema information (WSDL and XSD files) to be available within the deployed module.
Proxy gateway
Provides an out of the box, end to end service gateway that allows new services to be added without stopping and starting the application. It provides a built in mechanism to identify the message and route to the service provider endpoint. The only protocols supported are JAX-WS Web services.

For a description of dynamic and static service gateways, see What's new in WebSphere ESB V6.2, Part 2: Service gateway patterns. The rest of this article focuses on the new proxy gateway support.

Architecture of a proxy gateway

The concept of a proxy gateway is based on the primary goal of a service gateway, to provide a generic capability across a multitude of service providers. Additionally, this capability should be easy to build, easy to use and be an out of the box experience without dependencies on other products.

Terminology

Before diving into the architecture, some new terminology is introduced that sets the scene for the later discussion. Figure 4 shows the relationship between a proxy gateway, proxy group, service provider and virtual service.

Figure 4. Elements of a proxy gateway
Image to introduce new terminology by showing the elements of a proxy gateway
Proxy group
A collection of service providers that are grouped together into a logical set.
Proxy gateway
The entity that provides the gateway function for one or more proxy groups.
Virtual service
The exposed endpoint of the proxy gateway for a service provider within the associated proxy group.

Configuration store

The proxy gateway needs to have access to the configuration information and the defined relationships between the proxy gateway, proxy groups and the associated service providers. However, providing an out of the box capability precludes requiring a dependency on an external registry. As a result, WebSphere ESB V7 introduces a new built-in configuration store to hold this data.

To enable IT and solution administrators to manipulate the data within the built-in configuration store, a Business Space widget is provided. The interface enables users to create, delete and amend virtual services associated with a proxy group. Figure 5 shows the high level interactions of the proxy gateway, the configuration store and the Business Space widget. You can see in the middle of the diagram that the configuration store maintians the associations between proxy groups and proxy gateways. The proxy gateways contain definitions of virtual services and their defined endpoints. At the bottom you can see the Business Space widget used to administer the proxy groups and their virtual service definitions.

Figure 5. Proxy gateway, configuration store and Business Space widget
Complete interaction between the proxy gateway, the built-in configuration store and the Business Space widget

Network addressable endpoints for virtual services

The proxy gateway provides the ability to have an individual network addressable endpoint for each virtual service it is exposing. This enables the consumer of the virtual service to have a dedicated URL for the interaction with the proxy gateway. The proxy gateway export, which is a normal service gateway export, accepts messages in a pattern of URLs instead of the normal single URL. The format is:

<NORMAL-EXPORT-URL>/<VIRTUAL-SERVICE-NAME>

For example, assume the export normally accepts inbound messages to:

http://localhost:9080/proxyGateway/sca/ProxyGatewayExport

The export also accepts an inbound message with the following endpoint pattern:

http://localhost:9080/proxyGateway/sca/ProxyGatewayExport/*

This allows a separate URL to be provided for each virtual service required for the proxy gateway, for example:

http://localhost:9080/proxyGateway/sca/ProxyGatewayExport/VirtualServiceA
http://localhost:9080/proxyGateway/sca/ProxyGatewayExport/VirtualServiceB
...

Virtual service WSDL generation

To create a typical Web service client, you would normally retrieve the WSDL file for the service provider and pass it into a Web service wizard to generate a client stub. A service gateway poses a unique problem in that the WSDL needed by the client is a combination of the WSDL for the gateway and the WSDL for the target service provider. For a service gateway in WebSphere ESB V6.2 the creation of this WSDL file was a manual process. You had to download the target service provider WSDL, replace any policy information with that attached to the service gateway export and then override the endpoint to that of the service gateway. This exposed to the service consumer that a service gateway was being used, and because it was a manual process it was open to editing mistakes.

To address this issue for the proxy gateway user, an automated WSDL resolution mechanism is supplied. You can submit requests to the following pattern:

<NORMAL-EXPORT-URL>/<VIRTUAL-SERVICE-NAME>?wsdl

For example:

http://localhost:9080/proxyGateway/sca/ProxyGatewayExport/VirtualServiceA?wsdl

Virtual service endpoint resolution

Consider the routing options available within a proxy gateway. In general, it is required to be able to determine the type of message the gateway is acting on and then resolve this to a network addressable endpoint. This can be handled automatically by the proxy gateway using the dedicated URL and the built-in configuration store information. Because the virtual service has a dedicated URL format containing the virtual service name, it can be extracted from the URL pattern and passed to the built-in configuration store to resolve it to a network addressable endpoint.

Gateway Endpoint Lookup Primitive

WebSphere ESB 6.2 provided a general framework for a service gateway, but due to the dynamic nature of the gateway, many of the existing routing mechanisms were difficult to configure within a gateway solution. To address this concern, the Gateway Endpoint Lookup primitive is added in WebSphere ESB 7.0. This primitive provides three dedicated modes of operation, one aimed at dynamic and static service gateways and the other two for the proxy gateway.

URL (proxy gateway)
As mentioned in a previous section, this is when the unique identifier for the virtual service is available at the end of the URL. It provides service identification information that can be used as a token to determine the endpoint address to forward the message to. In this mode of operation the configuration data is stored within the built-in configuration store. This is the recommended configuration for a proxy gateway.
XPath (proxy gateway)
This is similar to the URL mode of operation, with the exception that the unique identifier for the virtual service is extracted from the message rather than from the URL. An XPath expression identifies a location in the message, typically in the message headers, that contains the unique identifier for the virtual service. Resolution of the endpoint is then done using the built-in configuration store.
Action (dynamic and static service gateways)
Each Web service request has a SOAPAction value specified and some might also have a WS-Addressing action value. According to the specification this value should be: "An identifier that uniquely (and opaquely) identifies the semantics implied by this message". For each message passing through the primitive, the action value is determined from the service message object. Then WebSphere Service Registry and Repository is queried to find WSDL ports that have the same action value. Similar to the Endpoint Lookup primitive, it is possible to specify user defined properties and classifications for this mode of lookup.

This article only focuses on the URL mode of operation as this is the normal mode used within a proxy gateway solution. An additional aspect of the gateway endpoint lookup primitive in URL or XPath mode is the specification of which proxy groups are associated with a proxy gateway implementation. One or more proxy groups can be specified. At runtime, the endpoint resolution of the virtual service is scoped to the specified proxy groups as defined within the built-in configuration.

Administering the configuration store

A Web-based interface implemented using a Business Space widget is provided to enable you to administer the built-in configuration store used by proxy gateways.

Introduction to Business Space

Business Space powered by WebSphere provides a browser-based graphical user interface that lets business users interact with content from products in the WebSphere Business Process Management portfolio. It provides a customizable and collaborative environment for monitoring, reviewing, and administering common business processes, such as human task flows, modeling, and performance indicators.

Business Space has the concept of spaces, templates, pages and widgets. In simple terms, a space is a collection of pages that can be built based on a template, and a page is a canvas that can contain a number of widgets. WebSphere ESB and WebSphere Process Server ship a number of built in templates and widgets to provide an enhanced out of the box experience.

In the context of WebSphere ESB, Business Space provides administrative capabilities, allowing you to control and manage the applications installed on the system. The primary users are IT and solution administrators who need to manage the installed applications. It was initially introduced in WebSphere ESB V6.2 and provided the ability to view the SCA modules deployed in the server. In WebSphere ESB V7.0 the capability now includes, among other additions, the management of the built-in configuration store for proxy gateways.

The proxy gateway widget

The proxy gateway widget displays a list of proxy groups that exist in the built-in configuration store. For each proxy group in the list, there is an indication of which of the installed proxy gateways are associated with the group. When a proxy gateway is initially installed into the server, the proxy groups it references are automatically added to the configuration store if they don't already exist. However, when a proxy gateway is uninstalled from the server, the proxy groups it is associated with are not deleted. This prevents unintentional loss of configuration data for the proxy group simply because there is a moment in time when no proxy gateway applications are installed that reference it. Instead, you must explicitly delete the proxy group if it is no longer needed.

Figure 6 shows a screen capture of the proxy gateway widget. It helps to illustrate what you see when a proxy group is shared by multiple proxy gateways, when a proxy gateway has multiple proxy groups and when a proxy group exists without an associated proxy gateway.

Figure 6. Proxy gateway widget
Proxy gateway widget showing a list of proxy groups and their associated proxy gateways

In the example, take note of the following that can bee seen in the table.

  • There are three proxy gateways: PGW1_Gateway, PGW2_Gateway, PGW3_Gateway
  • There are four proxy groups: PGW1ProxyGroup, PGW2ProxyGroup, PGW3ProxyGroup, PGWSharedGroup.
  • The first row has a proxy group (PGW1ProxyGroup) that is associated with a single proxy gateway (PGW1_Gateway).
  • The second row has a proxy group (PGWSharedGroup) shared by multiple proxy gateways (PGW1_Gateway, PGW2_Gateway).
  • Rows two and three illustrate a proxy gateway (PGW2_Gateway) that is associated with multiple proxy groups (PGWSharedGroup, PGW2ProxyGroup).
  • The fourth row has a proxy group (PGW3ProxyGroup) without an associated proxy gateway.

From this table, you can select a proxy group to edit. To do so, you first must select the proxy group’s row in the table, which makes a pencil icon visible. Clicking on the pencil transitions the widget to a new view where you can configure the virtual services for the proxy group. Additionally, if the selected row is for a proxy group without an associated proxy gateway, an X icon is visible which enables you to delete the proxy group. These are illustrated in the screen capture in Figure 7:

Figure 7. Edit and delete icons for a proxy group
Proxy gateway widget with a proxy group selected, illustrating the appearance of the pencil icon for editing and the X icon for deletion

When a proxy group is initially created in the configuration store, there are no virtual services defined. When you edit it for the first time, a panel as shown in Figure 8 is presented:

Figure 8. Proxy group with no virtual services defined
Panel for editing a proxy group. In this example, no virtual services are currently defined for this proxy group

To add a virtual service, you enter into the WSDL Location field the URL for the service endpoint, appended with ?wsdl. For example:

http://localhost:9080/BankServiceProviderWeb/sca/accountExport1?wsdl

Then click Add Service. The panel for defining the virtual service opens:

Figure 9. Panel for editing a virtual service
Panel enabling you to end the definition of a virtual service

This information represents a new virtual service and can be separated into six sections:

Port Type
The WSDL port type of the virtual service.
Virtual Service Name
The key that is appended to the URL of the export of the associated proxy gateways to create a dedicated URL for the virtual service. You may want to change the generated value to something more appropriate. For example, the default value shown in the screen capture is accountExport1_accountHttpService, which you might want to change to simply Account or AccountService.
Virtual Service URLs
Network addressable endpoints that are exposed for the virtual service via the associated proxy gateways.
Endpoint URLs
An ordered list of network addressable endpoints that are used to forward messages for this virtual service. These are available within the Target and AlternateTarget elements of the service message object following a Gateway Endpoint Lookup primitive.
Enable Virtual Service
Indicates if this virtual service should be available to a Gateway Endpoint Lookup primitive when it queries the built-in configuration store.
Advanced Service Properties
A series of user defined key value pairs associated with the virtual service. These are available within the EndpointLookupContext of the service message object following a Gateway Endpoint Lookup primitive.

Once saved, the widget returns to the list of virtual services associated with the proxy group. You can navigate back to the details section of the virtual service by again selecting the pencil icon of the corresponding row.

Tooling support for building a proxy gateway

WebSphere Integration Developer V7.0 provides support that helps to accelerate the development of a proxy gateway. It provides a pattern, which is essentially a wizard that generates a large portion of the proxy gateway implementation based on a set of parameters you provide. You might then need to make minor updates to the generated implementation to complete your proxy gateway.

Introduction to the Patterns Explorer

The pattern for the proxy gateway is accessible through a facility called the Patterns Explorer, which is a new capability in WebSphere Integration Developer V7. The Patterns Explorer provides the ability to create an integration solution for common scenarios. Depending upon the pattern and your requirements, the generated output from the Patterns Explorer might only be partially complete and require further customization.

In addition to the proxy gateway pattern, the static and dynamic service gateway wizards from WebSphere Integration Developer V6.2 have been ported to the Patterns Explorer. Additionally, new patterns for both a static and dynamic simple service proxy have been added in V7.0. Figure 10 shows the Patterns Explorer view, which allows you select the pattern you would like to work with:

Figure 10. Patterns Explorer view
Patterns Explorer view from which you can select the type of pattern you would like to work with

When you select a pattern to work with, a pattern specification view opens which provides documentation about the pattern and its use. On this panel is a button that allows you to create a new instance, which opens a pattern configuration view. This is where you specify the parameters used to generate the pattern. It is beyond the scope of this article to fully explain the Patterns Explorer, continuing instead by focusing on its use for building a proxy gateway.

Using the Patterns Explorer to generate a proxy gateway

Figure 11 shows the pattern configuration view for a proxy gateway. The left side is where you specify parameters defining the characteristics of the proxy gateway. The right side contains sections that can be opened, containing documentation for each of the parameters:

Figure 11. Pattern configuration view for a proxy gateway
View where you enter configuration information used to generate a proxy gateway pattern

The proxy gateway parameters are:

Lookup Option
This provides the capability to select the mechanism that is used to route the message. There are two available options:
  • URL
    As explained previously, this is when the virtual service identifier is available at the end of the URL. This provides the virtual service identification needed to determine the endpoint address to forward the message to. This is the recommended method for most scenarios.
  • XPath
    In some scenarios, the architecture of the enterprise may not support the extended URL pattern. In this case, the virtual service name can be encoded into the headers of the message. The XPath option provides a way to identify where in the headers the virtual service name is located. The actual setting of the XPath value needs to be customized after the proxy gateway is generated.
Logging Option
Provides the ability to specify if a Message Logger or Event Emitter primitive should be added to the request and response flow. For a Message Logger, you can also choose between logging to a database or using a Java logging implementation
Transport Protocol
As mentioned previously, the proxy gateway pattern is limited to JAX-WS Web service bindings. There are three options available, either SOAP 1.1, SOAP 1.2 or both. If both SOAP 1.1 and SOAP 1.2 are required, two separate exports and imports are generated, one for each SOAP version.

After specifying the parameters that meet your requirements, click Generate to generate the implementation and open the Pattern Summary view:

Figure 12. Proxy gateway pattern summary
Pattern summary for a proxy gateway, providing both text and diagrams illustrating the generated proxy gateway

The summary provides a nicely documented view of your proxy gateway. It provides you with the assembly diagram, the mediation flow overview, the requestOnly request flow and the requestResponse request and response flows. This gives you the ability to review in one place what has been generated. Each of the diagrams displayed can be clicked on to open the appropriate editor.

Proxy gateway example

This section shows you how to build, deploy, configure, and test a proxy gateway. It assumes that you have WebSphere Integration Developer V7.0 installed, including the WebSphere Test Environment with a server profile for either WebSphere ESB or WebSphere Process Server, V7.0.0.2 level or later. Simple service implementations are provided that are the endpoints for the virtual services in the proxy gateway you build. These instructions assume that you have some experience with WebSphere Integration Developer and the WebSphere Test Environment server. Here are the basic steps for the example:

  • Set up the environment.
  • Use the Patterns Explorer to generate a proxy gateway.
  • Deploy the services and the proxy gateway to the server.
  • Configure the proxy group using Business Space.
  • Test the proxy gateway using the Web Services Explorer.
  • Suggestions for additional things you can try.

Setting up the environment

You need to know your HTTP port for the server you use

In a typical WebSphere Integration Developer installation, WebSphere Process Server uses 9080 and WebSphere ESB uses port 9081. Using any port other than the default 9080 requires some additional steps for configuration and testing. These instructions assume the server is using 9081, thus providing the extra steps needed when the port is not the default 9080.

  1. Start WebSphere Integration Developer using a new workspace.
  2. From the Servers view, start the test server (either WebSphere ESB or WebSphere Process Server).
  3. From the Downloads section at the end of this article, download the project interchange file BankProvider.zip.
  4. Import BankProvider.zip into WebSphere Integration Developer.
  5. Take a few moments to familiarize yourself with the BankProvider project:
    • The assembly diagram contains two service implementations, LoanService and SavingsService
    • Each service is exposed using a JAX-WS SOAP 1.1 binding.
    • The Loan interface has two operations: getBalance and payment.
    • The Savings interface has three operations: getBalance, deposit and withdraw.
    • There is no real data behind the services. The operations simply echo back a response message that includes the input data.

Constructing a proxy gateway using the Patterns Explorer

  1. Open the Patterns Explorer. Figure 13 shows two possible ways to do this: an icon on the toolbar, or a link from the Getting Started panel. You can also open it by selecting Window => Show View => Patterns Explorer:
    Figure 13. Links for opening the Patterns Explorer
    WebSphere Integration Developer, showing two of the possible ways that you can use to open the Patterns Explorer view
    Once it has opened, Figure 14 shows the Patterns Explorer on the left and the panel on the right provides general information about patterns.
    Figure 14. Patterns explorer showing pattern specification documentation.
    Patterns explorer when initially opened, including a panel providing documentation of what patterns are and how to use them
  2. In the Patterns Explorer, click on Proxy Service Gateway. There is now a specification panel on the right with documentation for a proxy gateway.
  3. Create a new proxy gateway: clicking Create new instance in the lower left corner of the Specification panel.
  4. Provide an integration solution name in the dialog, such as BankProxy, as shown in figure 15, and click OK:
    Figure 15. New pattern instance dialog
    New pattern instance dialog prompting you to provide an integration solution name to use for the new pattern
  5. The right side now displays the pattern configuration panel for a proxy gateway with the default values filled in. This panel was previously shown in Figure 11. The defaults are:
    • Lookup method = URL
    • Logging options = Do not log messages
    • Transport protocols = Web Service (SOAP 1.1/HTTP)
  6. For this example, the default parameters are acceptable. Click Generate to generate a proxy gateway with the default configuration.
  7. After the required artifacts are generated, the pattern summary panel opens, as shown above in Figure 12. Scroll down and click on the requestResponse Request Flow diagram to open this flow in the mediation flow editor.
  8. Examine the mediation flow, which consists of a single Gateway Endpoint Lookup primitive named RouteMessage. This is the bare minimum required for a proxy gateway to function and is what gets generated when no logging is required.
  9. Select the RouteMessage Gateway Endpoint Lookup primitive and then go to the Properties view, Details panel:.
    Figure 16. Details panel for a Gateway Endpoint Lookup primitive
    Details panel of the properties view for a Gateway Endpoint Lookup panel, showing the lookup method and associated proxy group names
    The lookup method is set to URL and that a default proxy group named BankProxyProxyGroup has been added. The default proxy group is always named <Proxy Gateway Name>ProxyGroup. The other properties don't apply to the URL lookup method, and are therefore disabled.

The proxy gateway is now complete. For this example, there was no additional customization of the proxy gateway needed. The mediation module is ready to be deployed exactly as it was generated. However, in most situations you will need to do some customization to address your requirements for having a proxy gateway, such as adding header manipulation or auditing.

Deploying to the server

  1. From the servers view, get the context menu for your running server and select Add and Remove Projects:
    Figure 17. Opening the add and remove projects dialog
    Context menu for a server used to open the add and remove projects dialog
  2. As shown in Figure 18, select BankProviderApp and BankProxy_GatewayApp and then click Add > to move them to the Configured projects panel. Click Finish.
    Figure 18. Add and remove projects dialog
    Screen capture of the add and remove projects dialog, showing that the BankProviderApp and BankProxy_GatewayApp can be added by pressing the Add button.
  3. Wait for the projects to finish publishing to the server and ensure that they started successfully, as shown in Figure 19:
    Figure 19. Servers view with projects deployed to WebSphere ESB
    Servers view showing the BankProviderApp and BankProxy_GatewayApp running on the WebSphere ESB test server

Business Space configuration

  1. Access Business Space using a Web browser: Open a Web browser and navigate to http://<hostname>:<port>/BusinessSpace (for example http://localhost:9081/BusinessSpace). Alternatively, you can go to the Servers view, get the context menu for your running server and select: Launch => Business Space, as shown in Figure 20:
    Figure 20. Launching Business Space from the context menus for the server
    Menu selection used to open Business Space from the context menus for the WebSphere ESB test server
    This method opens the external Web browser you have configured for use with WebSphere Integration Developer. The internal Web browser provided with WebSphere Integration Developer does not work with Business Space.
  2. At the Business Space login screen, enter the credentials needed for your server. Typically, for a WebSphere Test Environment server, these are the default values of admin/admin. Click Login.
  3. When Business Space opens, what you see depends upon what you have done previously with Business Space. You might see the Welcome to Business Space panel as is shown in Figure 21, or you may see something else.
    Figure 21. Business Space open in a browser
    Web browser with Business Space open. The image highlights the Manage Spaces tab and the Start button used to open the space manager
  4. Open the Space Manager: Click on the Manage Spaces tab located at the top, or alternatively, if you see the Welcome to Business Space panel, click on the large green Start button. You will see the Space Manager as shown in Figure 22.
    Figure 22. Space manager
    Space manager listing the spaces available for you to use, with the Service Administration space highlighted
  5. Click on the Service Administration space. This automatically creates a space based on the template. It includes four pages with tabs along the top. Click on the Proxy Gateway tab to display the proxy gateway page, composed of one widget, the proxy gateway widget:
    Figure 23. Proxy gateway widget
    Service administration space with the proxy gateway tab selected, showing the proxy gateway widget
  6. Notice that the BankProxyProxyGroup is present and associated with the BankProxy_Gateway. This association was added to the configuration store when you deployed the BankProxy_Gateway to the server. To configure virtual services for this proxy group, select the BankProxyProxyGroup row and click on the pencil icon, as shown in Figure 24:
    Figure 24. Opening the proxy group editor
    Pencil icon you click on to open the editor for a proxy group.
  7. Figure 25 shows the page enabling you to add virtual services to the proxy group. At this stage there are no virtual services configured for the proxy group.
    Figure 25. Virtual services for a proxy group
    Virtual services configured for a proxy group. It also provides an input field to enter a WSDL location for adding additional virtual services.
  8. As previously discussed, to add a virtual service, you need to specify the WSDL location in the form:
    <NORMAL-EXPORT-URL>/<VIRTUAL-SERVICE-NAME>?wsdl

    . To determine the NORMAL-EXPORT-URL, check the binding of the export for the service, shown in Figure 26 for the LoanService. The port specified needs to be appropriate for the server on which the service is deployed, not necessarily 9080 as shown in the binding:
    Figure 26. Binding for a Web services export
    WebSphere Integration Developer Binding panel in the properties view of a Web services export. This panel provides the URL for the service endpoint
  9. Now add the LoanService endpoint as a virtual service in the proxy group. Enter
    http://localhost:9081/BankProviderWeb/sca/LoanExport?wsdl

    into the WSDL Location and click Add Service. The configuration panel for the virtual service opens:
    Figure 27. Virtual service configuration panel
    Screen capture of the proxy gateway widget panel used to configure a virtual service.
  10. The virtual service and its endpoint is fully configured and can be saved as-is. However, note that the default virtual service name is LoanExport_LoanHttpService. To provide a better virtual service name than the default, enter LoanService into the Virtual Service Name field and click Save.
  11. Repeat the previous three steps for the SavingsService. This completes the configuration steps in Business Space. The result should look like Figure 28, showing the two virtual services and their configured endpoints:
    Figure 28. Proxy group with two virtual services configured
    Panel listing the virtual services configured for a proxy group. It now shows the two virtual services just added along with their endpoints

Testing the proxy gateway

Now that the configuration has been completed in Business Space, the proxy gateway is ready to be used by clients. Use the Web Services Explorer in WebSphere Integration Developer to perform the testing, sending requests through the proxy gateway to the virtual service endpoints.

  1. Open the Web perspective: selecting Window => Open Perspective => Other, and then select Web in the dialog.
  2. Open the Web Services Explorer: click on its icon in the toolbar, as shown in Figure 29:
    Figure 29. Icon for opening the Web Services Explorer
    Toolbar in the Web perspective of WebSphere Integration Developer, with icon for opening the Web Services Explorer highlighted
  3. Navigate to the WSDL Page by using the icon shown in Figure 30:
    Figure 30. Icon for opening the WSDL page
    Web Services Explorer with icon used to navigate to the WSDL page highlighted.
  4. Click on WSDL Main in the Navigator panel:
    Figure 31. Link to navigate to the open WSDL panel
    WSDL page with link you need to click to navigate to the open WSDL panel highlighted
  5. The Open WSDL dialog is now shown in the Actions panel. It lets you enter the URL required to retrieve the WSDL needed by the client to invoke the virtual service. As was previously explained, you can submit requests to:
    <NORMAL-EXPORT-URL>/<VIRTUAL-SERVICE-NAME>?wsdl

    . To get the WSDL needed to access the LoanService through the proxy gateway, enter this URL into the WSDL URL field:
    http://localhost:9081/BankProxy_GatewayWeb/sca/BankProxy_GatewayExport_WS_SOAP11/
    	LoanService?wsdl

    and click Go, as shown below:
    Figure 32. Open WSDL panel
    WSDL panel showing URL to access the WSDL to invoke the loan service endpoint via the proxy gateway
  6. The result is that you are now ready to test the LoanService by routing requests through the proxy gateway. The Web Service Explorer should look like this:
    Figure 33. Web Services Explorer ready to test the LoanService
    Web Services Explorer showing the operations defined for the loan service. This panel can be used to invoke loan service request through the proxy gateway
  7. Click on the getBalance operation, fill in any value for the account number, and click Go. The invocation will be submitted to the proxy gateway endpoint and forwarded onto the endpoint for the LoanService. The LoanService generates a response that passes through the response flow of the proxy gateway. The expected result is shown in Figure 34, echoing the account number you entered and a balance of 999:
    Figure 34. Result of getBalance invocation
    Web Services Explorer showing the result from invocation of the getBalance operation. It shows a result string of Account number = 12345, Balance = 999.

Additional things you can try

To get a better overall feel for the proxy gateway, here are a few suggestions for things you can try.

  1. Test the payment operation of the LoanService.
  2. Test the SavingsService. The configuration store for this virtual service is complete, but you will need to generate the client side WSDL to invoke the service using the Web Services Explorer.
  3. Add Trace mediation primitives to the request flow both before and after the Gateway Endpoint Lookup primitive, to get a better understanding of the primitive’s operation. Use the Console view in WebSphere Integration Developer to examine the results of tracing a request. In particular:
    • In the first trace, look at the HTTPHeader where you will see the URL containing the virtual service name.
    • In the second trace, look for the EndpointLookupContext, which contains the endpoint for the virtual service. You can also see the endpoint in the Target element of the SMOHeader. This is what actually controls the routing to the target endpoint through the proxy gateway’s import.
  4. Deploy a module of your own containing a JAX-WS Web service. Configure a virtual service in the configuration store using Business Space, generate a client side WSDL for the virtual service, and then test it.

Guidelines for selecting service gateway patterns

This section discusses when it is appropriate to use each of the service gateway patterns. The information here is generic -- in some situations there may be good reasons to consider other approaches.

Web service based service gateway
If a Web service only based service gateway is required, then the starting point should be the proxy gateway pattern. A proxy gateway provides built-in routing capabilities and client side WSDL resolution. The other patterns, such as the dynamic service gateway, might require extensive user code to provide similar functionality.
Messaging or HTTP based service gateway with XML data encoding
Assuming the encoding style of the messaging and HTTP service gateways is serialized XML of business objects, then the dynamic service gateway is worth considering. WebSphere ESB V7 provides an option to automatically parse incoming messages to the gateway. Therefore, if access to the body of the message is required, this can be easily achieved in the dynamic service gateway pattern.
Messaging or HTTP based service gateway with non-XML data encoding
When access to the body of the message is not required, then the dynamic service gateway is a useful starting point to consider. However, if access to the body of the message is required, the static service gateway is likely to be the most sensible option.
Protocol switching service gateway with XML data encoding
When a multi-protocol service gateway is required and message encoding on all protocols is XML serialization of business objects, then the dynamic service gateway is worth considering. WebSphere ESB V7 provides an option to automatically parse incoming messages to the gateway. Therefore, if access to the body of the message is required, this can be easily achieved in the dynamic service gateway pattern.
Protocol switching service gateway with non-XML data encoding
When access to the body of the message is not required, then the dynamic service gateway is a useful starting point to consider. However, if access to the body of the message is required, then the static service gateway is likely to be the most sensible option.

Conclusion

This article introduced you to the proxy gateway pattern, which provides a Web service gateway that is fast to build and meets the majority of requirements with an out of the box experience. The article started with an overview of service gateway patterns and then went into detail on the architecture of a proxy gateway. It showed you how the built-in configuration store is administered using Business Space. The development tools provided, specifically the Patterns Explorer used to generate a proxy gateway implementation, was described. An end-to-end example showed you how to build, configure, and test a proxy gateway. Finally, the article presented guidelines for selecting an appropriate service gateway pattern for your requirements.


Download

DescriptionNameSize
Project interchange file for proxy gateway exampleBankProvider.zip13 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=500589
ArticleTitle=Developing and deploying a proxy gateway using WebSphere ESB V7, WebSphere Integration Developer V7, and Business Space powered by WebSphere
publish-date=07142010