Best Practices for Designing and

Building the Services of an SOA

Guido Schmutz
Technology Manager, Oracle ACE
Director for FMW & SOA
Trivadis AG, Switzerland
Abstract

This session will present best practices for designing

and building the services of an SOA. Different ways
of implementing services in different environments
and languages are presented and the pros and cons
of each approach will be discussed. The session will
cover how to ensure service versioning, why
contract-first is the preferred approach, and under
which circumstances a contract-last approach might
be valid and useful.
Guido Schmutz

Working for Trivadis for more than 14 years

Oracle ACE Director for Fusion Middleware and SOA

Co-Author of different books

Consultant, Trainer Software Architect for Java, Oracle,
SOA and EDA

Member of Trivadis Architecture Board

Technology Manager @ Trivadis

More than 20 years of software development

experience

Contact: guido.schmutz@trivadis.com

Blog: http://guidoschmutz.wordpress.com

Twitter: gschmutz
Trivadis Facts & Figures

11 Trivadis locations with more than 550

employees

Financially independent and sustainably
profitable

Key figures 2010
~180
employees
Revenue CHF 101 / EUR 73 mio.

Services for more than 700 clients in over

1800 projects

Over 170 Service Level Agreements

~20
More than 5'000 training participants employees
~350
Research and development budget: employees
CHF 5.0 / EUR 3.6 mio
Agenda

Principles of Service Design

Service Design

Service Model and Implementation

Service Versioning

Summary
Principles of Service-Orientation
Service Design Principles

Standardized Contract Implement a

standardized contract

Loose Coupling Minimize dependencies

Abstraction Minimize the availability of meta information

Reusability implement generic and reusable logic and contract

Autonomy implement independent functional boundary and
runtime environment

Composability Maximize composability

Statelessness Implement adaptive and state management-
free logic

Discoverability implement communicative meta information
Agenda

Principles of Service Design

Service Design

Service Implementation

Service Versioning

Summary
Development Approaches

Bottom up Produktio Verkauf

Top-Down
n

Top Down Domain

Meet in the F&E Rohstoffeingang Produktgenehmigung

middle (agile)
Service Service Service

Bottom-Up Service Service Service

API Components
Files DB Applications
Contract-First Web Service Design

Important for service-

orientation is the
standardizing and
decoupling of the
technical contract of
each service

Service-oriented design
therefore should be
based on a contract
first approach
avoid the use of auto-
generation tools Source: Thomas Erl, Principles of Service Design
Contract-First is
fine ..

But isnt it just too hard to get ?

Most SOA platforms do not make a
contract-first service design easy
Creation of WSDL and XSD is too
much effort

There is build-in support in the IDE to
graphically implement WSDL and
XSD
Platform specific, no standard for
look-and-feel
I like Contract First design, BUT
<wsdl:definitions xmlns:tns="http://trivadis.com/service/credit-card/v1"
...
name="CreditCardValidation-v1">
<wsdl:types> <xs:schema xmlns:xs=..."

Lot of repetition <xsd:schema ...> xmlns:tns="http://www.trivadis.com/cdm/credit-card/v1"
</wsdl:types> targetNamespace=http://www.trivadis.com/cdm/credit-card/v1
Very talkative elementFormDefault="qualified"
<wsdl:message name="validateCardRequest">
attributeFormDefault="unqualified" version="1.0">
More options than <wsdl:part name="request"<xs:element name="creditCard" type="tns:CreditCardT"/>
(often) necessary => element="tns:validateCreditCardPaymentRequest"/>
<xs:complexType name="CreditCardT">
</wsdl:message> <xs:sequence>
RPC/literal <wsdl:message name="validateCardResponse">
<xs:element name="creditCardKind"

