SOA solutions

White paper

Best practices for service-oriented

model development with IBM
WebSphere Portlet Factory software.

March 2006
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 

Introduction
Contents An important capability of IBM WebSphere® Portlet Factory software is its
support of a two-level services architecture that provides a clean separation of
2 Introduction the presentation user interface (UI) from the back-end data access and busi-
3 Overview ness logic, for delivery of service-oriented architecture (SOA) applications.
4 How it works
5 Feature details WebSphere Portlet Factory software’s service-oriented architecture defines
6 Basic steps service provider models that access back-end data and services and ser-
13 Dynamic service swapping vice consumer or presentation models that provide the front-end Web user
13 Documentation builder interface. WebSphere Portlet Factory software automates the generation of
15 Conclusion both these layers as well as all the necessary artifacts to enable loose cou-
pling between them. This clean separation of layers, combined with a new
set of SOA-specific WebSphere Portlet Factory features allows developers
to decouple implementation and testing of the UI from the back-end access
and to streamline SOA development and deployment. This paper gives an
overview of these capabilities and how they can be used to easily create and
help manage applications within an SOA environment.
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 

Overview
The goals of WebSphere Portlet Factory software’s supporting features for
service-oriented architectures are to:

1. Enable independence and flexibility between the presentation and the

services layers, both at implementation and in deployment.
2. Speed SOA application development with increased levels of automation,
including generating appropriate service testing pages.
3. Make the most common service creation scenarios (structured query
language [SQL], packaged apps, Web Services Description Language
[WSDL]/Simple Object Access Protocol [SOAP]) very easy, including
eliminating the need for back-end access during implementation of the
UI (presentation layer).
4. Support a formal interface to speed the creation of alternate service
implementations, for swapping out back ends or providing backup services.

The approach is simple and natural: you create models that are either service
providers (back-end data access) or service consumers (front-end presentation)
and then combine them (flexibly) both for application testing and for deploy-
ment. Using this methodology, teams of developers can work independently
on the layers and don’t need to constantly coordinate and adjust to modifica-
tions made on the other side. Additionally, development can proceed without
requiring access to the targeted back-end systems, simplifying life consider-
ably for all, especially for the UI team. There are a number of new WebSphere
Portlet Factory builders and supporting features that enable this methodology
and expand on previous versions of service-oriented support.
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 

How it works
Service provider models define a service within the Web application
(WebApp); the model (and thus the service) is then referenced by service con-
sumer models. The service can provide one or more operations (similar to the
operations within a WSDL service). The service can return whatever results
are required within an application, including gathering data from multiple
back ends or databases and combining it in whatever form is required. It is
often useful to define a service with multiple, related operations, even if the
data sources represent more than one back-end system. For example a cus-
tomer information service might define operations to return a customer list
(based on search criteria), customer detailed information, customer orders,
customer complaints, and so on. A product service might define operations for
products by category, products by price, product inventory, product costs or
product sales performance.

Service consumer models, as their name implies, use one or more service
consumer builders to invoke the service operations made available by service
provider models. Usually (but not necessarily), a service consumer model will
generate a UI, obtaining data via the service provider and then using whatever
other builders are needed to generate pages with the forms, views, graphs and
so on, that comprise the presentation layer. The provider/consumer builder set
provides insulation to UI models, and loose enough coupling between UI and
service models to allow substitution of an alternate service provider model,
even during run time.
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 

Feature details
There are two core builders for the service layer:

• Service definition builder. This builder creates underlying support

for an initially empty service, provides an option for exposing the service
via WSDL and names the service.
• Service operation builder. This builder adds an operation or method to
the service defined by the previous service definition builder. The operation
can invoke any data access support available in the model. Data access is
usually provided by using one or more back-end integration builders, such
as SAP function or SQL call, but can also be provided by a Linked Java™
Object (LJO) or any data returning method. Note that the service provider
builder does not invoke the external data access application program
interface (API) itself; other builders (such as integration builders or an
LJO builder) in the provider model or in another included model, make
the calls and bring the data into the WebApp. Service providers are built
on top of those primitives. The service operation builder can also transform
data from the structures used by the back-end system builder calls into the
desired structures for the service being defined.

There is one core builder for the presentation layer:

• Service consumer builder. This builder makes all the operations defined
in a service provider model available for use. It enables other builders to
reference all the information provided by the service, including the input
and output schemas, the operations and the associated variables. With the
service consumer builder making the data available to the page automation
system, the entire array of page automation builders can be used to generate
pages. For example, the view and form builder can reference service infor-
mation, including the input and result schemas, and automatically generate
complex presentation elements such as forms and list views.
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 

Basic steps
This example shows a pair of simple service provider and service consumer
(presentation) models. It uses a Java Database Connectivity (JDBC) database
connection in the service layer (SQL call builder), although the service could
just as easily use any WebSphere Portlet Factory integration builders such as
SAP, IBM Lotus® Domino® software, PeopleSoft, Web services or any integra-
tion builders created for proprietary back ends.

