W H I T E P A P E R OptimalJ Web services

One of the biggest business challenges facing organizations today is leveraging their
existing investments, such as existing applications. Therefore, almost every development
project requires some level of application integration. As development and integration
are very much related, OptimalJs model-driven and pattern-based development
environment is extended to include a model-driven integration environment.

OptimalJ enables developers to integrate external components into an OptimalJ

application by importing the application information into the Integration Model. The
Integration Model is an extension of the Application Model. The Integration Model is
used to generate connector code for invoking the external application. The Integration
Model can also be used to generate EJB and Web models so that developers can
generate Session Bean wrappers and JSPs for invoking and interacting with the
connector.

Figure 1: OptimalJ Integration Model

The objective of the Integration Model is to connect to external applications by

reducing complexity and therefore accelerate application integration when developing
a new J2EE application, similar to what OptimalJ provides for Java development.

Before you read our technical white paper series, we encourage you to gain a general
understanding of OptimalJ and its use of MDA by reading OptimalJ: An Introduction at
http://www.compuware.com/products/optimalj/detail.htm.

CompuwareCorporation
Web services
Web services, as the name implies, are services offered via the web. A Web
service provides application logic (without worrying about how the Web
service is implemented) that is accessible using standard Internet protocols.
In a typical Web services scenario, a business application sends a request to a
service at a given URL using the SOAP1 protocol over HTTP. The service
receives the request, processes it, and returns a response. The Web service
interface is the only thing the consumer of the Web service needs to know.
The web service interface is described using the Web Services Description
Language (WSDL2). The Web service implementation is relevant only for the
Web service provider.

An often-cited example of a Web service is that of a stock quote

service, in which the request asks for the current price of a specified
stock, and the response gives the stock price. This is one of the simplest
forms of a Web service in that the request is filled almost immediately,
with the request and response being parts of the same method call.

Web services are the next logical step in the evolution of technology
standards. Web services infrastructure will transform todays software runtimes
into a more flexible service-oriented architecture3 and offer enterprises
significant savings and flexibility in application integration and development.

OptimalJ provides access to external Web services. Besides connecting to

external Web services, OptimalJ also enables users to develop their own Web
services. The OptimalJ Web services implementation is based on open
standards, namely:

Web Services Description Language (WSDL) from W3C.

Simple Object Access Protocol (SOAP) from W3C.
Java API for XML-Based RPC (JAX-RPC) from Sun Microsystems.
AXIS from Apache Software Foundation is used as the JAX-RPC compliant
runtime system and the WSDL to Java mapping tool. The AXIS implementation
fully complies with the WS-I interoperability standards. Apache AXIS has
surpassed Apache SOAP in function, performance and interoperability and, in
particular, has passed Suns JAX-RPC compliance tests.

In addition to these essential features, the model-driven approach taken by

OptimalJ brings with it some further benefits, which differentiate it from a
simple framework.

1
SOAP (Simple Object Access Protocol) - lightweight, extensible protocol for information exchange across different systems and protocols.
Part of the SOAP specification defines a set of rules for how to use XML to represent data.
2
WSDL (Web Services Description Language) - an XML-based contract language that defines a standard mechanism for documenting what
messages a Web service accepts and generates (i.e., interfaces).
3
See white paper: Service Oriented Architecture and OptimalJ http://javacentral.compuware.com/members/downloads/whitepapers.htm

2
Web services provision with OptimalJ
OptimalJ offers the functionality to expose any OptimalJ modeled stateless
Session Bean as a Web service. This is based on the ability to expose EJB
components as Web services. Providing a Web service in OptimalJ entails two
things:

Implementing the functionality provided by the Web service based on a

business level
Generating the Session Bean code, deployment descriptor and WSDL file
required by the consuming application
Like all application development in OptimalJ, developing a Web service is a
model-driven process. The process starts with defining a Domain Model. The
Domain Model consists of two sub-models: the domain class model and the
domain service model. The class model is a high-level business model
undistorted by any technology detail. In the domain service model, users
model the business operations and create the basis for the generation of
Web services.

Figure 2: The domain class and domain service model

After having defined the Web service definitions at the Domain Model level,
developers can start generating the Application Model in the application tier
by using the Update All Models menu option. OptimalJ generates applications
that are logically layered and service oriented, since the Application Model
consists of three sub-models: Web, EJB and DBMS. Within the context of
Web services, the three sub-models serve the following purposes:

3
 EJB Model
