Java Web Services Guidev1.0

Java Web Service Design and Development Guide

| technical document

New Zealand Java Centre of Expertise eds.com

>>

EDS INTERNAL DOCUMENT

Table of Contents

Document Control....................................................................................................4Amendment Record........................................................................................................................ 4Outstanding Issues......................................................................................................................... 4References..................................................................................................................................... 5

1 Introduction.................................................................................................61.1 Background........................................................................................................................... 61.2 Scope.................................................................................................................................... 61.3 Objectives............................................................................................................................. 81.4 Guide Usage......................................................................................................................... 81.5 Target Audience....................................................................................................................91.6 Benefits................................................................................................................................. 91.7 Document Updates and Maintenance...................................................................................9

2 Server Products........................................................................................102.1 Overview............................................................................................................................. 102.2 Sun Java System Access Manager 7.1...............................................................................102.3 Identity Manager................................................................................................................. 112.4 Sun Policy Agent 2.2...........................................................................................................112.5 Oracle Application Server...................................................................................................122.6 Compatibility Matrix.............................................................................................................12

3 Architecture...............................................................................................133.1 Use Case Perspective.........................................................................................................133.2 Logical Overview................................................................................................................. 133.3 Typical Request Flow..........................................................................................................15

3.3.1 Basic User Session..............................................................................................153.3.2 User Authentication..............................................................................................16

Development Tools................................................................................................183.4 JDeveloper.......................................................................................................................... 183.5 Together Architect...............................................................................................................193.6 XML Spy............................................................................................................................. 19

4 Service Oriented Architecture (SOA) and Web Services.......................20

5 Web Service Standards............................................................................23

6 Frameworks...............................................................................................276.1 Spring.................................................................................................................................. 276.2 RCF..................................................................................................................................... 276.3 Axis..................................................................................................................................... 276.4 Castor................................................................................................................................. 286.5 Web Services Invocation Framework (WSIF)....................................................................28

7 Development Process...............................................................................297.1 Web Service Development Approach.................................................................................29

7.1.1 Bottom-up Pattern................................................................................................297.1.2 Top Down Pattern.................................................................................................30

EDS and the EDS logo are registered trademarks of Electronic Data Systems Corporation. © 2005 EDS. All rights reserved. 07/2005


of 54

7.2 Business Processing Execution Language for Web Services.............................................307.3 (BPMN) Business Processing Modeling Notation...............................................................307.4 Model driven approach for development.............................................................................317.5 Mocking and Unit Testing Web Services.............................................................................31

8 Design Considerations.............................................................................328.1 Overview............................................................................................................................. 328.2 Key Resources....................................................................................................................348.3 End Point Design................................................................................................................34

8.3.1 References...........................................................................................................348.3.2 End Point Implementation....................................................................................348.3.3 Interface Granularity, Composition and Reuse....................................................358.3.4 Asynchronous vs. Synchronous...........................................................................358.3.5 Stateless vs. Stateful............................................................................................368.3.6 RPC vs. Literal.....................................................................................................368.3.7 Message Header vs. Payload..............................................................................398.3.8 XML Schemas......................................................................................................40

8.4 Security............................................................................................................................... 418.4.1 References...........................................................................................................418.4.2 Approaches to Security........................................................................................418.4.3 Key Guidance......................................................................................................418.4.4 Transport versus Message Level Security...........................................................428.4.5 Transport Level Security......................................................................................428.4.6 Message Level Security.......................................................................................43

8.5 Performance and Scalability...............................................................................................458.5.1 References...........................................................................................................458.5.2 Guidance..............................................................................................................45

8.6 Interoperability....................................................................................................................468.6.1 References...........................................................................................................468.6.2 Overview..............................................................................................................478.6.3 Testing.................................................................................................................478.6.4 Top Tips...............................................................................................................47

8.7 Reliability............................................................................................................................. 488.7.1 References...........................................................................................................488.7.2 Overview..............................................................................................................48

9 Design Issues in Implementing Target Use Case...................................509.1 Design................................................................................................................................. 509.2 Development Approach.......................................................................................................50

10 Bibliography................................................................................................51

of 52

EDS and the EDS logo are registered trademarks of Electronic Data Systems Corporation. © 2007EDS. All rights reserved. 07/2005


Document Control

Amendment RecordVersion Date Change Author

1.0a 30 Jan 2007 Created Saba Kanagasabapathy1.0b 13 Feb 2007 Reviewed Comments from Tom Pesendorfer Saba Kanagasabapathy1.0c 14 Feb 2007 Reviewed Comments from Vijay Seetharaman Saba Kanagasabapathy1.0d 19 Mar 2007 Restructure of document contents and format Navindra Herath1.0e 20 Mar 2007 Update structure and bullet points indicating

likely section contents addedPete Raymond

1.0f 30 Mar 2007 Major rework of content and structure. Removed sections which had no or insufficient content.

Pete Raymond

1.0g 16 April Added design section, made minor modifications to others, updated outstanding issues.

This version was used to discuss the contents with the Global Java Forum Members on the 18 April 2007

Pete Raymond

1.0h 18 April Updated design section and completed XML Processing guidance

Pete Raymond

1.0i 20 April Restructured last 2 sections. Slight modifications to scope and tools description following comments.

Pete Raymond

1.0j 13 May Included comments on the asset vetting process

Vijay Seetharaman

Outstanding Issues# Issue Expected Resolution

1. The depth of coverage is variable with the treatment of many of the topics in variable and lacks depths and authority in some areas.

Update with more real world experience following wider review

2. Need to investigate RCF support for web services. Update following review by RCF team member.

3. Need to give clearer guidance on the split of issues encountered when undertaking web service design and implementation using open source tools and those encountered using SOA focused tools such as Oracle BPEL designer or Sun Java Composite Application Platform Suite.

None identified.

4. Would benefit from a section on version control. Not sure if this is part of service management (i.e. a section not present) or develop approach.

Assess following wider review.

5. Need a better, more consistent approach to references. Currently have some in the reference section, some as genuine hyperlinks (i.e. can’t see the URL) and some as http://... Style text.

Seek guidance on this at review.

6. Should this document cover REST? Seek guidance on this at review.

7. Needs to have a section which highlights the relevant design decisions in implementing a system to satisfy the requirements outlined in section 3.

Seek guidance on this at review to gauge support.

of 52



References# Description Author Version / Date

1 Your Strategy For Web Services Specifications

Randy Heffner, Forrester December 14, 2006

2 SOA-enabling standards: an overview Claire Rogers and Veena Subrahmanyam

June 2006

3 EDS Impact Assessment – Web Services Security for External Organizations

Christopher Chan v1.0b, 18 Jan 2007

of 52



1 Introduction

1.1 BackgroundIn late 2006 the New Zealand Java Centre of Expertise (JCoE) had team members waiting for a project to ramp up. In support of their personal development and the capability enhancement of the group a small team was formed to investigate and determine best practice for the design and implementation of web services. The initiative progressed with a number of JCoE members contributing, then in early 2007 the opportunity to share the effort invested was recognized by the Global Java Capability Lead Technologist and a small amount of funding allocated to pull together work to date and produce a best practice guide.

The focus on the effort shifted away from web service technologies in general and firmly focused on the Tech Policy standards, A3 Agile Architecture Offering and Alliance Partner products.

1.2 ScopeIn producing web service guidelines one of the challenges is to determine a cohesive but deliverable scope. Much of the information required in any implementation is available to architects and developers, however, often the time required to locate quality information is significant. Conversely, reinventing the wheel is never a productive approach. Balancing these two drivers has been the goal of the authors of this best practice. The scope is therefore to identify the key decisions in designing and implementing systems using the A3 stack of:

Oracle Application Server 10g (10.1.3)

Sun Access Manager 7.1

Sun Policy Agent 2.2

However, where there are other company standards such as the Reusable Component Framework (RCF) and industry wide defacto standards such as Spring they are also covered. In general we will focus on links to EDS produced and hosted material, Alliance Partners and publicly available information in that order.

One of the challenges in assembling web services guidance is the breadth of information available. Web services are ubiquitous and a huge effort is being invested by vendors in defining and implementing standards and bringing services and products to market in support of Service Oriented Architectures (SOA). Yet to many Java developers SOA is abstract, untouchable, focused on governance, strategy and business process. This Java Web Services Best Practices document for is focused on the design and implementation of web services for developers wanting to understand how to be productive quickly on projects, wanting to know which XML parser will be quickest, which tools should I use to define a web service interface and how shall I turn it into running java code. That’s not deny the need to set web services in the context of the SOA tidal wave, however, discussion of how to align your business units to deliver on your SOA strategy we’ll leave to others.

So what phases of the software development lifecycle guide target? Some would argue that web services has a lifecycle distinct from other development technologies and this may be true in terms of design and code phases, however, the basic phases of inception, elaboration, construction and transition are still relevant and this guide focuses on elaboration and construction. Specifically it focuses on design, development and unit testing. For production monitoring, web services are normally deployed in application servers which come monitoring tools for performance, capacity and throughput. To this new monitoring tools are now available. Oracle provides Business Activity

of 52



Monitor (see SOA World Product Review) and introduced in J2EE 1.4 was J2EE Management, JSR 77. J2EE Management provides a standard management model for exposing and accessing management information, operations, and attributes for J2EE components. JDeveloper 10g Release 3 (10.1.3.0) started supporting JSR 77 and Oracle Application Server 10.1.3 also support the management interface

There are many other areas that are important and valuable to cover but are also excluded. There is a large product set focused on Enterprise Application Integration (EAI). EAI is a process whereby silos of information are linked, this can be achieved at a process, application or date level. There is a rich diversity of tools supporting the mapping, transformations and distribution of data necessary for the integration. WebSphere Business Integration Server, Sun ONE Integration Server or the Tech Policy standard of Tibco BusinessWorks.

Figure 1 – Technology Policy

There are a number of areas of software development which are affected by the use of web services and more importantly are facilitated by it. Web Services have finally enabled the sharing of data over heterogeneous environments, one of the holy grails of computing. It has succeeded where CORBA and RMI/IIOP have large failed, ubiquity. With this opportunity comes a different set of questions; how do I work with a 3rd party who is providing a web service interface for which I need to consume data, who should generate the interface, how will I develop my client if I don’t have access to a running web service, how should I specify web services as a system level use cases? These and many questions on the process of developing web services will be answered in the section on the Web Service Development Process. This section will touch on the use of code generation and other process oriented questions, however, they will not be explored in detail.

Lastly a set of product features have been brought to market to support the persistence of XML. These are often used in systems using web services, but not always. When XML use became widespread the major vendors proposed storage via standard RDBMS mechanisms. In the case of Oracle this was CLOB or VARCHAR2. Smaller vendors pushed the market forward providing more