Essentially only two steps are required:

1. Create the service layer (service provider model) with three builders:
a. Integration builder (ex., SAP, SQL, Lotus Domino server) or method
b. Service definition builder
c. Service operation builder(s)

2. Use the service operations in the presentation model, with these builders:
a. Service consumer builder
b. V
 arious page automation builders (ex., view and form, record list
and details)
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 

Once these core pieces are in place, you can then add other builders to
enhance the service or consumer side as desired.

Figure 1 illustrates these two simple models and the major artifacts they
create or use in the WebApp.

Service model WebApp

• SQL call Data service

Retrieves customerList Customers

• Service definition Methods

Defines “Customers” as a service invokeDB
findCustomers
• Service operation getCustomerDetail
Defines operation “findCustomers”
with inputs (search) and results Variables
Defines operation “getCustomerDetail” customerList
CustomerDetail

Pages
Presentation model InputPage
DisplayPage
• Service consumer
Declares use of the service “Customers”

• View and form

Uses the view method “findCustomers”
Generates pages

• Additional page automation builders

Column modifiers, additional validation, etc.

Figure 1
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 

To further enhance the development of SOA applications, WebSphere Portlet

Factory software provides an additional set of features that simplify and speed
the development effort:

• Stub service models and disconnected support. A simple button

in the service definition builder automatically creates a stub service model.
This is a completely generated model that has an identical interface to the
original service provider model, but includes an entirely self-contained
snapshot of operations, schemas and sample data. The stub service model
removes the need for you to be connected to the data source, reducing the
hassle of configuring your system and eliminating the need for connecting
to a real system such as SAP, Lotus Domino software or PeopleSoft, or
ensuring the local presence of a developer’s version of the system. If desired,
the sample data can be automatically captured from actual result data
obtained by invoking the service just once, and then using the disconnected
support after that.
• Disconnected development approach. If your back-end system is slow in
responding or has limited availability, you will save considerable time by
using this disconnected development approach. Using a stub service model
means that the generation process doesn’t need to access the slow back end
for every regeneration cycle.
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 

• Service test builder. The service test builder lets you automatically
generate the pages and code required for testing all the operations defined
within a service, including the specification of default inputs for testing each
operation. The service test builder allows you to easily validate your back-
end functionality with complete independence from any presentation layer,
and without having to build a separate test harness. You can also generate
“headless” methods that call the service operations directly, a capability
that is useful for establishing automated testing of services, without having
to view browser pages.
• Service documentation builder. The service documentation builder
automatically generates service documentation on both sides of this dual
architecture. It will create information about the service and its operations,
including inputs and results, for services created by a service provider model
or for services used by a service consumer model. Alternatively, a separate
documentation model can be used to generate the document for any services
within the WebApp.
• Dynamic service mapping. This powerful feature enables you to dynami-
cally manage equivalent services, by letting you swap the actual service
provider model used whenever a service is referenced, either at design
time or at run time. A service mapping registry, a simple XML file, is used
to specify which model should be used to supply the referenced service.
This service mapping capability automatically supports scenarios such as:

– Using a stub service model for much of the provider implementation effort
and swapping in actual connectivity only to test out what you have built.
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 10

– Using a stub service model for the development and testing of the presen-
tation models, then simply modifying the service mapping file to enable
the real service (with real connectivity) to be used.
– Switching to an alternate service implementation (for example, to use
a different back end) at any time, without needing to modify any of the
presentation models. This enables substitutable services, either during appli-
cation development or for a deployed application. The only requirement is
that the selected model implements the same service provider interface.

• Support for implementation of service interfaces. To facilitate swapping

of service provider models, the new builder set supports the notion of a ser-
vice interface, similar in concept to a Java interface. The service definition
builder allows you to specify the name of another service provider model
that you want to use as the interface definition. The interface concept is very
useful when you want to develop alternate service provider implementations
that all work with a common set of presentation (service consumer) models.
It ensures that you can swap between service provider models without break-
ing the presentation models. The service definition and service operation
builders automatically provide assistance and verification for accurately
implementing the specified service interface (the alternate implementation
is not automatically generated). The service name, operation names and
the number and names of operation parameters are verified. Since input
and result types are not included in the verification, you could leverage the
adaptive features of the WebSphere Portlet Factory software to implement
the service with alternate formats.
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 11

Using these additional capabilities, there are six basic steps to create a flexible
SOA-based application:

1. Create the service layer (service provider model) with three builders:
a. Integration builder (ex., SAP, SQL, Lotus Domino server) or method
b. Service definition builder
c. Service operation builder(s)

2. Test the service operations right in the service provider model, add:
a. Service test builder (or checkbox in service definition)

3. Use the service operations in the presentation model, with these builders:
a. Service consumer builder
b. Various page builders (ex., view and form, record, list and detail)

4. Optionally generate a stub service model. In service provider model, add:

a. Service stub builder (or button in service definition)