The domain service is transformed to an EJBSessionComponent in the EJB
Model. This session component includes the domain service operations,
transformed to methods. At the code level, the session component methods
become part of the component interface of the generated Session Bean. The
EJBSessionComponent belongs to the internal implementation of the Web
service and, therefore, is relevant only for the Web service provider.

Web Model
The generated Web Model contains a Web component with a web action that
represents the domain service operation and its parameters. From this action, a
web front-end can be generated to present the web action parameters. This
web front-end allows developers to test the Web service implementation
within the development environment.

DBMS Model
The DBMS model contains the relational data schema. This schema includes
base table definitions that are transformations of the domain classes in the
class model. From the DBMS model, an SQL script is generated that allows
the implementation of the tables in a database. Again, this is relevant only for
the Web service provider.

After generation of the Application Model out of the Domain Model, the
next step is to generate the Web service from the EJB Model (see figure 3).

Figure 3: Generate Web service from EJB

4
The generation results in two top-level elements:

A WSDLRepository, which completely describes the interface of a single

Web service and is used to create the WSDL file for the Web service.
WSServerModule, which represents the interfaces used by external
applications to interact with the Web service.
To fully expose and implement the Web service, the developer generates code
from the Integration Model and the EJB models. The generated code from the
EJB Model is similar to regular OptimalJ applications and therefore the
EJBSessionComponent is transformed in Session Bean-related code, including
exception handling code and deployment descriptors for the preferred target
platform. The business methods as defined on the domain service level are
contained in the component interface of the session bean. Optionally a user
front-end component for testing purposes can be generated. From the
Integration Model, the WSDL file, SOAP binding and XML schemas are
generated.

To fully implement the Web service logic, developers only provide the method
body for those Session Bean methods that represent the Web service
operations. Free blocks are available for this purpose. This allows developers to
focus on adding value by enhancing business logic that fully supports the
business, rather than building the infrastructure.

The exposed session bean is made available as a Web service component

through the HTTP transport of the WSDL SOAP binding. All the business
methods of the exposed Session Bean are represented as RPC-coded mode
request-response operations. Support for HTTP Basic Authentication, servlet-
based authorization and digital signatures is offered (see paragraph on Web
Services Security).

5
Web services consumption with OptimalJ
Invoking a Web service based on a services description (WSDL) with
OptimalJ requires a developer to first import an existing WSDL file into
OptimalJs Integration Model by using OptimalJs Web service WSDL import
facility. The Web service WSDL import facility generates an OptimalJ Web
service Integration Model from an existing WSDL file. The import facility
does the following:

reads a WSDL file from the local file system or a remote location. If remote,
a URI (Uniform Resource Identifier) that points to the location and file
name is required. The URI is published by the Web service provider.
handles links to other WSDL files and XML schemas. The links are
specified with the import element in the WSDL file.
analyzes the file using WSDL syntax and semantics, and generates error
messages for violations, indicating the cause and location.
inserts the generated model into the OptimalJ repository.

Figure 4: OptimalJs Web services Integration Model after the WSDL import

6
After importing a WSDL file, the Web service Integration Model is populated
and available (see figure 4). From there the Domain Model can be generated.
The advantage of creating a Domain Model out of the Integration Model is
that the business functions provided by the Web service are represented at the
domain-level view of the application. This includes the domain class model
and the domain service model. The Web service component definition is
copied to the domain service model. More than one domain service can be
generated from the Integration Model. Structural elements such as complex
and enumeration type definitions are copied to the domain class model. No
domain classes are generated (see figure 5).

Figure 5: Domain class model and domain service model derived from the Integration Model

After generating the Domain Model from the Web service Integration Model,
the Application Model can be generated (see figure 6). The Application
Model includes the EJB and Web models. From the domain service, OptimalJ
allows developers to generate a Session Bean and its related code. This Session
Bean is then used as a wrapper for the Web service client code. Optionally,
users can also generate the Web Model. This enables users to create a web-
based interface for providing data input and displaying the result of the call to
the Web service for testing purposes.

7
Figure 6: OptimalJs Application Model, which includes the EJB and Web models

The final step is to generate and compile source code from the Application
Model. The code generator uses the specifications in the EJB Model to
generate the appropriate code. Generating code from the EJB Model will
result in a Session Bean that is used as a wrapper, whose business methods
invoke the related methods of the Web service. The interface of this Session
Bean includes methods that reflect the operations as defined in the interface
description. Deployment descriptors are generated, based on the preferred EJB
server as selected in the OptimalJ System Settings.