How to ensure Design <wsdl:part name="reply" type="tns:CreditCardKindT"/>
<xs:element name="cardNumber" type="xs:string"/>
element="tns:validateCreditCardPaymentResponse"/>
guidelines </wsdl:message> <xs:element name="cardholderFirstName"
type="xs:string" minOccurs="0"/>
<wsdl:message name="invalidCreditCardNumberFault">
WS-I compliance <xs:element name="cardholderLastName"
<wsdl:part name="error
Asynchronous type="xs:string"/>
element="tns:invalidCreditCardNumberFault"/>
<xs:element name="expirationMonth"
Interface </wsdl:message> type="tns:MonthT"/>
<wsdl:portType name="CreditCardValidationPT">
<xs:element name="expirationYear"
Service versioning <wsdl:operation name="validateCard"> type="tns:YearT"/>

Ensure naming <wsdl:input message="tns:validateCardRequest"/>
</xs:sequence>
<wsdl:output message="tns:validateCardResponse"/>
<xs:attribute name="id" type="xs:int"/>
conventions </xs:complexType>
<wsdl:fault name="InvalidCreditCardNumberFault"
<xs:simpleType name="CreditCardKindT">
message="tns:invalidCreditCardNumberFault"/>
Name of messages <xs:restriction base="xs:string">
</wsdl:operation>
Name of port types </wsdl:portType> <xs:enumeration value="visa"/>
<xs:enumeration value="mastercard"/>
<wsdl:binding ...>
Name of bindings <wsdl:service ...>
<xs:enumeration value="amexco"/>
</xs:restriction>
</wsdl:definitions> </xs:simpleType>
...
/xs:schema>
Alternative: UML with WS profile

Enterprise Architect has a

special profile for WSDL
and XSD modelling
 CBDI-SAE UML Profile Customer Relations

+
Business Type
Customer

num ber: {id1}

for SOA
+ nam e
+ bill ingAddress 0..*
+ lastYearShi pmentsVal ue
+ lastQtrShipmentsValue
+ thisQtrShipmentsValue
+ contactName1
+ contactName2
1 1
1 1 {i d1}
{i d1}

Suppliers Shipping owns

Busi ness Type Business Type makes Business Type
Warehouse Vehicle
receives Account
is base for
+ name: {i d2} + registrationNbr: {id2} 1
+ number: {i d1}
+ number: {i d1} 1 * + manufacturer ships from Busi ness T ype
+ name
+ address + model * Payment
+ openi ngDate
+ capacity + capacity
+ date: {id1} + balance
+ fl eetNbr requests
{id1} * + amount: {i d1}
1 0..1 {id1}
Application Business Type
Subcontractor
visited on {i d1} *
Parcels System makes
houses contains
+ name: {id1} * recorded i n
+ address 1..* in response
+ perform anceRating * Busi ness Type to
1..* Business Type
+ ourAccountNbr Journey 0..1 1 *
Pick Up Point
Required Behavior Required Behavior + date: {i d1}
Required Behavi or 1
Busi ness Type + shortName: {id1} Business Type Busi ness Type
{id1} + number: {i d1} Account Entry
Warehouse Position + address 0..1 Inv oice
+ routeCode
+ i sScheduled + guidance + sequenceNbr: {id1}
holds + number: {i d1} + number: {id1} recorded i n
shipments + issueDate + amount
Process at
+ descri ption
0..1 0..1 + total Amount
0..1 1 + isDebit
T echnical Interface * + typeCode 1 + reference
Techni cal Interface Technical Interface currently
+ status
+ date

Service Deloyment Architecture Schedule Pickup

Pickup and DelivBusiness
er Type
Subcontractor
Location
Obtain Payment
stores
currently conveying

1 1..*
origin for
+ discountGiven