5. Optionally generate documentation. In either or both models, add:

a. Service documentation builder

6. Optionally use service mapping registry to use the stub service model
or to switch between service implementations. Set mappings in:
a. XML files in WEB-INF/config/service_mappings
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 12

Figure 2 shows the use of the full set of capabilities.

Of course, these examples are still just the basics. While most service provider
models will remain fairly simple, presentation models will be arbitrarily more
complex, depending on the application requirements.

Service model Stub service model

• SQL call • Schema

Retrieves customerList
• Variable (holds sample result data)
• Service definition
Defines “Customers” as a service • Service definition
Defines “Customers” as a service
• Service operation
Defines operation “findCustomers” • Service operation
with inputs (search) and results Defines operation “findCustomers”
Defines operation “getCustomerDetail” with inputs (search) and results

This model is completely autogenerated.

Presentation model

• Service consumer
Declares use of the service “Customers”

• View and form

Uses the view method “findCustomers”
Generates pages

• Additional page automation builders

Column modifiers, additional validation, etc.

Figure 2
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 13

Dynamic service swapping

Figure 3 illustrates the use of the dynamic service mapping mechanism to
swap between implementations of a service interface. Although the output
is identical in this diagram, the system will adapt successfully to minor
variations in the services (such as whether data chunking for data paging
is supported).

Service provider models

Variants of a service

getCustomers

Service
Production-1 model consumer model
Dynamic
SAP getCustomers service User interface
Interface
mapping
mechanism
Production-2 model

JDBC getCustomers

Figure 3

Documentation builder
On page 14 is a sample of the documentation produced by the service
documentation builder.
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 14

Services used
Model: services/CustomerProvider
Service : customerList
Operation : execute
Parameters : Name Variable Type Direction
Results customerListTransformXml customerListTransformSchema/Customers Output

Service : customerSearch
Operation : execute
Parameters : Name Variable Type Direction
Inputs customerSearchInputs customerSearchInputs Input
Results customerSearchTransformXml customerSearchTransformSchema/Customers Output

Service : publicService
Operation : getCustomerList
Parameters : Name Variable Type Direction
Results getCustomerListResults customerListTransformSchema/Customers Output
Operation : findCustomers
Parameters : Name Variable Type Direction
Inputs getCustomerListResults customerSearchInputs/customerSearchInputs Input
Results findCustomersResults customerSearchTransformSchema/Customers Output

Service : nonPublicService
Operation :
Parameters : Name Variable Type Direction

Model: MyProvider1
Service : List
Operation : execute
Parameters : Name Variable Type Direction
Results ListTransformXml ListTransformSchema/Addresses Output

Service : Details
Operation : execute
Parameters : Name Variable Type Direction
Inputs DetailsInputs DetailsInputs/DetailsInputs Input
Results DetailsTransformXml DetailsTransformSchema/Addresses Output

Service : Addrs
Operation : execute
Parameters : Name Variable Type Direction
Inputs getDetailsInputs DetailsInputs/DetailsInputs Input
Results getDetailsResults DetailsTransformSchema/Addresses Output

Service : getList
Operation : execute
Parameters : Name Variable Type Direction
Results getListResults ListTransformSchema/Addresses Output
Best practices for service-oriented model development
with IBM WebSphere Portlet Factory software.
Page 15

Conclusion
With IBM WebSphere Portlet Factory software’s delivery of SOA-based port-
lets, the time needed to implement composite applications can be significantly
reduced because it provides tools and technology to leverage this new develop-
ment paradigm – as well as boosting developer productivity by reducing the
associated skills required to enable the integration of established applications.

ibm.com/websphere/portletfactory/
© Copyright IBM Corporation 2006

IBM Corporation
Software Group
One Rogers Street
Cambridge, MA 02142
U.S.A.

Produced in the United States of America

03-06
All Rights Reserved

 omino, IBM, the IBM logo, Lotus and WebSphere

D
are trademarks of International Business
Machines Corporation in the United States, other
countries or both.

J ava and all Java-based trademarks are trade-

marks of Sun Microsystems, Inc. in the United
States, other countries, or both.

O
 ther company, product and service names may
be trademarks or service marks of others.

R
 eferences in this publication to IBM products and
services do not imply that IBM intends to make them
available in all countries in which IBM operates.

T
 he information contained in this documentation
is provided for informational purposes only. While
efforts were made to verify the completeness
and accuracy of the information contained in this
documentation, it is provided “as is” without war-
ranty of any kind, express or implied. In addition,
this information is based on IBM’s current product
plans and strategy, which are subject to change by
IBM without notice. IBM shall not be responsible
for any damages arising out of the use of, or oth-
erwise related to, this documentation or any other
documentation. Nothing contained in this docu-
mentation is intended to, nor shall have the effect
of, creating any warranties or representations from
IBM (or its suppliers or licensors), or altering the
terms and conditions of the applicable license
agreement governing the use of IBM software.

GC28-7738-00