The generated code includes bean classes, JSPs, the update object, deployment
descriptors and other code required to call the integrated component. The
generated Session Bean is used to invoke the generated connector (client)
code. The created Java classes provide a self-contained framework for
accessing the target Web service in a JAX-RPC compliant way. All the
mandatory JAX-RPC types are supported, including complex XSD types,
complex XSD types derived by extension, arrays, etc. Besides the mandatory
JAX-RPC types, support for occurrence constraints minOccurs and maxOccurs
for xsd:element is generated where applicable.

Both RPC-encoded and document-literal-style operations are supported (most

.NET Web services are based on the document-literal style). Additionally, all
SOAP Bindings based on HTTP/HTTPS transport are generated.

8
=== start generating code
generate java classes for EJBStructType Address
generate java classes for EJBStructType Phone
generate java classes for EJBEnumType StateType
generate java classes (EJB 2.0) for EJBSessionComponent AddressBook
generate generic deployment descriptor (EJB 2.0) for EJBModule ejb
generate Manifest file for EJBModule ejb
Generating a KeyGeneratorFactory for modelpackage.application.ejb.ejb
generate JBoss 3.0 deployment descriptors (EJB 2.0) for EJBModule ejb
Generating WebComponent AddressBook
Generating AddressBookAddEntryForm.java
Generating AddressBookAddEntryIntAreaCodeForm.java
Generating AddressBookGetAddressFromNameForm.java
Generating AddressBookGetAddressFromNameIntAreaCodeForm.java
Generating AppError.jsp
Generating Character Encoding Filter for web
Generating web deployment descriptor
Generating action mappings for web
Generating resource properties for web
Generating index.html
generate Manifest file for WEBModule web
Generating JBoss 3.0.x specific deployment descriptor for WEBModule web
Generating WSDL/XSD document(s) and java code for WS client module WSClientModule.
Creating a top-level WSDL document wsdlrepository_top.wsdl
Invoking an external WSDL-to-Java convertor for top-level WSDL file
D:\signatures_demo\app\modelpackage\integration\webservices\WSClientModule\wsdlrepository_top.wsdl.
Successfully finished generating code for WS client module WSClientModule.
Exporting the WSDLRepository modelpackage.integration.webservices.wsdlrepository into WSDL/XSD
document(s):
Creating a WSDL document wsdlrepository.wsdl
Successfully finished exporting the WSDLRepository modelpackage.integration.webservices.wsdlrepository into
WSDL/XSD document(s).
=== finished generating code

Figure 7: Overview of the code generated, with JBoss deployment descriptors

9
The following runtime services are available:

a) Support for HTTP and HTTPS transports, that is, support for SSL is
provided.
b) Support for participating in a session with a Web service endpoint
component in case the OptimalJ Session Bean has been marked stateful.
Note: this only makes sense if the targeted Web service has been deployed
with its scope set to Session.
c) Support for setting an upper bound on the duration of all request-
response remote calls to the methods of the Web service component made
by the business methods of the Session Bean.
d) Support for HTTP Basic Authentication.
e) Support for specifying HTTP/HTTPS proxy related settings as well as SSL
related settings when starting an EJB application server wherein the
Session Bean is going to be deployed.
f) Support for setting any Java system property when starting an EJB
application server wherein the Session Bean is going to be deployed.
g) Support for digital signatures as defined in the Web Services Security
specification (see next paragraph).