of 52



http://www.tibco.com/software/application_integration/businessworks/

http://www.sun.com/software/products/integration_srvr_eai/home_int_eai.xml

http://www-306.ibm.com/software/info1/websphere/index.jsp?tab=solutions/appintegration&S_TACT=105AD02W&S_CMP=campaign

http://www.oracle.com/technology/tech/java/oc4j/10131/OracleAS-NF-10131.pdf

http://www.oracle.com/technology/products/jdev/collateral/papers/10131/newfeatures/index.html

http://jcp.org/en/jsr/detail?id=77

http://webservices.sys-con.com/read/275121.htm

than just a store based on a large string and Oracle and others introduced various approaches to parsing and mapping the XML to relational tables. Oracle’s XML SQL Utility for Java is one and more recently included in Oracle 10g is DBMS_XMLSTORE (See XML to Relational: Bridging the Gap). Hibernate 3 utilizes the dom4j framework for XML parsing and manipulation and store XML to any of its supported vendor databases, however, it is not Hibernate’s core strength.

In summary the main focus of these best practices is to provide practical guidance on designing and implementing web services using Java by presenting references to or summaries of all the key information.

1.3 ObjectivesThe objectives of this guide are to:

Support developers designing and implementing web services using Java

Build collateral for EDS Alliance Partner products

Provide and highlight the existence of reusable assets

Reference out to other material rather than reinvent the wheel

1.4 Guide UsageThis guide is structured primarily as a reference source although reading the introduction will place the guidance in context. Users should be able to refer to specific sections in isolation if you have a particular interest, however, we hope that you’ll find this entire guide useful and encourage you to provide comments and additions.

At the time of writing (March 2007) there are a number of other related initiatives ongoing in the company and some must see information sources. The key ones readers of this guide should be aware of are:

Service Oriented Architectures (SOA) Community https://knowledgecentre.eds.com/sites/kc0155/default.aspx

EDS Technology Strategy & Architecture Identity and Access Management https://knowledgecentre.eds.com/sites/kc16/TechnologyDirectives/Identity%20and%20Access

%20Management.doc

EDS Tech Policyhttp://techpolicy.iweb.eds.com/default.aspx

In using this guide as part of the software development process we suggest:

referencing it as part of technology selections during architecture and design

using to support the implementation teams to guide coding

leveraging it as criteria for reviews

We would also encourage you to review and add to its contents via the process described in the Document Maintenance and Updates section.

of 52



http://techpolicy.iweb.eds.com/default.aspx

https://knowledgecentre.eds.com/sites/kc16/TechnologyDirectives/Identity%20and%20Access%20Management.doc


https://knowledgecentre.eds.com/sites/kc0155/default.aspx

http://www.oracle.com/technology/oramag/oracle/05-sep/o55xml.html

http://download-east.oracle.com/docs/cd/B10501_01/appdev.920/a96616/arxml08.htm

Lastly any guidance document should always have a disclaimer, let’s call it the prime directive. If you choose not to comply with a standard then you should understand why and if it is a significant non-compliance document the reason. No standard can be written to completely cover all scenarios; each developer must apply their judgment in applying the standard to produce the most appropriate design or code possible.

1.5 Target AudienceThis isn’t a beginner’s guide, it assumes you either have understood the basics of web services and Java or are prepared to read around to make sense of the guidance. It’s also targeted at those wishing to focus on EDS standards and alliance partner tools.

There are a number of links to information from research and analysis companies which is only available to EDS employees. You can access this information by following the instructions at http://infocentre.eds.com/workplace/research/tools/vendors/index.html.

1.6 BenefitsThe benefits expected from usage of this guide are:

reduced time spent on design and development resulting in reduced costs, higher quality, greater business agility and faster time to market.

promotion of EDS standards and alliance partner tools

reduced time spent researching and experimenting on the best approaches for web services

1.7 Document Updates and MaintenanceThis document will follow the Global Java Forum’s (GJF) Asset Vetting Process. There are two key processes that every asset endorsed by the GJF is put through. The “Endorse Asset” and “Revise Asset” processes. The “Endorse Asset” process describes the process of vetting the asset, while the “Revise Asset” process governs how the asset is updated and maintained over a period of time.

of 52



https://knowledgecentre.eds.com/sites/kc44/Shared%20Documents/GJF%20Asset%20Vetting%20Process.doc

http://infocentre.eds.com/workplace/research/tools/vendors/index.html

2 Server Products

2.1 OverviewShown below is Sun identity management products, Sun also provides a useful summary of its solutions at http://www.sun.com/software/media/flash/demo_identity/netid.html?intcmp=27 included in the Identity Management resource centre at http://www.sun.com/software/products/identity/index.jsp . The Burton Group identifies identity management as “Identity management is the set of business processes, and a supporting infrastructure, for the creation, maintenance, and use of digital identities.”

Figure 2 – Overview of Sun Identity Manager Products (Source SunMicrosoft_NetTalk.pdf)

Product Role

Directory Server store identity data, includes fail over and replication

Access Manager centralized access control, single sign on

Identity Auditor verification, auditing, reporting, compliance

Identity Manager Provisioning, de-provisioning, updating

Federation Manager extranet Single Sign-on, trusted domain management, SAML assertion exchange

Below is some further clarification of the core products included in the architecture where we think some confusion may occur. The Directory Server is a reasonably straightforward concept, it is a database of identity information typically accessed via the Lightweight Directory Access Protocol (LDAP). Identity Auditor, Federation Manager and Identify Manager SPE is not referenced and excluded from the scope. This leaves Access Manager and Identity Manager which would be core to any solution.

2.2 Sun Java System Access Manager 7.1 From the sun site http://www.sun.com/software/products/access_mgr/faq.xml

Q: What is Sun Java Access Manager? (Formerly Identity Server.)

A: Sun Java System Access Manager helps organizations manage secure access to an enterprise's web applications both within the enterprise and across business-to-business value chains. It is an

of 52



http://www.sun.com/software/products/access_mgr/faq.xml

http://www.sun.com/software/products/identity/index.jsp

http://www.sun.com/software/media/flash/demo_identity/netid.html?intcmp=27

open, standards-based product that provides centralized authentication and policy-based authorization from a single, unified framework. Access Manager meets the current needs of the enterprise for secure protection of essential identity and application information and supports their future business needs through implementation of the latest identity federation standards for tighter integration with business partners. It improves user experience through single sign-on to all of an organization's web-based applications and creates revenue opportunities through deepened relationships with partners, suppliers, and customers.

Let see if we can distil this marketecture into implemented features:

cross domain sign on (CDSSO); this allows a user to authenticate once and access services in any security domain

authentication and authorization services; authentication checks who you are and authorization is what you are allowed to do.

audit

2.3 Identity ManagerSun provides a reference to a Gartner analysis of user Provisioning products at http://www.sun.com/software/products/identity/magic_quadrant_user_provisioning_1h06.pdf . The market definition of user provisioning that Gartner uses is as follows:

UP solutions address the enterprise’s need to administer (create, modify, disable and delete) the following identity objects across the heterogeneous IT system infrastructure environment (operating systems, databases, directories, business applications and security systems):

User IDs associated with each user

Authentication credentials – IT and facility

Roles (for example, enterprise-level and target system specific)

Entitlements (for example, assigned via roles or explicitly to the user ID at the target system level)

User profile attributes (such as name, address, phone number, title and department)