{i d1}
contains
Automation U... Automation Unit Automation U...
Showing Deployments 0..1 currentl y holds *
+ shortName *
Schedule Pickup Pickup and Deliv Obtain Payment Business Type
+ er
address *
Business Type
Shipment
Inv oice Item
+ tagNbr: {i d1}
Required Behavior * + desti nationAddress pai d for by + number: {id1}
0..1
+ weight + description
Automation Unit 1 + charge
Business Type + di mensi on
Implementation Model:: Handling Procedure + speci al Needs
Customers defines procedures for
Core Business + desti nationInstructions
Finance
Required Behavior + parcelType: string
* * + charge
Required Behavior + definition: stri ng
+ contentDescri ption
+ procedure: string T echnical Interface
Required Behavior + constraints: sting
Inv oices
Technical Interface
Required Behavior
manifest Subcontractors Required Behavior
Automation Unit
Required Behavior Inv oices
Business Type Busi ness Type
Endpoint Deployed AU Automation Unit HazardousShipment FoodShipment
:Customers :Customers Technical Interface
Shipping Obj ects
Shipments
Endpoint Implementation
Required Behavior
T echnical Interface Required Behavior
Deploy Deploy
Warehouses
instanceOf
Techni cal Interface
Node
Technology Model::alpha :Sun Serv er
Node
Technology Model::beta :Sun Serv er
instanceOf
Service Instance
cust01 :Customers
Required Behavior
Required Behavior Technical Interface
Customers
Accounts
Business Type Model
Automation Unit

Deploy
Automation Unit
Customers
Accounts
Showing Domains
executionEnvironment... executionEnvironment... Required Behavior
:SOAP Engine :EJB Container Deploy Required Behavior
Service Instance
cust02 :Customers Required Behavior
(from Technology Model) (from Technology Model) Utility Required Behavior
Automation Unit
Prov iderX Required Behavior
Communication Path Technical Interface
Communication Path
AddressFormatter

Node
Technology
Model::r01 :
Underlying
T echnical Interface
Router
Transactions
Techni cal Interface
Automation Unit
Customer Inv oicing
Automation Unit
Relationships
Accounting System T echnical Interface
New Accounts

Service Implementation Architecture http://everware-cbdi.com

Showing Services and Automation Units
Using DSL to simplify WSDL generation
abstract message common {
<wsdl:definitions xmlns:tns="http://trivadis.com/service/credit-card/v1" requestNr : String [1:1]
... }
name="CreditCardValidation-v1">
<wsdl:types>
Import common.msgtype
<xsd:schema ...>
namespace service.credit-card(1.0)
</wsdl:types>
using cdm.credit-card(1.0) as cc
<wsdl:message name="validateCardRequest">
<wsdl:part name="request"
message validateCardRequest extends common {
element="tns:validateCreditCardPaymentRequest"/>
creditCard : cc.CreditCard
</wsdl:message>
forAmount : Double
<wsdl:message name="validateCardResponse">
}
<wsdl:part name="reply"
message validateCardResponse {
element="tns:validateCreditCardPaymentResponse"/>
requestNr : String[1:1]
</wsdl:message>
reservationNumber : String
<wsdl:message name="invalidCreditCardNumberFault">
}
<wsdl:part name="error
element="tns:invalidCreditCardNumberFault"/>
fault invalidCreditCardNumber {
</wsdl:message>
code : String
<wsdl:portType name="CreditCardValidationPT">
creditCard : cc.CreditCard
<wsdl:operation name="validateCard">
}
<wsdl:input message="tns:validateCardRequest"/>
<wsdl:output message="tns:validateCardResponse"/>
service CreditCardValidation {
<wsdl:fault name="InvalidCreditCardNumberFault"
sync operation validateCard
message="tns:invalidCreditCardNumberFault"/>
throws invalidCreditCardNumber
</wsdl:operation>
input validateCardRequest
</wsdl:portType>
output validateCardResponse
<wsdl:binding ...>
<wsdl:service ...>
}
</wsdl:definitions>
Domain Specific Language (DSL)

A Domain Specific Language (DSL) is

A small programming language, which focuses on a particular domain
The right tool for the right job

The opposite is a General Purpose Language (GPL)
A language such as Java or C#
A general purpose modeling language such as UML

A DSL can be a visual diagramming, programatic abstractions or
textual languages
Text based DSL are more and more common

Examples of existing DSLs
SQL, Ant, XML, BPEL, BPMN