10
Web Services Security
Security is rarely an issue when Web services are used only internally. When
they are to be exposed externally it becomes a more serious issue. Starting
with release 3.1, OptimalJ supports the important new open standard Web
Services Security (WS-Security4) from the Organization for the Advancement
of Structured Information Standards (OASIS - http://www.oasis-open.org).
The WS-Security specification is seen as the key Web services standard, and is
the first such standard to support, integrate and unify multiple security models,
mechanisms and technologies. It is intended to allow a range of different
systems to interoperate in a platform- and language-neutral manner.

Web services use SOAP for XML messaging. As SOAP messages are sent
across the wire, they could be lost or modified. Securing these messages or,
more generally, securing business transactions on the web, is an important
topic. The WS-Security specification fundamentally provides a standard set of
SOAP extensions that can be used to implement both integrity and
confidentiality in Web services applications. Web services must be able to
authenticate users and message senders and protect transmitted data from
being modified by inappropriate parties. The following security requirements
must be addressed to ensure the safety of information exchange in general and
SOAP messages in particular.

Authentication establishes the identity of the user (or another program)

attempting to access the application. Typically the basic credentials that
authenticate a user are a username and password combination.
Authorization determines which users can access which resources.
Authorization therefore covers the privileges of authenticated users.
Confidentiality is the process of ensuring that only the intended user is able
to access specific information. While authorization prevents information
from reaching unintended parties in the first place, confidentiality ensures
that even if the information falls into the wrong hands, it remains unusable.
Data integrity assures that messages have not been modified in transit.
Integrity of data is usually assured by calculating message digests using a
hashcode and sending a digital signature of the data along with the data.
The receiver verifies the data and its hashcode.
Non-repudiation guarantees that the sender of the message cannot deny
sending it. For example: it guarantees that the sender cannot deny the
placement of a specific order, when receiving an invoice for that order.
Non-repudiation means that proper authentication is in place and involves
the use of digital signatures.

4
http://www.oasis-open.org/committees/download.php/3281/WSS-SOAPMessageSecurity-17-082703-merged.pdf

11
In OptimalJ, Authentication and Authorization are supported in the form of
HTTP Basic Authentication5 and servlet-based authorization, where OptimalJ
generates the necessary bits and pieces. The next sections describe how
OptimalJ supports and implements Web Services Security.

Digital signatures
To allow a digital documents integrity to be verified, a mathematical hash
function (Secure Hashing Algoritm; SHA) is applied to the bits that make up
the document. The resulting number is called the message digest. It has the
property that if the document is altered, applying the same hash function
would result in a different message digest. The message digest is sent along
with the document so that the recipient can recalculate the message digest
from the document and compare it with the digest received with the
document. If the digests are the same, then the message sent and the message
received are exactly the same.

Message digests alone are not a complete solution for ensuring that a
document has not been modified. Someone might intercept a message and its
digest, modify the message, recalculate a new digest, and send both on to the
recipient. This is where the second cryptographic technique comes in, digital
signatures. A digital signature is the encryption of the message digest based on
public key cryptography.

Public key cryptography

Public key cryptography is a form of cryptography which makes use of two
keys: a public key and a private key. Each actor (i.e., sender/signer or
receiver/verifier) gets a pair of keys; one called the public key and the other
called the private key. The public key is published, while the private key is
kept secret. All communications involve only public keys, and no private key
is ever transmitted or shared. Anyone can send a confidential message by just
using the public key, but the message can only be decrypted with a private key.
The private key is always linked mathematically to the public key. This is the
idea behind algorithms such as DSA (Digital Signature Algoritm) and RSA
(Rivest, Shamir and Adleman). Public-key cryptosystems are designed so that
deriving the private key from the public key is computationally infeasible.

5
HTTP Authentication entails sending user names and passwords encoded as Base64 without ciphering them. It is strongly recommended to
use HTTP basic Authentication in combination with the Secure Socket Layer (SSL). Enabling SSL is a matter of making the Web server
listen on a secure port.

12
Certificates
For signature verification to be meaningful, the verifier must have confidence
that the public key does actually belong to the sender. Otherwise someone
could claim to be the sender, presenting a different public key instead of the
real one.

In OptimalJ, both the signing and the verifying part use X509 Certificates
(versions 1 through 3) as a means of communicating/obtaining public keys to
be used in verifying. X509 is described by WS-Security and includes extensible
ways to describe the characteristics of the credentials included with a message.
Since an X509 Certificate maps a public key to the key owners identity, it is
of paramount importance that the verifier make sure that the certificate is
valid: i.e., its owner identity is known or can be testified to by a Certificate
Authority like Verisign (http://www.verisign.com/) or Thawte
(http://www.thawte.com/) prior to verifying the message with the certificates
public key. For testing purposes and simple scenarios, one can use the JDKs
keytool utility6 for the generation of private keys and certificates too. In this
respect, the capabilities of keytool are somewhat limited in that it always
generates self-signed X509 Version 1 certificates, which offer very little
authenticity.

In the event of using certificates found in incoming SOAP envelopes,

OptimalJ provides the following ways of verifying their trustworthiness:

1. Based on the presence of a certificate in a keystore7 specified by the

verifying party. This approach is useful when the number of business
partners is not large and all are known to the Web service provider.
2. Using the verify method of a user-defined class, which has to implement
com.compuware.alturadev.ws.wsse.CertificateVerifier. The
interface is part of the open-source alturalib library shipped with
OptimalJ. This method gives the user flexibility in verifying a certificate.
The user can extend the code, by extending the interface, in such a way
that the validity of the certificate can be checked at the Certificate
Authority.
In addition, its also possible to simply ignore certificates supplied in signed
SOAP envelopes and use a predefined certificate for verifying. Although in a
typical scenario the client of a Web service component would sign its requests,
and the Web service component provider would verify them, OptimalJ allows
for the possibility that the Web service component provider signs its responses
and the client verifies them. This may be done on top of the normal scenario
or independently.

6
http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/keytool.html
7
Java keystore is a secure storage for private keys and certificate chains

13
Digital signatures - signing
The senders private key is used to encrypt the message digest. This is termed
the digital signature. Since the private key of a person is involved, the
digital signature is unique to that individual. This establishes the identity of
the sender (signer). This signature is then bound to the message and sent
along with the document or the transaction. The public key of the individual
is also sent.

Figure 8: Signing properties of a Web service in OptimalJ

OptimalJ provides a separate model element in the Web service integration

model for signing SOAP messages (see figure 8). This model element is the
placeholder for a number of properties for signing SOAP messages. For
example, the property SignatureMethod assigns the combination of a message
digest algorithm and a key-dependent algorithm. The options are RSA-SHA1
and DSA-SHA1. When the signing properties are specified, they can be
bound to any Web services component that is available in the Web service
Integration Model. The signing part in OptimalJ signs the whole SOAP body
of the outgoing SOAP envelope, making sure that the caller claims
responsibility for the whole payload found in the message. Support for
different signing properties can be specified for each Web service separately,
giving extra flexibility. The signing properties are generated into the
deployment descriptor.

14
Digital signatures - verification
When an individual receives a signed document, the verification process is
initiated. The public key of the sender is used to decrypt the digital signature
and retrieve the message digest. The hash algorithm is applied again to the
digital contents to generate another message digest. These two message digests
are compared, and, if they match, verification is successful. If there were any
changes in the digital contents, the resultant message digest would differ from
the original one and the verification would fail.

Figure 9: Verifier properties of a Web service in OptimalJ

OptimalJ provides a separate model element in the Web service Integration

Model for verifying SOAP messages (see figure 9). This model element is the
placeholder for a number of properties for verifying SOAP messages. For
example the certificateValidation property defines how the certificate needs to
be verified. One option is to ignore the certificate information. The option
Trusted Store means that the trusted certificate entries in the keystore file are
verified. The programmatic option allows your own validation mechanism.

When the verifying properties are specified, they can be bound to any Web
services component that is available in the Web service Integration Model.
The verifying properties are generated into the deployment descriptor. By
default, the verifying part always ensures that only those requests are processed
whose whole SOAP bodies are signed. If only a portion of the body is signed,
the verifier rejects the request with a SOAP fault being reported back to the
sender. The verifying part can be configured to accept not-signed SOAP
envelopes, in which case a normal not-signed message is simply passed on to
the implementing class. In most cases this should be avoided.
15

Compuware products
and professional services
delivering quality
applications
Compuware is a leading global
provider of software products and
professional services which IT
organizations use to develop,
integrate, test and manage the
performance of the applications
that drive their businesses. Our
software products help optimize
every step in the application life
cyclefrom defining requirements
to supporting production service
levelsfor web, distributed and
mainframe platforms. Our services
professionals work at customer
sites around the world, sharing
their real-world perspective and
experience to deliver an
integrated, reliable solution.
Summary
OptimalJ enables users to create Web services (provision) from a high-level
business model, hiding the complexity by generating all the J2EE
administrative code. Developers and designers have more time to focus on the
real added value of the Web service, i.e., fully focus on the implementation of
the business logic. Additionally, OptimalJ enables users to call an external
Web service (consumption) just based on importing its WSDL file. Based on
this information OptimalJ generates the necessary components to invoke the
Web service, taking the complexity away.
OptimalJ minimizes security risks by implementing secure Web services based
on the OASIS standard. OptimalJ supports all mandatory and recommended
algorithms for digesting, signing and verifying as specified in the Web Services
Security and XML-Signature Syntax and Processing8 documents. By its model-
driven nature, OptimalJ hides the Web Services Security complexity by
deriving all the necessary components from the models.

Please contact us to learn more

about how our comprehensive
solutions can help your
organization improve productivity,
create higher quality applications
and ensure performance in
production.

All Compuware products and services listed within are

trademarks or registered trademarks of Compuware
Corporation. Java and all Java-based marks are trademarks
or registered trademarks of Sun Microsystems, Inc. in the
United States and other countries. All other company or
product names are trademarks of their respective owners.
2004 Compuware Corporation

8
http://www.w3.org/TR/2002/REC-xmldsig-core-20020212

1/04