Corporate policies (for example, time-of-day restrictions, password management policies, business relationships that define users’ access to certain IT resources and segregation of duties

2.4 Sun Policy Agent 2.2The Sun Java System Access Manager Policy Agent 2.2 User's Guide http://192.18.109.11/819-2143/819-

2143.pdf is a good reference source. The policy agent comes into two forms: J2EE agents designed to work with J2EE application servers and Web Agents which integrate with web servers. The proposed product set is based on the integration with the Oracle Application Server so the relevant guide is the Sun Java System Access Manager Policy Agent 2.2 Guide for Oracle Application Server 10g at http://docs.sun.com/app/docs/doc/819-7171 which is an example of using a J2EE Agent. The policy agent works with the Access Manager which depends on Directory Server.

of 52



http://docs.sun.com/app/docs/doc/819-7171

http://192.18.109.11/819-2143/819-2143.pdf

http://192.18.109.11/819-2143/819-2143.pdf

http://www.sun.com/software/products/identity/magic_quadrant_user_provisioning_1h06.pdf

2.5 Oracle Application ServerOracle Application Server is the EDS standard for Java Application Servers and supports enterprise applications, portals, and web services.

Reference: http://techpolicy.iweb.eds.com/ProductBrowser.aspx?PID=1359 for EDS Technology policy information.

2.6 Compatibility MatrixShown below are the applications dependencies for the chosen products, excluded are platform requirements.

Sun Java System Access Manager 7.1 compatibility list at http://docs.sun.com/app/docs/doc/819-

4683/6n6qn8567?a=view does not list Oracle.

Sun Policy Agent 2.2 which comes with SJS Access Mgr 7.1 http://docs.sun.com/app/docs/doc/819-

7171/6n94rvsnp?a=view is compatible.

of 52



Product Supported Application Dependencies

Directory Server 6.0 none

Access Manager 7.1 Directory Server 6.0, Supported web application container e.g. Sun Java Application Server 8.2

Policy Agent 2.2 Access Manager

Oracle none

http://docs.sun.com/app/docs/doc/819-7171/6n94rvsnp?a=view

http://docs.sun.com/app/docs/doc/819-7171/6n94rvsnp?a=view

http://docs.sun.com/app/docs/doc/819-4683/6n6qn8567?a=view

http://docs.sun.com/app/docs/doc/819-4683/6n6qn8567?a=view

http://techpolicy.iweb.eds.com/ProductBrowser.aspx?PID=1359

3 Architecture

3.1 Use Case PerspectiveThis guide is designed to support a use case commonly required in a system leveraging web services. A use case was selected to provide a focus for the guidance and limit the scope. The use case is a purchase where the flow requires the system to call other web services and maintain the security context supplied by the human actor.

User Case: User makes a purchase request

Figure 3 – Target Use Case

Goal / Context

The user wishes to make a purchase and provide identifying information and credit card details.

Basic Flow

1. The user submit a request to purchase an item

2. The system responds with a confirmation that the purchase has succeeded

Alternate Flow

These would be based around credit card details being rejected or other system failures and are not explored here.

Non Functional

1. The credentials of the user must be validated.

2. The request must be logged and be auditable.

3.2 Logical OverviewThe architecture described in this document is designed to address the use case described in the implementation scenario with EDS standard products. It is based on best of breed selections: Oracle for the application server and Sun products for the identity management. There are a number of

of 52



products which are omitted from the architecture which would normally be present in a real solution, they include a portal, directory information management and synchronization tools, and runtime management and monitoring support. The architecture is also purely logical and lacks the distribution of products and applications to physical or virtual infrastructure. This would be a very useful exercise and would take the logical view into the realms of reference architecture but is outside the scope. Typical allocations may include separate virtual machines or physical hosts for Oracle HTTP Server, Oracle Application Server, Sun Java Application Server hosting the Access Manager and the Directory Server.

There were some challenges to designing the proposed architecture. They include:

Sun’s propensity to rename and rebrand products, this makes products selections difficult without thorough knowledge of the product range.

Access Manager 7.1 is not supported in Oracle Application Server and therefore to host the Access Manager web application the solution includes provisioning of a supported container such as Sun Java Application Server. This means that even within a Java Enterprise solution two application servers are deployed. This may be considered undesirable from a licensing and support cost perspective.

Figure 4 – Overview Architecture

The architecture includes the following products:

Oracle Application Server 10g R3 (10.1.3.1)

Sun Access Manager 7.1

Sun Policy Agent 2.2

Sun Java Application Server 8.2

Directory Server 6.0

The architecture definition is based on brief research of vendor technical material and would of course require an architectural validation phase to reduce risk of implementation difficulties prior to

of 52



Policy Agent

Oracle Http Server / App Server

Sun Java System Application Server

Access Manager

Directory Server

any deployment. While some research was undertaken to support the basic product selections, documented known issues were not reviewed in detail. Limited consideration was also given to the platform operating system. While vendors such as Sun publish compatibility matrices including support for other vendors such as the deployment of Directory Server on Windows, they also provide recommended configurations which have had the greatest testing effort invested in them. Unsurprisingly these tend to provide the most painless route to production.

Application servers are now well understood in the market place and integrated into the enterprise java developer’s psyche. Little background is therefore required. However, the role of identity management software is rather different and therefore some background is warranted.

3.3 Typical Request Flow

3.3.1Basic User Session

The following diagram and flow description is taken from the SJAM 7.1 Technical Overview and describes the process behind a basic user session by tracing what happens when a user logs in to a resource protected by AccessManager. In these examples, the server which hosts an application is protected by an AccessManager policy agent. The Basic User Session includes the following steps.

Figure 5 – Creating a User Session (Source SJAM 7.1 Technical Overview)

When a user initiates a user session by using a browser to log in to a web-based application, the events in the following illustration occur. The accompanying text describes the process.

1. The user’s browser sends an HTTP request to the protected resource.

2. The policy agent inspects the user’s request and finds no session token.

of 52



3. The policy agent contacts the configured authentication URL. In this example, the authentication URL it is set to the URL of the Distributed Authentication User Interface Service.

4. The browser sends a GET request to the Distributed Authentication User Interface.

5. The Session Service creates a new session (session data structure) and generates a session token. The session token is a randomly-generated string that represents the user.

6. The Authentication Service sets the session token in a cookie.

Analyzing the request flow there does appear to be some ambiguity in the operation. For example it is not clear how in step 4 the browser send a GET request having received no response. Possibly a redirection response is returned to the browser indicating that a GET request is required.

3.3.2User Authentication

When the browser sends a GET request to the Distributed Authentication User Interface, the events in the following illustration occur. The accompanying text describes the process.

Figure 6 – User Authentication Flow (Source: Sun Access Manager Technical Overview)

1. Using the parameters in the GET request, the Distributed Authentication User Interface contacts the Authentication Service installed on the AccessManager server.

2. The Authentication Service determines the appropriate authentication module to use based upon AccessManager configuration and the request parameters passed by the Distributed Authentication User Interface using the Authentication client APIs. For example, if AccessManager is configured to use the LDAP Authentication type of module, the Authentication Service determines that the LDAP Authentication login page will be used.

of 52



3. The Authentication Service determines which presentation callbacks should be presented, and sends to the Distributed Authentication User Interface all necessary credentials, requirements, and callbacks for use by the presentation framework layer.

4. The ClientDetection Service determines which protocol, such as HTML or WML, to use to display the login page.

5. The Distributed Authentication User Interface returns to the Web browser a dynamic presentation extraction page along with the session cookie. The presentation extraction page contains the appropriate credentials request and callbacks info obtained from the AccessManager server.

6. The user’s browser displays the login page. The user enters information in the Username and Password fields of the login page.

7. The browser replies to the Distributed Authentication User Interface with a POST that contains the required credentials.

8. The Distributed Authentication User Interface uses the Authentication client APIs to pass credentials to the AccessManager server.

9. The Authentication Service uses the appropriate authentication module type to validate the user’s credentials. For example, if the LDAP authentication module type is used, the Authentication Service verifies that the username and password provided exist in the LDAP directory. Other authentication module types have different requirements.

10. Assuming authentication is successful, the Authentication Service activates the session by calling the appropriate methods in the Session Service. The Authentication Service stores information such as Login time, Authentication Scheme, and Authentication Level in the session data structure.

11. Once the session is activated, the Session Service changes the state of the session token to valid.

12. The Distributed Authentication User Interface replies to the protected resource with an SSOToken in a set-cookie header.

13. Now, the browser makes another request to the original resource protected by a policy agent. This time, the request includes a valid session token, created during the authentication process.

of 52



Development ToolsThe following listed tools have been identified as standard selections for web service development, see the EDS Tech policy for more information.

3.4 JDeveloper JDeveloper is the standard Tech Policy tool for Java development (see http://techpolicy.iweb.eds.com/CategoryBrowser.aspx?CGID=810 ) and supports all major J2EE application servers and databases. JDeveloper generally uses less resources compared Borland Together Architect (TA), however TA provides more comprehensive Java modeling capability. JDeveloper does however provide features such as a WSDL editor and the BPEL Process Manager as below:

http://www.oracle.com/technology/products/jdev/collateral/papers/1013/jdev1013_overview.pdf )

Figure 7 – JDeveloper WSDL Editor

Figure 8 – JDeveloper BPEL Process Manager

of 52



http://www.oracle.com/technology/products/jdev/collateral/papers/1013/jdev1013_overview.pdf

http://techpolicy.iweb.eds.com/CategoryBrowser.aspx?CGID=810

3.5 Together ArchitectBorland Together Architect is the EDS standard for Java based analysis, UML modeling, and design and provides comprehensive support for round tripping between code and models. The tool can be demanding on desktop resources and code focused developers are unlikely to use many of the facilities provided by this tool. However, it does use the Eclipse framework, which is the most widely used IDE within EDS, the wider Java community and provides access to a large and thriving market of open source and vendor plug-ins.

Reference: http://techpolicy.iweb.eds.com/ProductBrowser.aspx?PID=315 for EDS Technology policy information.

3.6 XML SpyAltova XML Spy is one of the best XML authoring and manipulating tools on the market. Light weight easy to use and fully featured. It supports XML message, schema and XSL editing, validation and debugging. It’s available as a stand alone application or as an Eclipse plug-in. The ~ $500 USD cost can be challenging to justify for many users though.

Reference: http://techpolicy.iweb.eds.com/ProductBrowser.aspx?PID=198 for EDS Tech policy information.

of 52





4 Service Oriented Architecture (SOA) and Web Services

So much has been written about Service Oriented Architecture (SOA) that it can be difficult to know where to start the SOA journey. This is as much the case for businesses wishing to obtain the benefits of SOA as it is for architects and developers wishing to sell and develop them. This section will not seek to summarize or analyze the SOA approach, merely to try and place web services in context. To start with a definition is usually informative and the Open Group provides a candidate at http://www.opengroup.org/projects/soa/doc.tpl?gdid=10632

Service-Oriented Architecture (SOA) is an architectural style that supports service orientation. Service orientation is a way of thinking in terms of services and service-based development and the outcomes of services.

A service:

Is a logical representation of a repeatable business activity that has a specified outcome (e.g., check customer credit; provide weather data, consolidate drilling reports)

Is self-contained

May be composed of other services

Is a “black box” to consumers of the service

An architectural style is the combination of distinctive features in which architecture is performed or expressed.

The slide below from Gartner summarizes this mindset:

Figure 9 – Service Oriented Development Styles (Source Gartner)

The OASIS group poses the question What is Service Oriented Architecture? In http://www.oasis-

open.org/committees/download.php/18487/wd-soa-rm-pr2.doc and answers it thus:

Service Oriented Architecture (SOA) is a paradigm for organizing and utilizing distributed capabilities that may be under the control of different ownership domains. Gartner claims to have first coined the phrase in http://www.gartner.com/resources/114300/114358/114358.pdf .

of 52



http://www.gartner.com/resources/114300/114358/114358.pdf

http://www.oasis-open.org/committees/download.php/18487/wd-soa-rm-pr2.doc

http://www.oasis-open.org/committees/download.php/18487/wd-soa-rm-pr2.doc

http://www.opengroup.org/projects/soa/doc.tpl?gdid=10632

However, while all encompassing these types of definitions are often too abstract. Let us focus on some commonly accepted core principles:

1. Contract-Driven

2. Loosely Coupled

3. Encapsulation

4. Reusable / Composable

5. Autonomous

6. Stateless

7. Discoverable

You’ll notice that there is still no mention of web services, so let’s turn to a technology company rather than a standards body for some more detail. Sun has useful material at http://java.sun.com/developer/technicalArticles/WebServices/soa/index.html and in discussing interoperability notes that:

Web services are software systems designed to support interoperable machine-to-machine interaction over a network. This interoperability is gained through a set of XML-based open standards, such as WSDL, SOAP, and UDDI. These standards provide a common approach for defining, publishing, and using web services.

So web services are one of a number of the underpinning technologies used to deliver SOA, albeit the important facility to define, discover and use services. Randy Heffner of Forrester has recently provided a series of articles summarizing web services standards (see Ref 1 and http://www.forrester.com/go?docid=40881 for an example) which provides a useful summary:

SOA is about structure for flexibility. SOA provides core design concepts to construct applications for business flexibility and application flexibility.

Web services is about ecosystems. Web services provide standard industry protocols for connecting between applications, which opens broad ecosystems for connecting to customers and suppliers, integrating tools and infrastructure from multiple IT vendors, hiring people with technical skills (whether employees or consultants), and more.

of 52



http://www.forrester.com/go?docid=40881

http://java.sun.com/developer/technicalArticles/WebServices/soa/index.html

Figure 10 – Web Services Specifications Are Evolving To Provide Standards-Based SOA (Source Forrester Research, Inc)

We’ve covered SOA and Web Service relationships in terms of evolution and design versus implementation. Let’s put pull this together into a diagram which shows the roles of various standards and architectural layers. HP has the perfect summary of SOA and web service standards at http://devresource.hp.com/drc/technical_white_papers/soa_stds/index.jsp#wspolicy which includes the diagram below:

Figure 11 Web Service Architecture (Source HP Ref 2)

EDS has good collateral on SOA, its value and recent implementations. We suggest starting at http://www.applicationsdelivery.eds.com/nlapps/data/docattachments/SOA In Action.ppt but also referencing the A3 site at http://infocentre.eds.com/who/work/a3/ .

Finally in the context of SOA is the all conquering Enterprise Service Bus (ESB). ESBs are one of the underpinning technologies used to deliver SOAs. Wikipedia provides a nice summary An ESB generally provides an abstraction layer on top of an implementation of an enterprise messaging system which allows integration architects to exploit the value of messaging without writing code. Contrary to the more classical enterprise application integration (EAI) approach of a monolithic stack in a hub and spoke architecture, the foundation of an enterprise service bus is built of base functions broken up into their constituent parts, with distributed deployment where needed, working in harmony as necessary.

In summary web services enables effective delivery of SOA. There are a number of concepts and technologies such at the Enterprise Service Bus, BPM, and service orchestration and choreography which, while interesting to bring into the picture, would lead us inexorably into a review of SOA and out of our scope.

of 52



http://en.wikipedia.org/wiki/Enterprise_service_bus

http://infocentre.eds.com/who/work/a3/

http://www.applicationsdelivery.eds.com/nlapps/data/docattachments/SOA%20In%20Action.ppt

http://devresource.hp.com/drc/technical_white_papers/soa_stds/index.jsp#wspolicy

5 Web Service Standards A web service comprise of five basic service elements; namely

Component Description

Service a deployed and accessible business process or application function

Service registry a place where you can find information about available service

Service client a client that accesses a service

Transport protocol for example HTTP or HTTPS

XML-based messages the messages between client and the service

The key standards are listed below.

Standard Name Description

SOAP (Simple Object Access Protocol) Specification

Version 1.1, specified by W3C specification.

Refer http://www.w3.org/TR/soap/ in W3C notes.

WSDL (Web Services Definition Language) Specification

Version 1.1, specified by W3C specifications.

Refer http://www.w3.org/TR/wsdl in W3c notes.

UDDI (Universal Description, Discovery, and Integration) Registry

Version 2.2, specified by UDDI.org, association with OASIS

Refer http://uddi.org/pubs/uddi-v3.0.2-20041019.htm for the latest version

WS-I (Web Services Interoperability) Basic Profile

Version 1.0a, which consists of

SOAP Ver 1.1 (over HTTP 1.1),

WSDL Ver 1.1

UDDI Ver 2.2

XML Schema 1.0

Refer http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html for more details.

Web Service Security

WS-Security

User Name Token profile

SAML Token profile

This specification describes enhancements to SOAP messaging to provide authentication, message integrity and confidentiality. This mechanism can be used to accommodate wide variety of secure models and encryption technologies.

of 52



http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html

http://uddi.org/pubs/uddi-v3.0.2-20041019.htm

http://www.w3.org/TR/wsdl

http://www.w3.org/TR/soap/


X.509 Token profile

Kerberos Token Profile

SOAP with Attachment Profile

http://www.oasis-open.org/specs/index.php#wssv1.1

Web Services Trust language

WS-Trust

WS-Trust is an extension to WS-Security specification and defines

Methods for issuing, renewing, and validating security tokens.

Ways to establish, assess the presence of, and broker trust relationships.

http://msdn2.microsoft.com/en-us/library/ms951260.aspx#ws-

trust__toc72863343

Web Services Policy Framework

WS-Policy

WS-Policy provides a flexible and extensible grammar for expressing the capabilities, requirements, and general characteristics of entities in an XML Web Services-based system. WS-Policy defines a framework and a model for the expression of these properties as policies. Policy expressions allow for both simple declarative assertions as well as more sophisticated conditional assertions.

http://msdn2.microsoft.com/en-us/library/ms951240.aspx

Web Services Addressing

WS-Addressing

Web Services Addressing (WS-Addressing) defines two interoperable constructs that convey information that is typically provided by transport protocols and messaging systems. These constructs normalize this underlying information into a uniform format that can be processed independently of transport or application. The two constructs are endpoint references and message information headers.

http://www.w3.org/Submission/ws-addressing/#_Toc77464314

Web Services Distributed Management: Management Using Web Services (MUWS)

This specification defines a standard for management of distributed information technology (IT) resources using Web services. Many distributed IT resources use different management interfaces. By leveraging Web service technology, MUWS enables easier and more efficient management of IT resources. This is accomplished by providing a flexible, common framework for manageability interfaces that leverage key features of Web services protocols. Universal management and interoperability across the many and various types of distributed IT resources can be achieved using MUWS

http://docs.oasis-open.org/wsdm/wsdm-muws1-1.1-spec-os-

01.htm#_Toc129090796

of 52



http://docs.oasis-open.org/wsdm/wsdm-muws1-1.1-spec-os-01.htm#_Toc129090796

http://docs.oasis-open.org/wsdm/wsdm-muws1-1.1-spec-os-01.htm#_Toc129090796

http://www.w3.org/Submission/ws-addressing/#_Toc77464314

http://msdn2.microsoft.com/en-us/library/ms951240.aspx

http://msdn2.microsoft.com/en-us/library/ms951260.aspx#ws-trust__toc72863343

http://msdn2.microsoft.com/en-us/library/ms951260.aspx#ws-trust__toc72863343

http://www.oasis-open.org/specs/index.php#wssv1.1


Web Service Transaction

WS-Coordination

WS-Atomic Transaction

WS-Business Activity

The purpose of the specification is to define as set of protocol to coordinate the outcome of distributed application activity in terms of distributed transaction.

http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ws-tx

Web Service Remote Portlet (WSRP)

WSRP defines a set of interfaces and related semantics which standardize interactions with components providing user-facing mark-up, including the processing of user interactions with that mark-up. This allows applications to consume such components as providing a portion of the overall user application without having to write unique code for interacting with each component

http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp

Table 4

The JSR-921 and JSR-181 describes and sets the standards for Enterprise Web Services and the Web Service Meta data.

Shown below are the primary J2EE 1.4 and Web services standards Oracle Application Server 10g R3 supports.

Standard Version

JavaServer Pages (JSP) 2.0

Servlets 2.4

Java Server Faces 1.1

Enterprise JavaBeans (EJB) 3.0

Java Management Extensions (JMX) 1.2

JMX Remote Access API JSR-160

J2EE Management 1.0 (JSR-77)

J2EE Application Deployment 1.1 (JSR-88)

Java Transaction API (JTA) 1.0

Java Message Service (JMS) 1.1

Java Naming and Directory Interface 1.2

Java Mail 1.2

of 52



http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp

http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ws-tx

Standard Version

Java Database Connectivity (JDBC) 3.0

Java Authentication & Authorization Service

1.0

J2EE Connector Architecture 1.5

Enterprise Web Services 1.1 (JSR-921)

Web Services Metadata 1.0 (JSR-181)

Java API for XML-Based RPC (JAX-RPC) 1.1

SOAP with Attachments API for Java (SAAJ)

1.2

Java API for XML Processing (JAXP) 1.2

Java API for XML Registries (JAXR) 1.0.5

Java API for Rules Engines JSR-94

Common Annotations for the Java Platform

JSR-250

Many of these versions have been superseded in the recently released JEE 5 release. For example JAXP 1.4.1 was released on Mar. 20, 2007.

of 52



6 Frameworks

6.1 SpringSpring is an open source Java Enterprise application framework based on the principle of Inversion of Control. Reference: http://techpolicy.iweb.eds.com/ProductBrowser.aspx?PID=1333 for EDS Tech policy information. Spring has support for JAX-RPC web services via remoting (http://www.springframework.org/docs/reference/remoting.html), more recently has been expanded to incorporate a specific framework (http://static.springframework.org/spring-ws/docs/1.0-m1/reference/pdf/

spring-ws-core-reference.pdf) and also provides integration with Axis 2 (http://ws.apache.org/axis2/1_1_1/spring.html). It is widely used, well supported by all major vendors (e.g. http://www.oracle.com/technology/tech/java/spring.html, http://e-docs.bea.com/platform/suppconfigs/configs/spring/index.html) well documented and greatly simplifies most aspects of Java enterprise development.

6.2 RCFThe RCF is the standard EDS offering for web based development. Refer to the white paper describing the Web Services implementation using EDS Reusable Component Framework (RCF).

https://knowledgecentre.eds.com/sites/kc99/Technical/White Papers/RCF JEE Compatibility Guide.pdf and https://knowledgecentre.eds.com/sites/kc99/default.aspx to access the high quality documentation for this framework which is layered on top of Apache Struts.

6.3 AxisApache Axis has been the most successful open source web services implementation framework over the last three years. Apache Axis has gone through some re-design in recent times and a new version named Axis 2 has been released. The programming model for Axis 2 is quite different to that of its predecessor and many "lessons learnt" from the previous version have been incorporated into it. Axis gained its current stable state over a long period of time. It will take time until Axis 2 enjoys the same stability. Both Axis 2 and Axis will co-exist in development and the complete migration might take some time.

Advantages:

The framework is more XML oriented and has the plug-in architecture for various WSDL styles, i.e. rpc or document style bindings. It is aligned more towards document based Web Service thus provides much wider interoperability among Web Services.

The framework supports the Message Exchange Pattern and as a result has built-in support for synchronous/asynchronous implementation of Web Services. (i.e. you could configure a Web service as synchronous - request/response - or asynchronous - fire and forget - very easily).

Uses relatively new AXIOM based data binding (Axis Data Binding - ADB Framework and Schema Compiler); also provide an ability to plug-in other data binding framework such as JAXB. The ADB framework uses the fast StAX API to marshal/un-marshal XML data.

Can be deployed to any Servlet container and provides in-built tools to deploy services. The deploy tool is part of the Axis runtime engine.

Writing a Web Service is very easy. All you need to do is implement the services as POJOs and produce a service deployment descriptor XML file.

of 52




https://knowledgecentre.eds.com/sites/kc99/Technical/White%20Papers/RCF%20JEE%20Compatibility%20Guide.pdf

http://www.oracle.com/technology/tech/java/spring.html

http://ws.apache.org/axis2/1_1_1/spring.html

http://static.springframework.org/spring-ws/docs/1.0-m1/reference/pdf/spring-ws-core-reference.pdf

http://static.springframework.org/spring-ws/docs/1.0-m1/reference/pdf/spring-ws-core-reference.pdf

http://www.springframework.org/docs/reference/remoting.html


Provides REST support.

Disadvantages:

Does not implement any of the Sun standards such as JAX-RPC, SAAJ, but has the ability to build layers to support these on top of the Axis engine.

Does not use JAXB for data binding; instead uses relatively new, yet un-proven frameworks/standards.

Not much documentation available.


6.4 CastorCaster is an open source XML to Java Object binding tool. The mapping information is maintained in a separate XML file. Using Caster provides very straight forward marshalling and unmarshalling operations.


6.5 Web Services Invocation Framework (WSIF)The Web Services Invocation Framework (WSIF) is a simple Java API for invoking Web Services. This framework provide facilities for invoking web services irrespective of the underlying services protocol.

Reference: http://ws.apache.org/wsif/ for more details about WSIF framework. EDS Tech policy has no entry for the Apache WSIF framework.

of 52



http://ws.apache.org/wsif/



7 Development Process

7.1 Web Service Development ApproachThere are two common implementation patterns available for Web Service implementations.

1. Bottom-up Pattern: Start with Java interface to produce WSDL.

2. Top-down Pattern: Start with WSDL to produce implementation as Java classes.

However see http://www-128.ibm.com/developerworks/architecture/library/ar-servdsgn1/index.html?ca=drs-

tp1207 for a discussion of “meet in the middle” and http://devresource.hp.com/drc/resources/WSLifecycle/index.jsp for a wider discussion of web service development lifecycle.

7.1.1Bottom-up Pattern

Advantages:

Provides a quick way to expose legacy implementations as web services.

Requires little or no knowledge of WSDL or XML because the WSDL document is generated by IDEs such as NetBeans and JDeveloper and the Java2WSDL utility.

Excellent tool support. (e.g. NetBeans IDE, JDeveloper IDE)

Disadvantages:

The generated schema defining the data types in the WSDL document derives only from the Java classes from the provider's environment and not from any standards-based schema. This may introduce interoperability issues.

The generated schema is embedded in the WSDL, which makes reuse of the schema more difficult. (It is possible, of course, to extract the schema from the original WSDL document).

The development of the server-side web service implementation and the client-side Web service requester cannot proceed in parallel. The server-side skeleton and data transfer objects have to be developed before a WSDL can be generated that can be used to generate the client-side stubs.

Incremental changes to the interface are more difficult to manage. For example, if the interface of the class that implements the service is changed and the WSDL is regenerated, more significant changes could occur in the WSDL, thus causing interoperability with existing clients to fail. The basic problem is that, on the server-side, the class implementing the service is deemed the master interface and, on the client-side, the WSDL provided by the server-side is the master interface. These two different masters can cause the interfaces to become out of sync and difficult to debug and fix.

The namespaces of the embedded schema types are typically generated from the Java package names of the server-side JavaBeans. Therefore, if the package names are changed, the namespace will be changed, which means the types are no longer compatible. Most of the tools allow a package to namespace mapping, but this must be explicitly set during the execution of the tool.

of 52



http://devresource.hp.com/drc/resources/WSLifecycle/index.jsp

http://www-128.ibm.com/developerworks/architecture/library/ar-servdsgn1/index.html?ca=drs-tp1207


7.1.2Top Down Pattern

Advantages:

Supports the use of existing standards-based XSD types.

When new schema types are developed for the current service, they can be easily reused for other services by simply importing the newly developed XSD into the other services.

Allows for parallel and independent development of client-side and server-side.

Incremental changes to the service are best managed by changing the WSDL itself. Since the WSDL is the common interface (or contract) for both the client-side and server-side, these changes can be easily managed so they do not affect interoperability with existing requesters or providers.

Tools will use the namespaces defined in the WSDL to determine the package names of the generated JavaBeans (or data transfer objects). Most of the tools support namespace to package name mappings. The advantage with starting from WSDL is that both the client-side and server-side can use different package name mappings without affecting the access of the service.

Disadvantages:

Requires knowledge of WSDL and XSD because both must be manually generated or manipulated. Even the sophisticated tools that exist today to generate WSDL and XSD require detailed knowledge of the structure of WSDL and XSD to ensure proper compliance with standards and optimal performance.

Tool support for the top-down approach has generally been more limited than the support for bottom-up, but that support is improving.

Introduces less interoperability issues.

Recommendation

Selection of one particular approach depends on the business and architectural requirements. However, top down approach is the recommended one as it offers many advantages as detailed above.

7.2 Business Processing Execution Language for Web ServicesBPEL should be considered for Java based web service development in the future and supports the definition and orchestration of web services.

Reference: http://searchwebservices.techtarget.com/generic/0,295582,sid26_gci1172072,00.html for BPEL learner’s guide.

Reference: http://www-128.ibm.com/developerworks/library/specification/ws-bpel/ for BPEL for Web Services 1.1 for a vendor specification

7.3 (BPMN) Business Processing Modeling NotationBusiness Process Modeling Notation (BPMN) is designed to support the definition of business procedures in a graphical.

of 52



http://www-128.ibm.com/developerworks/library/specification/ws-bpel/

http://searchwebservices.techtarget.com/generic/0,295582,sid26_gci1172072,00.html

Reference: http://www.bpmn.org/Documents/Introduction%20to%20BPMN.pdf for the Introduction to BPMN Ver 1.0 .

Reference: http://www.bpmn.org/ for more BPMN information.

7.4 Model driven approach for developmentThe model driven approach for development is the best approach to adopt for the development phase. Choosing right IDE, Tools and frameworks will allow you to integrate your solution seamlessly as a single model. Ultimately you will have the flexibility of automatic code generation (forward and reverse), documentation and provide high level of easy code maintenance. The model driven approach is the recommended approach for the Web Service development.

7.5 Mocking and Unit Testing Web ServicesThe development and deployment of web services creates challenges for developers. The main challenge is unavailability of the actual service to bind to while developing other classes or components. To be productive on this phase it is vital that you mock any dependent web service. The chosen mocking mechanism should be able to provide you with test results representative of the actual service. It is recommended that you:

1. Mock the service using a mocking mechanism which mimics the service and provides you with test results.

2. Use a unit test framework to exercise your code with expected and unexpected test data

Reference: http://techpolicy.iweb.eds.com/ProductBrowser.aspx?PID=1230 for EDS Tech Policy information on open source Mock objects.

Reference: http://techpolicy.iweb.eds.com/ProductBrowser.aspx?PID=1268 for EDS Tech Policy information on JUnit.

of 52





http://www.bpmn.org/

http://www.bpmn.org/Documents/Introduction%20to%20BPMN.pdf

8 Design Considerations

8.1 OverviewWhat is web service design? Before the explosion of SOA and associated technologies I considered its primary focus to be schema and interface design with a special focus on XML parsing, XML/Object mapping and performance. That’s still true today but increasingly the drive for reusability, the proliferation of web services and the enabler of BPEL means that increasing it’s concerned with service compositions and orchestration. In addition the old has been repackaged as new. Search for web services best practices in Google and most of the references will be circa 2004, however, search for SOA and the picture is very different. What was “XML Journal” became “Web Services Journal” and is now “SOA World” (http://webservices.sys-con.com/). However, like the XML based web services which underpin SOA, the fundamental design goals remain constant:

scalability and performance

reliability

interoperability

ease of implementation, reuse, maintenance and enhancement

security, confidentiality, auditability

So what are the key decisions necessary for any Java web service architect and developer?

Sun provides a useful summary at http://java.sun.com/blueprints/guidelines/designing_webservices/html/

webservdesign4.html#1104299

Decide on the interface for clients. Decide whether and how to publish this interface.

Determine how to receive and preprocess requests.

Determine how to delegate the request to business logic.

Decide how to process the request.

Determine how to formulate and send the response.

This design section is primarily focused on bullet one and two above and covers common questions such as:

Which SOAP messaging style? For example JAX-RPC vs. document style

Should I use asynchronous or synchronous calls?

How should I validate documents?

How will I make my web services perform?

It’s highly likely that if you’re reading this that you are already a convert to good design, however, its still worth restating that service interface design is the cornerstone of rapid development and will lay the foundation of future reuse and composition. Before moving on to the guidance let’s refresh our memory of the basic requests flows for a web service call and the architecture offered by the Oracle 10g Application Server.

Firstly finding a provider via the find-bind-execute flow.

of 52



http://java.sun.com/blueprints/guidelines/designing_webservices/html/webservdesign4.html#1104299


http://webservices.sys-con.com/

Figure 12 Find – Bind – Execute Lifecycle

Then a typical SOAP request flow for a JAX-RPC.

Figure 13 Typical JAX-RPC Message Handling

Lastly an overview of the Oracle 10g Application Server web service support.

Figure 14 Oracle Application Server 10g R3 (10.1.3.0.0) Web Services Framework

of 52



http://java.sun.com/developer/technicalArticles/WebServices/soa/fig3.gif

8.2 Key ResourcesThe following references were heavily used in producing the design section.

HP’s Web Service Resource Centerhttp://devresource.hp.com/drc/topics/web_services.jsp and particularly http://devresource.hp.com/drc/resources/WSBestPractices/index.jsp

IBM Technical Library There is a 14 part series called Best Practices for Web Services (you should be able to view them with a search such as (http://www-128.ibm.com/developerworks/views/webservices/libraryview.jsp?

search_by=best+practices+for+web+services ) for example http://www-128.ibm.com/developerworks/webservices/library/ws-best8.html

Best practices for service interface design in SOA, Part 1: Exploring the development, interfaces, and operation semantics of serviceshttp://www-128.ibm.com/developerworks/architecture/library/ar-servdsgn1/index.html?ca=drs-tp1207

Designing Web Services with the J2EETM 1.4 Platform JAX-RPC, SOAP, and XML Technologies

http://java.sun.com/blueprints/guidelines/designing_webservices/html/

Oracle 10g R3 Application Server New Featureshttp://www.oracle.com/technology/tech/java/oc4j/10131/OracleAS-NF-10131.pdf

8.3 End Point Design

8.3.1References


http://www-128.ibm.com/developerworks/webservices/library/ws-whichwsdl/

http://xml.sys-con.com/read/40694.htm

8.3.2End Point Implementation

There are two choices for Interface Endpoint Type in J2EE 1.4:

Using a JAX-RPC service endpoint: The service implementation is a Java class in the Web container. The service adheres to the Web container's servlet lifecycle and concurrency requirements.

Using an EJB service endpoint: The service implementation is a stateless session bean in an EJB container. The service adheres to the EJB container's lifecycle and concurrency requirements.

Sun provides good guidance at http://java.sun.com/blueprints/guidelines/designing_webservices/html/

webservdesign5.html#1119627

New or Wrapped Service: for an existing service choose an endpoint type suited for the tier on which the preprocessing logic. Use a JAX-RPC service endpoint when the preprocessing occurs on the Web tier of the existing application and an EJB service endpoint when preprocessing occurs on the EJB tier.

of 52











http://www-128.ibm.com/developerworks/webservices/library/ws-best8.html

http://www-128.ibm.com/developerworks/views/webservices/libraryview.jsp?search_by=best+practices+for+web+services


http://devresource.hp.com/drc/resources/WSBestPractices/index.jsp

http://devresource.hp.com/drc/topics/web_services.jsp

Threading - because an EJB service endpoint is implemented as a stateless session bean you need not worry about multi-threaded access since the EJB container is required to serialize requests to any particular instance of a stateless session bean. For a JAX-RPC service endpoint you must do the synchronization yourself in the source code.

Transactions – A JAX-RPC service endpoint runs in a Web container, its transactional context is unspecified. There is also no declarative means to automatically start the transaction. Thus, you need to use JTA to explicitly demarcate the transaction. An EJB service endpoint runs in the transaction context of an EJB container. You as the developer need to declaratively demarcate transactions. The service's business logic thus runs under the transactional context as defined by the EJB's container-transaction element in the deployment descriptor.

Access Permissions - A Web service's methods can be accessed by an assortment of different clients, and you may want to enforce different access constraints for each method. When you want to control service access at the individual method level, consider using an EJB service endpoint rather than a JAX-RPC service endpoint.

8.3.3 Interface Granularity, Composition and Reuse

Service granularity will directly affect ease of use and re-use. Designs need to balance extremes of a large number of interfaces with a single operation to a single interface with many operations. This trade off is not specific to web services and has long been an ongoing challenge for object oriented analysis and design.

In general a service interface should generally contain groups of semantically related operations.

There will be other forces at play in selecting the granularity of the interface, such as performance (many small interfaces are slower), ease of maintenance (many interfaces take more management) and the variety of clients (is the same sort of information required by many different clients or with different reliability requirement).

However, generally best practice is to expose coarse-grained services that aggregate simple services to the granularity needed by consumers.

A designer needs to impose order for the purposes of the consumer and, to a large extent, ignore the underlying interface on which it depends. When composing service interfaces from underlying web services performance will have to be carefully considered. This will be a challenge over time as new business services are defined through the composition of existing web services. If performance does become a problem and the interface is available via a protocol such as RMI/IIOP or an in JVM native call, this can be used in instead.

Java application server vendors dealt with this performance problem during the introduction of EJB 1.1 with the use of non standard local references. These then went to become part of the EJB 2.0 specification (albeit in a rather clumsy way). In the alphabet soup that is web service development I haven’t yet found the equivalent (see http://soa.sys-con.com/read/46565.htm for a good discussion)

8.3.4Asynchronous vs. Synchronous

A web service call can be implemented as an asynchronous or synchronous operation. Asynchronous operations have typically been implemented using message oriented middleware (for example a JMS interface to WebSphere MQ) and use a document style interface. Conversely a JAX-RPC interface is commonly deployed as a synchronous call, although for a one way operation control returns immediately to the calling thread, however, there is no way for the client to catch errors.

of 52



http://soa.sys-con.com/read/46565.htm

Asynchronous interactions come in two different flavors:

One-way invocations

The service requestor does not expect or need a response. The application or the business process simply drops the message off to be delivered to the intended destination and continues processing.

Asynchronous request with delayed response

The service requestor dispatches the request message and subsequently polls the service for the response, or a callback is dispatched to the requestor.

So the issues which impact the decision will include:

How long the operation will run for

Required reliability (queuing technology provides guaranteed delivery)

Performance considerations such as rapid changes in load

So in general asynchronous messaging should be used when:

The client does not require immediate response

The service requires minutes or days to complete

Batch processing or human intervention is required

When using asynchronous operations over the Internet operations consider:

using two separate synchronous invocations with the requesting application providing a ID to correlate with the initial request

a polling or posting approach in the design

Also:

Include a reply-to-address if posting back to client

Leverage the SOAP header to maintain state

8.3.5Stateless vs. Stateful

Services should be designed as stateless. Stateless interface scale better and are easier to reuse.

8.3.6RPC vs. Literal

Any experienced Java developer will be familiar with Richard Monson-Haefel who produced the defacto reference guides for EJB development. It’s interesting to note that while reflecting on the completion of his recent book on J2EE Web Service he argued that “JAX-RPC is Bad, Bad, Bad! http://rmh.blogs.com/weblog/2005/06/jaxrpc_is_bad_b.html . As JAX-RPC is the standard approach for Java web services implementation that’s concerning. JAX-RPC is the approach which has been most widely adopted within the Java community, if you use AXIS RPC services are the default in Axis.

However J2EE 1.4 supports both RPC-based and document-oriented web services and document oriented message exchange has been supported in the Java Web Services Developer Pack since 1.1. Once a service is discovered, the client can invoke remote procedure calls on the methods offered by the service, or send an XML document to the web service to be processed. I think one of the reasons

of 52



http://rmh.blogs.com/weblog/2005/06/jaxrpc_is_bad_b.html

is that web services have been introduced into architectures to replace remote method calls and have consequently been modeled on the using the same mentality. Perhaps with the introduction of SOA strategies this will change.

The following is adapted from Russell Butek’s article “Which style of WSDL should I use?” http://www-

128.ibm.com/developerworks/webservices/library/ws-whichwsdl/

A Web Services Description Language (WSDL) binding style can be RPC or document. The use can be encoded or literal. A WSDL document describes a web service. A WSDL binding describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol. A WSDL SOAP binding can be either a Remote Procedure Call (RPC) style binding or a document style binding. A SOAP binding can also have an encoded use or a literal use. This gives you four style/use models:

1. RPC/encoded

2. RPC/literal

3. Document/encoded

4. Document/literal

Add to this collection a pattern which is commonly called the document/literal wrapped pattern and you have five binding styles to choose from when creating a WSDL file.

In most situations the document/literal wrapped format is the best choice and is covered in detail later in this section, but first a review of the strengths and weaknesses of approaches 1 -4 above.

8.3.6.1 RPC/encoded

Strengths

Minimal WSDL.

Easy message dispatch as the operation name appears in the message.

Good for data graphs, for example a binary tree.

Weaknesses

The type encoding info (such as xsi:type="xsd:int") is usually just overhead which degrades throughput performance.

You cannot easily validate this message

Although it is legal WSDL, RPC/encoded is not WS-I compliant therefore reduced interoperability.

8.3.6.2 RPC/literal

Strengths

The WSDL is still about as straightforward as it is possible for WSDL to be.

Easy message dispatch

The type encoding info is eliminated.

RPC/literal is WS-I compliant therefore good interoperability.

of 52





Weaknesses

You still cannot easily validate this message

8.3.6.3 Document/encoded

Nobody follows this style. It is not WS-I compliant.

8.3.6.4 Document/literal

Strengths

There is no type encoding info.

You can finally validate this message with any XML validator. Everything within the soap:body is defined in a schema.

Document/literal is WS-I compliant, but with restrictions (see weaknesses).

Weaknesses

The WSDL is getting a bit more complicated. This is a very minor weakness, however, since WSDL is not meant to be read by humans.

The operation name in the SOAP message is lost. Without the name, dispatching can be difficult, and sometimes impossible.

WS-I only allows one child of the soap:body in a SOAP message.

8.3.6.5 Document/literal wrapped

This is the preferred interaction style and will be considered in greater detail. First let’s consider the following method:

public void myMethod(int x, float y);

Shown below is the Document/literal wrapped WSDL for myMethod

<types> <schema> <element name="myMethod"> <complexType> <sequence> <element name="x" type="xsd:int"/> <element name="y" type="xsd:float"/> </sequence> </complexType> </element> <element name="myMethodResponse"> <complexType/> </element> </schema></types><message name="myMethodRequest"> <part name="parameters" element="myMethod"/></message><message name="empty"> <part name="parameters" element="myMethodResponse"/></message>

<portType name="PT">

of 52



<operation name="myMethod"> <input message="myMethodRequest"/> <output message="empty"/> </operation></portType>

<binding .../> 

The WSDL schema now has a wrapper around the parameters (as below).

Document/literal wrapped SOAP message for myMethod

<soap:envelope> <soap:body> <myMethod> <x>5</x> <y>5.0</y> </myMethod> </soap:body></soap:envelope>

The key features are

The input message has a single part.

The part is an element.

The element has the same name as the operation.

The element's complex type has no attributes.

Strengths

There is no type encoding info.

Everything that appears in the soap:body is defined by the schema, so you can easily validate this message.

Once again, you have the method name in the SOAP message.

Document/literal is WS-I compliant, and the wrapped pattern meets the WS-I restriction that the SOAP message's soap:body has only one child.

Weaknesses

The WSDL is even more complicated.

If you have overloaded operations, you cannot use the document/literal wrapped style. You must use the document/literal, non-wrapped style or one of the RPC styles

8.3.7Message Header vs. Payload

The SOAP specification stipulates that the SOAP message can contain the SOAP header, the body, and any number of user-defined headers. The user defined headers should be used to carry system relevant information that is project specific and conversely avoid putting system-relevant information into the body of your message. Examples of appropriate data include:

of 52

Identification of the service requestor application

Service implementation version

Dispatch and receipt timestamps

Similarly, the response message issued by the service operation can contain system-level data, such as:

Identification of the responding application (service provider)

Receipt and dispatch timestamps

Computed response time

The separation of system and business related data also allows the application of different processing mechanisms with, for example, system level data processed by infrastructure components such as an Enterprise Service Bus.

8.3.8XML Schemas

See http://xml.sys-con.com/read/40694.htm for a good article on schema design.

Use extensible XML schemas to enable addition of new data features when defining message structure.

Validate only the data to be used by the service operation, ignoring other parameters, when processing the message.

Minimize data structure complexity of requests and responses when using RPC with SOAP encoding.

Rely on SOAP Fault element, not HTTP status codes to determine the presence of SOAP processing errors or target service errors.

Stick with well accepted data types and elements for example sse xs:int instead of xs:integer

Date types may cause interoperability problems

Some platforms don't support all XML tags (e.g., <choice>)

Naming types can improve generation of helper classes, without these names, some platforms will generate anonymous class names

Use XML namespace appropriately, these can affect package names of helper classes

Consider methods to reuse XML types within WSDL, define one type and reference in different WSDL operations

Consider optional XML attributes where appropriate, this can increase re-usability and reduce name collisions

Leverage industry schemas such as Open Application Group Integration Specification (OAGIS) or ACCORD. If importing XML Schema into WSDL, leverage JAX-RPC mappings provided by tooling (for example, Integrated Development Environments) and runtimes. However, note not all XSD types are mapped to Java types in JAX-RPC V1.0. If passing an

of 52




entire business object document as a string parameter with Doc/Literal messaging style, use CDATA tags to embed the document into the SOAP Body to reduce SOAP parsing overhead.

8.4 Security

8.4.1References

http://download-west.oracle.com/docs/cd/B25221_04/web.1013/b15979.pdf

http://www.oracle.com/technology/oramag/oracle/05-jan/o15web.html

8.4.2Approaches to Security

Web service security can be implemented with transport level or message level security or both depending on the business and architectural requirements. Transport level security can be realized by using HTTP over SSL. The WS-Security specification defines a complete set of security specification to be used in message level security.

A key reference is the Oracle Application Server Web Services Security Guide 10g Release 3 (10.1.3) http://download-west.oracle.com/docs/cd/B25221_04/web.1013/b15979.pdf which describes the different security strategies that can be applied to a Web service in Oracle Application Server Web Services. The strategies that can be employed are username token, X.509 token, SAML token, XML encryption, and XML signature.

This section focuses mainly on message level security as transport level security is not specific to web services and is better understood than message level security, but first some broad advantages and disadvantages.

8.4.3Key Guidance

Use HTTPS for all external flows between systems over the Internet for confidential or market valued information.

Use mutual SSL authentication between partners when confidential information is exchanged.

Use XML Digital Signatures for SOAP messages to ensure message integrity and application-specific authentication.

Use XML Encryption of SOAP messages for end-to-end confidentiality.

Map the user's identity associated with the Web service invocation to a shared pseudonym for use between different security domains. Including the pseudonym in the request limits security risks by not exposing specifics of the individual security domains.

Use SOAP header blocks to exchange security tokens and to carry time stamps of messages.

When digitally signing messages using the private key of X.509 certificates, include the certificate in the request to enable the receiver to extract the public key of the certificate for validation of the signature.

of 52






8.4.4Transport versus Message Level Security

8.4.4.1 Transport Level Security:

Advantages:

Builds on top of an existing web application infrastructure.

Many developers know SSL and it is easy to enable it in common web and application servers.

SSL is a particularly ideal choice for end-to-end web service integration. SSL can enforce confidentiality, integrity, and authentication.

Offers better performance than message level security.

Does not introduce any interoperability issues.

Disadvantages:

SSL is an "all-or-nothing"-protocol. It does not have the granularity necessary to secure certain parts of the message, nor can it use different certificates for different message parts.

8.4.4.2 Message Level Security:

Advantages:

Offers sophisticated, fine grained, end-to-end security model for web services.

Provides confidentiality, integrity and authentication.

Disadvantages:

The user must be cognizant of performance and interoperability issues when message level security is used even within similar platform but different vendor implementations.

OracleAS supports message level security using the following tokens:

Username

X.509

SAML

8.4.5Transport Level Security

Transport level security is achieved using standard J2EE web access mechanisms of basic, digest, or client certification (client-cert) authentication. Additionally when using EJB 2.1 or 3.0 to implement the service, you can secure it on the transport level by making additions to the oracle-webservices.xml deployment descriptor.

A human interaction with a secured web site using basic or digest security would require entering user and password information. For a web service accessed from a Java web service client stub runtime properties such as javax.xml.rpc.security.auth.username and javax.xml.rpc.security.auth.password can be used to pass the user name and password to the service.

For the client certification method the user must possess a public key certificate which can be loaded into the client JVM keystore.

of 52



8.4.6Message Level Security

The following is adapted from http://www.oracle.com/technology/oramag/oracle/05-jan/o15web.html

The OASIS standard WS-Security was released in April 2004 and defines a mechanism for adding three levels of security to SOAP messages.

Authentication Tokens: WS-Security authentication tokens enable clients to send, in a standardized fashion, username and password or X.509 certificates for purposes of authentication within the SOAP message headers.

XML Encryption: WS-Security's use of the W3C's XML Encryption standard enables the SOAP message body or portions of it to be encrypted to ensure message confidentiality. Typically, various encryption algorithms are supported—in Oracle Application Server 10g Release 10.1.3, the algorithms supported are 3DES, AES-128, and AES-256.

XML Digital Signatures: WS-Security's use of the W3C's XML Digital Signature standard enables SOAP messages to be digitally signed to ensure message integrity. Typically, the signature is a computed value based on the content of the message itself: If the message is altered en route, the digital signature becomes invalid. Oracle Application Server supports DSA-SHA1, HMAC-SHA1, RSA-SHA1, and RSA-MD5 algorithms.

8.4.6.1 X.509 Digital Certificates

The following section is largely comprised of content from Reference 3 by Christopher Chan which provides a great summary of the use of X.509 Digital Certificates for exposing web services securely to external organizations. This section has been expanded on in preference to the other security approaches as:

It addresses the requirement to expose web services to partners – a currently common requirement

It provides summaries of other common technologies and encryption and the use of SAML

Digital Certificates are the electronic counterparts to driver licenses. You can present a Digital Certificate electronically to prove your identity or your right to access information or services online. X.509 is an industry standard and the most widely accepted format for Digital Certificates allowing you to:

Authenticate the subject represented in the certificate

Detect data tampering

Verify trust of a subject based on a Certificate Issuer (Certificate Authority)

Encrypt messages to provide confidentiality

of 52




Figure 11 – Public Key Encryption

It supports data confidentiality by encrypting messages with a public key and decrypting with a private key. It also enables messages to be signed with a digital signature to verify data integrity. In this case each message is signed with a private key and verified with a public key. Digital Signatures enable "authentication" of digital messages, assuring the recipient of a digital message of both the identity of the sender and the integrity of the message

Figure 12 – Ensuring Data Integrity

To understand the request flow from an external client using an x509 certificate see Figure 13 below.

Figure 13 – Client Authentication

As illustrated in Figure 13, the following steps describe STS token issuance and request/response process:

1. The client initializes and sends an authentication request to the STS. The authentication request to the STS is in the form of a RST message. This step can be performed by presenting the client's identifier and proof-of-possession (such as username and password) directly to the STS or by using a token issued by an authentication broker (such as an X.509 digital signature). The approach of the client obtaining the SAML token from the STS is done implicitly where the service manages the interaction with the STS.

The RST message contains a security token that holds the client's credentials, which are required to authenticate the client.

2. The STS validates the client's credentials. After the STS determines that the client's credentials are valid, it may also decide whether to issue a security token for the authenticated client. i.e. the STS may have a policy where it issues tokens only for organizations who belong to a specific role or for valid X.509 certificates that can be validated through a specific trust chain.

3. The STS issues a security token to the client. If the client's credentials are successfully validated, the STS issues a security token (SAML token) in a RSTR message to the client; typically, the security token contains claims related to the client. The security token is usually signed by the STS; when the security token is signed by STS, the service can confirm that the token was issued by the STS and that the security token was not tampered with after it was issued.

of 52



4. The client initializes and sends a request message to the service. After the client receives a security token from the STS, it initializes a request message that includes the issued security token, and then it sends the request message to the service.

5. The security token is validated by the service. After the token is validated by the service, it is used to establish security context for the client, so the service can make authorization decisions .

6. (Optional) The service initializes and sends a response message to the client. A response is not always required.

8.5 Performance and Scalability

8.5.1References

http://www-128.ibm.com/developerworks/webservices/library/ws-best10/

http://java.sun.com/blueprints/guidelines/designing_webservices/html/xml6.html#1130836

8.5.2Guidance

Before getting into some of the detail about which techniques can improve performance its important to remember that, as Donald Knuth said “We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil." http://en.wikipedia.org/wiki/Optimization_(computer_science)

It’s very easy to get bogged down in the details of XML performance tuning without ever knowing if you are actually improving real world performance. So above all:

Conduct load testing on an end to end vertical slice early in project and understand the behavior of the system in terms of performance, capacity and scalability.

The following summary is taken from http://java.sun.com/blueprints/guidelines/designing_webservices/html/

xml6.html#1130836

Limit Parsing of Incoming XML Documents - In general, it is best to parse incoming XML documents only when the request has been properly formulated.

Use the Most Appropriate API - In general, without considering memory consumption, processing using the DOM API tends to be slower than processing using the SAX API. When using higher-level technologies such as XSLT, keep in mind that they may rely on lower-level technologies like SAX and DOM, which may affect performance, possibly adversely.

Choose Effective Parser and Style Sheet Implementations - Consider using JAXP, which not only supports many parsers and style sheet engines, but also has a pluggability feature that allows a developer to swap between implementations and select the most effective implementation for an application's requirements.

Tune Underlying Parser and Style Sheet Engine Implementations - The JAXP API defines methods to set and get features and properties for configuring the underlying parser and style sheet engine implementations. A particular parser, document builder, or transformer implementation may define specific features and properties to switch on or off specific behaviors dedicated to performance improvement.

Reuse and Pool Parsers and Style Sheets - Parsers, which are complex objects, may be pooled so that they can be reused by other threads of execution, reducing the burden on memory allocation and garbage collection. The same considerations may apply to style sheets and transformers.

of 52





http://en.wikipedia.org/wiki/Optimization_(computer_science)


http://www-128.ibm.com/developerworks/webservices/library/ws-best10/

Reduce Validation Cost - Validation is an important step of XML processing, but keep in mind that it may affect performance. Although you must validate external incoming XML documents, you can exchange freely, that is, without validation, internal XML documents or already validated external XML documents.

Reduce the Cost of Referencing External Entities - Recall that an XML document may be the aggregation of assorted external entities, and that these entities may need to be retrieved across the network when parsing.

Cache Dynamically Generated Documents - Dynamically generated documents are typically assembled from values returned from calls to business logic. Generally, it is a good idea to cache dynamically generated XML documents to avoid having to refetch the document contents, which entails extra round trips to a business tier.

Use XML Judiciously - Using XML documents in a Web services environment has its pluses and minuses. Rely on XML protocols, such as those implemented by JAX-RPC and others, to interoperate with heterogeneous systems and to provide loosely coupled integration points. Avoid using XML for unexposed interfaces or for exchanges between components that should be otherwise tightly coupled.

Additionally:

Design the web service interface to minimize the network traffic. A coarse-grained service offers better performance; however, large SOAP messages can be a performance bottleneck due to time spent parsing them. A compromise needs to be achieved in terms of payload size and the desired performance. Large SOAP message can be compressed so that it consumes lesser bandwidth.

Complex SOAP messages can be a performance bottleneck due to time spent serializing/de-serializing messages. Keep the payload complexity low.

The document/literal style SOAP messages are smaller and less complex than rpc/encoded message.

Security incurs performance costs. The performance costs of an end-to-end message level security (i.e. WS-Security) are, in most cases, higher than a transport level security mechanism like HTTP over SSL.

Persistent HTTP connections are good for performance in case of a large number of messages of small payload size. HTTP keep-alive is a way to request that a HTTP connection persists, though this is the default in HTTP/1.1.

Use stateless transactions with all required data included with the request. For example, include business context information such as business transaction ids and authorization codes into the SOAP message Body.

8.6 Interoperability

8.6.1References

http://www.ws-i.org/

http://blogs.msdn.com/smguest/archive/2004/08/12/213659.aspx

of 52




http://www.ws-i.org/Default.aspx

8.6.2Overview

Web services have been a success largely because of their interoperability in heterogeneous computing environments. Interoperability was a key focus of the J2EE 1.4 release. While other protocols such as CORBA did the same, they were just too hard to work with. However, the various Web services specifications are sometimes inconsistent and unclear and when the specifications are clear not all data types are available on all platforms.

To address these challenges the WS-I organization (http://www.ws-i.org/ ) was formed to create and promote interoperability of Web services. It has defined a number of profiles which dictate how you should write your Web services to be interoperable.

The WS-I Basic Profile covers:

Messaging standards (such as SOAP)

Description and discovery standards (such as UDDI)

Security

A significant effort in J2EE 1.4 Web services was ensuring that Web services built with JAX-RPC and SAAJ could easily conform to the WS-I Basic Profile and Oracle 10g R3 Application Server Web Services should conform to the WS-I Basic Profile 1.1. Oracle has also done the same interoperability certification with its WS-Security implementation conforming to the WS-I Basic Security Profile 1.0.

8.6.3Testing

Best practices in testing include:

Understand what types of SOAP clients will access the service

Test software against different vendors and platforms

Test for interoperability before deploying into production

8.6.4Top Tips

See http://blogs.msdn.com/smguest/archive/2004/08/12/213659.aspx

Use XSD First - When designing for interoperability, always start with defining the data first. Deciding on what data will be sent, creating the data type in XSD first, and then using tools to generate classes from the XSD file will help guarantee data type interoperability on the wire.

Use Unit Tests to Test Interoperability - Unit tests (using NUnit for .NET and JUnit for Java) are invaluable for testing interoperability of multiple data types over a Web Service. Re-running the tests if data types change (or if you change versions of Web Services toolkits!) will give you the confidence that the Web Services that you design are fully interoperable.

Ensure Document/Literal when generating Web Services - Many toolkits have the option of choosing either RPC/Encoding or Document/Literal as the default format when generating Web Services. To help ensure compliance with the WS-I Basic Profile 1.0, select Document/Literal as the default encoding mechanism for all of your Web Services.

Add Option to Change Host and Port - When designing your Web Service client, consider adding a helper method to change the host and port values of the Web Service location. This makes it easy

of 52




http://www.ws-i.org/Default.aspx

if the location of the Web Service changes in the future or you want to redirect the output to a trace tool.

Use Trace Tool to Investigate - A Trace Tool can be invaluable for investigating SOAP requests and responses between Web Services. It can help validate data types and the construct of the message, and also report SOAP faults that you may miss in a browser. Using one that intercepts the request is more difficult to setup, but easier to use than looking through trace files.

Always use compareTo() when comparing dates/times - If sending dates and times over a Web Service between .NET and Java, always use the appropriate compareTo() method in Java to compare dates (as opposed to date == value). This will help ensure accuracy for date comparisons between the platforms, especially when trying to compare those milliseconds values.

Null Dates and Times are recognized by Java, but not by .NET - In Java, java.util.Date and java.util.Calendar are classed as reference types. In .NET, System.DateTime is considered a value type. Reference types can be null, whereas value types cannot. If you are planning to send null date values across a Web Service, always send the value in a complex type, and set the value of the complex type to null. This will help prevent the null date value being interpreted incorrectly (and raising an exception).

Testing Generated Java Beans for Null - When using tools or an IDE to generate Java Beans from an XSD file, always make sure that you know how to test to see if the object is null. In some instances this is done using the isNil() method on the bean itself.

Use Package and Type Name Options when Generating Client Proxies - Many Java based tools have the option of specifying a unique package and type name when generating client proxies (for example, BEA WebLogic uses clientgen parameters to do this). This is essential when you are creating proxies for Web Services that share the same data type.

Watch out for Empty Arrays - Sending empty arrays over Web Services can create issues – some toolkits recognize an empty array as a single null value. If you are sending arrays of objects over a Web Service, always ensure that the array contains valid data.

8.7 Reliability

8.7.1References

Overview of WS Reliable Messaging and Session Support http://weblogs.java.net/blog/bhaktimehta/archive/2006/08/ws_reliable_mes_1.html.

Web Services Reliability (WS-Reliability) Version 1.0: Frequently Asked Questions (FAQ)http://developers.sun.com/sw/platform/technologies/ws-reliability.faq.html

http://www-128.ibm.com/developerworks/websphere/techjournal/0602_tost/0602_tost.html

8.7.2Overview

Reliability is a common requirement of transactional enterprise systems. This has often been achieved using a combination of XML messages and JMS (for example refer to http://www-

128.ibm.com/developerworks/websphere/techjournal/0602_tost/0602_tost.html). The WS ReliableMessaging was published in March 2003 and in June 2005 the 1.0 specification was submitted to OASIS for standardization.

In Oracle’s words the current version Oracle Application Server 10g R3, provides an implementation of the OASIS standard WS-Reliability however Oracle is committed to delivering an implementation

of 52






http://developers.sun.com/sw/platform/technologies/ws-reliability.faq.html

http://weblogs.java.net/blog/bhaktimehta/archive/2006/08/ws_reliable_mes_1.html

of WS-ReliableExchange, a reliable messaging variant that has drawn consensus from the major Web services infrastructure vendors Oracle, IBM, BEA and Microsoft when it emerges from the OASIS standards body.

Oracle also supports JMS Web services, which are slightly different because two JMS destinations and possibly an MDB are required, depending on implementation. In this scenario, a SOAP call goes through the following progression:

The Web service client sends a SOAP message to an HTTP Servlet

The Web service listener Servlet drops the message to a JMS destination

An MDB or alternate JMS client picks up the incoming message and processes the contents

The result of the operation is placed on a second JMS destination

The Web service listener Servlet returns the service result to the Web service client via a SOAP message

of 52



9 Design Issues in Implementing Target Use CaseDescribe how the guidance in this document would be relevant to design decisions required to implement a system for the target use case. This section would necessarily specify the design decisions taken but would link the guidance to the relevant areas of the architecture and development process. For example:

9.1 Design

How would a user authenticate to the web application?

How would credentials supplied to securely transferred to a web service call to the credit check agency?

Would the call to the credit check agency be synchronous, asynchronous use RPC or Document style, what security measures would be involved?

How would audit and logging be achieved? Java APIs directly or via Oracle Application Server functionality, what are the trade offs?

How would performance considerations be reflected in a design? Would the system use DOM, SAX and through which API?

Would I use BPEL?

Which standards and APIs are likely to be present in the final solution?

9.2 Development Approach

Would you start with WSDL in defining the web service interface to the credit check agency? Is there any industry standards to reuse?

How could the service be developed if the credit check agency has no access to the development environment?

Which tools will I use? Borland Architect, JDeveloper, others?

of 52



10 Bibliography

[1] Code, Security Docs, Architecture, Sample App

http://www.ws-i.org/deliverables/workinggroup.aspx?wg=sampleapps

[2] Sun BluePrints for SOA and Web Services and Identity

http://java.sun.com/developer/technicalArticles/WebServices/soa/

https://bpcatalog.dev.java.net/nonav/soa/index.html

Identity Management resource centrehttp://www.sun.com/software/products/identity/index.jsp

[3] Web Services Development, Deployment, Security and Testing Made Easy

https://knowledgecentre.eds.com/sites/kc44/gjf/Reference/Conferences%20and%20Seminars/Oracle

%20Open%20World/Web%20Services%20Development,%20Deployment,%20Security%20and

%20Testing%20Made%20Easy.ppt

[4] Web Services Architecture and Its Specifications: Essentials for Understanding WS-*

http://www.books24x7.com/book/id_12504/toc.asp

[5] Oracle eBook

http://www.packtpub.com/BPEL-SOA/book#indetail

http://www.packtpub.com/page/BPEL_Cookbook_Table_of_Contents

[6] SOA & BPEL: SOA & BPEL: Building a Service With BPEL Building

http://developers.sun.com/events/techdays/presentations/2007/TD_ATL_JavaEE_BPEL_SOA.pdf

[7] Oracle Application Server List of Books for 10g Release 3 (10.1.3)http://download-east.oracle.com/docs/cd/B25221_04/nav/docindex.htm

[8] Service Oriented Architectures (SOA) Community https://knowledgecentre.eds.com/sites/kc0155/default.aspx

[9] EDS Technology Strategy & Architecture Identity and Access Management https://knowledgecentre.eds.com/sites/kc16/TechnologyDirectives/Identity%20and%20Access

%20Management.doc

[10] EDS Tech Policyhttp://techpolicy.iweb.eds.com/default.aspx

[11] HP’s Web Service Resource Centerhttp://devresource.hp.com/drc/topics/web_services.jsp and particularly http://devresource.hp.com/drc/resources/WSBestPractices/index.jsp

[12] IBM Technical Library – Web Services Best Practices

of 52



http://devresource.hp.com/drc/resources/WSBestPractices/index.jsp

http://devresource.hp.com/drc/topics/web_services.jsp

http://techpolicy.iweb.eds.com/default.aspx




http://download-east.oracle.com/docs/cd/B25221_04/nav/docindex.htm

http://developers.sun.com/events/techdays/presentations/2007/TD_ATL_JavaEE_BPEL_SOA.pdf

http://www.packtpub.com/page/BPEL_Cookbook_Table_of_Contents

http://www.packtpub.com/BPEL-SOA/book#indetail

http://www.books24x7.com/book/id_12504/toc.asp

https://knowledgecentre.eds.com/sites/kc44/gjf/Reference/Conferences%20and%20Seminars/Oracle%20Open%20World/Web%20Services%20Development,%20Deployment,%20Security%20and%20Testing%20Made%20Easy.ppt



http://www.sun.com/software/products/identity/index.jsp

https://bpcatalog.dev.java.net/nonav/soa/index.html

http://java.sun.com/developer/technicalArticles/WebServices/soa/

http://www.ws-i.org/deliverables/workinggroup.aspx?wg=sampleapps

http://www-128.ibm.com/developerworks/views/webservices/libraryview.jsp?

search_by=best+practices+for+web+services

[13] Designing Web Services with the J2EETM 1.4 Platform JAX-RPC, SOAP, and XML Technologieshttp://java.sun.com/blueprints/guidelines/designing_webservices/html/

[14] Oracle 10g R3 Application Server New Featureshttp://www.oracle.com/technology/tech/java/oc4j/10131/OracleAS-NF-10131.pdf

of 52







Java Web Services Guidev1.0

Documents

Transcript of Java Web Services Guidev1.0