Define you own custom DSL according to the problem
Service interface in our case
Prototype based on Eclipse XText
available
Service Contract Template => DSL
service CreditCardValidation {
version : 1.0
namespace : CreditCard

business-properties {
name: Kreditkarten-Validierung
purpose:
domain: CreditCard
technical-properties {
owner: xxxx
service-type: BAS, BES
execution-frequency: 100 per day

operation validate-card
throws InvalidCreditCardNumber, ServiceFault {
operation-group: read-only
updating: true
resultCache: true
atomicTx: true
idempotent: true
can-particpate-in-tx: true
pattern: one-way | request-response

input-message {
RequestNr : ct.Text[1:1]
CreditCard : cc.CreditCard
}

output-message ValidateCardResponse {
RequestNr : core.Text
CreditCard : cc.CreditCard
WS-I: check your contracts!

An open industry effort promoting Web Services interoperability

~130 member organizations (2004)

Deliverables
Profiles
Sample applications
Test tools and supporting materials

Current profiles
Basic Profile 1.1, 1.2 (in work)
SOAP, WSDL, WS-Addressing, MTOM
Basic Security Profile (in work)
WS-Security and security token formats

Use these tools to check your contracts
Command line, soapUI, Maven plugin
Message Exchange Patterns (MEP)

There are four basic message exchange patterns (MEPs) used in Web
services
Notification

Request/Response
Web
Application Solicit Response Application
Service
One-Way

One-Way - A message comes to the service and the service produces nothing in
response (Fire-and-Forget).
Request/Response - A message comes to the service, and the service produces a
message in response (main program & subroutine architecture style).
Solicit Response - The service sends a message and gets a response back
(Reverse Request / Response).
Notification - The service sends a message and receives nothing in response
(Broadcast, Publish-Subscribe)

Solicit Response and Notification are not supported by the WS-I Basic
Profile
Standardized Service Data Models
Canonical Data Model

Source: Enterprise Integration Patterns (www.eaipatterns.com)

Standardized Service Data Models
Canonical Data Model
 Service Usage Scope

Scope Typical WS-Attribute:

Document style, industry standard
Cross Organisational data formats

Document style, enterprise data

formats
Within Organization
Document or RPC style, LOB
data representations

Within Department Function call, RPC or RMI

Inside Application
Granularity

Tight Loose
Level of coupling
SOA Logical Architecture Service
Categorization

Source: Oracle
Agenda

Principles of Service Design

Service Design

Service Implementation

Service Versioning

Summary
What type of applications do we find
today?
a) PL/SQL in the database holds logic
b) Java holds business logic, data access is implemented in
PL/SQL
c) Java holds business logic and data access (JDBC or O/R
Mapper), no PL/SQL in database

Application A Application B Application C

Business Logic PL/SQL Java Java

Data Access PL/SQL PL/SQL ORM

Storage Tables Tables Tables

PL/SQL Implementation of Use Case

PL/SQL Package specification

Object types
Java Implementation for Use Case

Customer Service Interface in Java

Customer and Address DTO

Service-enable applications directly

For B and C a Java Web Service Facade can be written

How can deploy existing PL/SQL logic as a Web Service ?

Application A Application B Application C

Web Service ???? Java Java
Facade

Business Logic PL/SQL Java Java

Data Access PL/SQL PL/SQL ORM

Resource Tables Tables Tables

Service Interface
for Use Case
JAX-WS WSDL First
 JAX-WS WSDL First
JAX-WS Annotations

JAXB Annotations

EJB Annotations

Transformation
Java with JAX-WS - Code First

Determines XSD

Determines WSDL
Native Database Web Service (11g)

A servlet in the database (DBWS) acts as a gateway to:

SQL Statements
XQuery
PL/SQL
Native Database Web Service (11g)
Service Enablement of DB logic
using Oracle Service Bus (OSB)
OSB adds a layer of indirection (virtualization)
Mediation: Transformation, Filtering, Enrichment, Routing
Adapter: supports integration of existing applications

OSB OSB OSB

Mediation Mediation
SOA Platform Mediation
Adapter Adapter

Application A Application A Application A

Web Service
DB Servlet
Facade

Business Logic PL/SQL PL/SQL

Data Access PL/SQL PL/SQL

Resource Tables Tables Tables

OSB and DB Adapter for request-
driven access to information
Problem
Want to directly access data from DB of an existing Java application
Solution
Use the DB Adapter on the OSB to implement CRUD DB operations
Provide it as a contract-first SOAP web service on OSB

SQL
Demo: Database Adapter on OSB
Service Enablement of Java using
Oracle Service Bus (OSB
OSB adds a layer of indirection (virtualization)
Mediation: Transformation, Filtering, Enrichment, Routing
Adapter: supports integration of existing applications
OSB OSB
Mediation Mediation
SOA Platform Transport Adapter

Application B Application C
Web Service Java
Facade

Business Logic Java Java

Data Access PL/SQL ORM

Resource Tables Tables

 OSB HTTP Transport to wrap JAX-WS
service
Problem
Want to offer a contract-first SOAP-based Web Service to consumers
and not the JAX-WS service
Solution
Use OSB HTTP Transport to wrap the JAX-WS Code-First service
Provide it as a contract-first SOAP web service on OSB

Transform from/to canonical model

SOAP Webservice
OSB HTTP Transport to wrap JAX-
WS Code First service
Proxy Service Business Service HTTP Transport

XQuery Transformation

Transformation
OSB EJB Transport to call EJB

Problem
Want to use an EJB session bean directly without having to service
enable it first
Solution
Use OSB EJB Transport to access the existing EJB session bean
Provide it as a contract-first SOAP web service on OSB

RMI / IIOP

Transaction propagation
OSB EJB Transport to call EJB

Proxy Service Business Service EJB Transport

Service Enablement in BPEL/BPMN
BPEL and BPMN
Orchestration

SOA
Platform OSB
Mediation Mediation Mediation
Adapter

Application A Application B Application C

Web Service Java Java
Facade

Business Logic PL/SQL Java Java

Data Access PL/SQL PL/SQL ORM

Resource Tables Tables Tables

Automatic Build &
Deployment

Goals
Automate everything
WLS Domain creation
Schema repository creation
OSB & SOA artifacts build
& deployment
soapUI integration testing
Hudson Integration
Continuous Integration

Tools
Hudson
Maven
soapUI
Subversion
Nexus Maven Repository
Agenda

Principles of Service Design

Service Design

Service Model and Implementation

Service Versioning

Summary
Service Versioning

Services once deployed can never be

changed
Stable endpoints, dont necessarly know our
consumers

WS-* specs have
no versioning
concept in place

The ripple effects of changes

Service Versioning

In software, major-minor versioning is used to accommodate

two levels of change

A major change indicates a large update that creates an
incompatibility with existing deployments
Typically indicates large scale revisions of the product with
significant new features or bug fixes
Change to the first digit

A minor change indicates an update that is backward
compatible with existing deployments of the software that share
the same major version
Typically contain a number of small new features, bug fixes and
issues resolutions that do not break compatibility
Change to the second or subsequent digit
Implementing Versioning on ESB

Common Endpoint for all One Endpoint per Major Version

versions with Version in Message

One Endpoint per Major Version One Endpoint per Version

Service Versioning

WSDL Version 1.0

Service Versioning

WSDL 1.1
Agenda

Principles of Service Design

Service Design

Service Model and Implementation

Service Versioning

Summary
Summary

Standardized Service Contract => use contract-first

design => wrap contract-last services

Service Categories
Make sure to categorize your services

Implement minimal Service Governance
Service Versioning
SLA Management and Monitoring
My other sessions @ Kscope11

Reusing Existing Java EE Applications

from Oracle SOA Suite 11g, Tuesday 1:45
2:45 Room 203C

Fault Handling in Oracle SOA Suite 11g,
Wednesday 8:30 9:30 Room 203C
Best Practices for Designing and
Building the Services of an SOA
Please Fill Out Your Evaluations

Guido Schmutz
Technology Manager, Oracle ACE
Director for FMW & SOA
Trivadis AG, Switzerland
Feedback-URL: http://ezsession.com/kscope