1 Introduction

ModePro™ Java EE Cartridge, distributed as part of the ModelPro™ provisioning engine, generates Java EE deployable artifacts from UML Platform Independent Models (PIM) based on SoaML standard.

This following is list of the target technology platforms that the JEE cartridge provisions to:

Web Service Contract:

Web Service Definition Language (WSDL) 1.1

WS-Addressing 1.0 WSDL Binding
SOAP 1.1

XML Schema 1.0

Java EE:

Build Environment

Eclipse with Web Tools Platform
Apache Ant

This document describes how a cartridge user can use the Java EE cartridge to automate the generation of Java EE web services implementations. Knowledge or experience in the following technologies areas is required:

Working knowledge of UML and SoaML;
Understanding of the ModelPro™ provisioning concept;
Understanding of Java EE web service application programming interfaces (API).

In addition, it is assumed that the user is familiar with the Eclipse development environment. Though SoaML examples are used throughout this document, this document is not intended to be a SoaML tutorial. Please refer to the SoaML/ModelPro Tutorials for how to create models using SoaML. In addition, the ModelPro Technical Reference document explains the basic concepts of ModelPro provisioning engine which first time users may find helpful.

2 Understanding the Provisioning Model

The Java EE cartridge produces deployable artifacts based on a provisioning model, a Platform Specific Model (PSM), contained in the same UML model file as the SoaML PIM. In the provisioning model, model elements are annotated with stereotypes defined in the JEE Provisioning Profile, a UML profile shipped with ModelPro™. The JEE Provisioning Profile can be accessed at http://portal.modeldriven.org/content/uml-profiles.

Figure 1

As shown in Figure 1, the following are key stereotypes defined in the JEE Provisioning Profile:

JEE Provisioning. The ModelPro™ provisioning engine engages the Java EE cartridge when it detects that the provisioning model specifies an Execution Environment with the JEE Provisioning stereotype. This stereotype defines the following tag:

runtime. This optional tag specifies a server definition in the target Eclipse workspace.

JEE Web Service. The cartridge provisions a Java EE Web Service project for each participant instance with the JEE Web Service stereotype. Each port defined by the participant instance with ServicePoint stereotype will expose a web service endpoint. The JEE Web Service stereotype defines the following tag:

targetNamespace. This tag specifies the XML namespace for the provisioned web service artifacts, such as XML schemas and WSDL definitions. The package names for the provisioned Java source code will also be derived from the value of this tag.

Service Point Provisioning. This stereotype allows additional web service endpoint provisioning instructions to be provided through the following tags:

usedInterfaceAddress. When a Service Interface implements a UML interface and uses another, the usedInterfaceAddress tag allows the user to specify a static web service endpoint address for the used interface. This static can be overridden at runtime. See Section 4 for more details.
usedInterfaceNamespace. Not currently used.

Entity Override. The cartridge will provision a placeholder for the Java developer to implement additional logic for entity classes with this stereotype. See Section 4 for more details.
Entity Persistence. Not currently used.

An example of a provisioning model is shown in Figure 2.

Figure 2

Two Java EE web service projects would be provisioned from this model. The first project, with the name “Solicitation Management Service” will target the Glassfish application server, while the second one, named “Solicitation Owner Agency” will have JBoss as its target runtime platform. In addition, the cartridge will provision business logic placeholders for the entity classes: Response and Solicitation in the “Solicitation Management Service” project.

3 Understanding the Provisioned Project

As explained in Section 1, deployable artifacts for each participant in the SoaML model are provisioned to an Eclipse project. The contents of the projects provisioned from the example in Figure 2 are shown in Figure 3.

Figure 3

The provisioned project is an EJB web service in compliance with the JAX-WS specifications. Figure 4 shows how various elements specified in the PIM part of the SoaML model are mapped to platform specific artifacts. These artifacts are explained in details in the following sections.

Figure 4

3.1 Java Artifacts

The generated Java artifacts follow a design pattern that reflects the following principals:

The web services are implemented using the standard JAX-WS technology, including JAXB.
The cartridge does not place technology specific limitations on the model. As such, multiple inherences and the use of abstract classes on the service interfaces are allowed.
There is a clear separation of concerns between the code that handles web service contracts and the code that implements the business logic.
The class structure in the business logic (implemented in POJO) reflects the class structure of the model.

As shown in Figure 3, the provisioned Java code is organized in three source folders:

user.src contains placeholders for the developer to implement business logic. For example, custom business logic can be implemented for the service participant, for the service ports, and for the entity classes. Details about implementation of business logic are discussed in Section 4.
gen.src contains generated code that the business logic may use or refer to. Examples include the default implementation of the service interfaces, interfaces representing the data types referenced directly or indirectly referenced from the service interfaces, as well as default implementation of these data interfaces. The generated Java classes are discussed in details later.
cartridge.src contains source code used at runtime either by the cartridge or by the JAX-WS infrastructure. Examples for each code include the JAX-WS web service implementation class themselves and, in the case of two-way services, the proxies for services implementing the used interfaces. Certain runtime utility classes are also provisioned under this folder. Though we do not expect a business logic developer to have to reference any code under the cartridge.src folder, users may find it useful in providing an understanding of the provisioned application architecture.

The provisioned project also has the following folders:

lib contains runtime library file for the MDS logging utility. More information about the logging utility can be found at: https://lib.modeldriven.org/MDSLIB/trunk/logging/
wsdl contains runtime WSDLs and XML schemas.

3.1.1 Participant Classes

The JEE cartridge provisions a participant class with the same name as the participant class specified in the SoaML model. Super classes of the participant class are also provisioned. Ports of the participant are provisioned as attributes. It is expected that the user will modify the provisioned Java code to implement additional business logic. See Section 4 for more details.

Figure 5

For example, the Solicitation Management Service class shown in Figure 5 is provisioned to the following Java code:

abstract public class SolicitationManager {

… …

private SolicitationResponseInterface response =

createSolicitationResponseInterface();

… …

private SolicitationManagement solicitation =

ceateSolicitationManagement();

… …

public class SolicitationManagementService extends SolicitationManager {

private static SolicitationManagementService instance;

public static SolicitationManagementService getInstance() {

if (instance == null)

instance = new SolicitationManagementService();

return instance;

}

/**

* @modifiable

protected SolicitationManagementService() {

}

private SolicitationNotificationInterface getOwnerAgency() {

return this.getSolicitation().

getSolicitationNotificationInterface();

}

protected SolicitationManagement createSolicitationManagement() {

… …

3.1.2 Service Interfaces

Service interfaces are the port types of the service points defined on a participant. A POJO class is provisioned for each service interface.

If a service interface implements a UML interface, a Java interface is provisioned for that implemented interface.

If a service interface uses a UML interface, a Java interface is provisioned for that used interface. An attribute of the type presenting the used interface is provisioned as an attribute in the service interface class. At runtime, the infrastructure automatically injects a generated proxy implementing the used interface for the developer to use.

Figure 6

For example, the following source code is provisioned for the Solicitation Management service interface shown in Figure 6:

public class SolicitationManagement implements SolicitationManagementInterface {

// used interfaces for this port

private SolicitationNotificationInterface

solicitationNotificationInterface;

public SolicitationNotificationInterface

getSolicitationNotificationInterface() {

return solicitationNotificationInterface;

}

public void setSolicitationNotificationInterface(

SolicitationNotificationInterface _usedInterface) {

this.solicitationNotificationInterface = _usedInterface;

}

// Implemented interface Solicitation Management Interface operations

public org.modeldriven.examples.informationmodel.Solicitation

getSolicitation(

org.modeldriven.examples.messagingmodel.GetSolicitation request)

throws org.modeldriven.examples.informationmodel.RecordNotFoundException

{

… …

3.1.3 Data Types

A Java interface is provisioned for each application data type referenced directly or indirectly from the service interfaces, as well as any additional UML class with the Entity stereotype. For example, a structure shown in Figure 7 will produce the following Java classes:

Solicitation interface
SolicitationSpecification interface, with a java.util.List attribute whose element type is the LineItem interface.
LineItem interface
SolicitationType enum
RequestForQuote interface
RequestForProposal interface

Figure 7

As shown in the SolicitationManagement example above, only these interfaces, instead of concrete implementation classes, are referenced in the generated code for service interfaces. Using interfaces as the contract between the business logic implementation code and the code handling web service interface, i.e. the participant and service interface classes, allows a clean separation of concerns. At the same time, they help work around the Java language limitation that only single inheritances are allowed for concrete classes.

There are a few additional features provided for classes with Entity stereotypes:

An ID class is provisioned for the entity class. The ID class contains all the attributes with true isID tag value.
A Reference class is also provisioned for the entity class. When there is a non-aggregation association between the entity class and another class, and the association end for the entity class is navigatable, an attribute of the Reference type is created in the other class.

The following is an example of the provisioned entity interface:

public interface Solicitation extends Identifiable {

public static class ID implements java.io.Serializable {

private String solicitationId;

… …

public static class Reference implements

org.modeldriven.modelpro.soapro.util.Reference<Solicitation> {

private ID id;

public Reference() {

}

public Reference(Solicitation entity) {

this((ID) entity.id());

}

public Reference(ID id) {

this.id = id;

}

… …

The cartridge also supports a number of primitive data types, as explained in Section 5.1.

3.1.4 Data Type Implementation Classes

In addition to the interfaces, the cartridge also provides a concrete implementation class for all the data types. If a data type has multiple superclasses, such as the Woman and Minority Owned Small Business class shown in Figure 8, only the first super class in the model is provisioned using the standard Java class extension mechanism, as shown in the following example:

public class WomanAndMinorityOwnedBusiness_Impl extends

SmallAndDisadvantagedBusiness_Impl

implements Serializable, WomanAndMinorityOwnedBusiness {

… …

Figure 8

The implementation class defines a convenient operation to convert of any object implementing the message type interface to a concrete implementation class, for example, the following operation

static SmallAndDisadvantagedBusiness_Impl.from(

SmallAndDisadvantagedBusiness o)

Will take any object implementing the SmallAndDisadvantagedBusiness interface and returns an instance of a concrete implementation class, which may be a subclass of the SmallAndDisadvantagedBusiness_Impl class.

3.1.5 Exceptions

Exceptions can be specified in the UML model through the “raisedException” property of an operation. For the provisioned Java code, the following get provisioned for a raisedException:

A Java interface (As for message types)
An concrete implementation class(As for message types)
An Exception class that extends java.lang.Exception

The provisioned POJO operations for service interfaces now declare exceptions in their “throws” clause, and the provisioned web service implementation and web service proxies for used interfaces translate the exception to faults defined in the WSDL.

3.1.6 JAX-WS related classes

There are a few limitation imposed by web service technologies. For example, multiple class inheritances are not supported by the Java language and XML schemas. In addition, POJO service implementations in JAX-WS do not handle polymorphism well.

To get around these technology limitations, the data types used in JAX-WS and XML schemas flatten all inheritances through aggregation, and additional utility classes are provisioned to handle transformation between the flat object structure used in the web service implementations and the POJO interfaces, as illustrated in Figure 9. These utility classes are located under the cartridge.src folder.

Figure 9

3.2 Web Service Contract Artifacts

XML Schemas and WSDLs are provisioned. Because multiple inheritances are not supported by XML schemas, XML schemas have flat structures. The following is a segment of the XML schema provisioned for the classes shown in Figure 8:

<xsd:complexType name="SmallBusiness__Part">

<xsd:sequence>

<xsd:element name="revenue" type="xsd:double" minOccurs="1"

maxOccurs="1" />

<xsd:element name="size" type="xsd:int" minOccurs="1"

maxOccurs="1" />

</xsd:sequence>

</xsd:complexType>

<xsd:complexType name="SmallBusiness">

<xsd:sequence>

<xsd:element name="WomanAndMinorityOwnedSmallBusinessPart"

type="InformationModel1:WomanAndMinorityOwnedSmallBusiness__Part"

minOccurs="0" maxOccurs="1" />

<xsd:element name="SmallBusinessPart"

type="InformationModel1:SmallBusiness__Part"

minOccurs="1" maxOccurs="1" />

<xsd:element name="SmallAndDisadvantagedBusinessPart"

type="InformationModel1:SmallAndDisadvantagedBusiness__Part"

minOccurs="1" maxOccurs="1" />

<xsd:element name="VendorPart"

type="InformationModel1:Vendor__Part"

minOccurs="1" maxOccurs="1" />

<xsd:element name="WomanAndMinorityOwnedBusinessPart"

type="InformationModel1:WomanAndMinorityOwnedBusiness__Part"

minOccurs="0" maxOccurs="1" />

</xsd:sequence>

</xsd:complexType>

4 Implementing Business Logic for the Provisioned Project

4.1 Implementing Services and Entity Classes

The Java EE developer implements the service by modifying the generated code for the participant. For example,

protected SolicitationManagement createSolicitationManagement() {

// TODO: Override Default Behavior here

return new SolicitationManagement() {

… …

Similarly, the cartridge provisions an implementation class, under the user.src folder, for each entity class with the Entity Override stereotype. The developer overrides superclass operations in these classes to provide additional capabilities.

4.2 4.2 Calling Partner Services

If a service interfaces has dependency on a used interface, proxies are provisioned and injected into the service interface POJO code, transparent to the business logic developer.

By default, the cartridge assumes that the used interface is realized by a web service at the endpoint specified by the value of the usedInterfaceAddress tag in the provisioning model. However, this address is overridden at runtime through one of two ways:

Use WS-Addressing headers. If the partner specifies a WS-Addressing reply-to address in one of its messages, as shown in the following example,

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">

<wsa:Action>http://_jaxws.calculator.example.soapro.modelpro.modeldriven.org/Calculator/calculateRequest</wsa:Action>

<wsa:ReplyTo>

<wsa:Address>http://handlerprovider/service</wsa:Address>

<wsa:ReferenceParameters>

</wsa:ReferenceParameters>

</wsa:ReplyTo>

</soapenv:Header>

<soapenv:Body>

……

</soapenv:Body>

</soapenv:Envelope>

The reply-to address will be used for all subsequent messages.

The proxies for used interfaces implements javax.xml.ws.BindingProvider interface. The BindingProvider interface gives the user full access to the underlying JAX-WS generated web service client, making easier to dynamically configure the web service client at runtime. In the following example, the developer can specify the addresses for the partner in the Java code:

((BindingProvider) getCalculationResultHandlerInterface())

.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,

"http://someurl/");

5 Advanced Topics

5.1 Working with Primitive Data Types

ModelPro™ provisioning engine is built on a set of open source technologies, including the Eclipse Modeling Framework (EMF). In particular, ModelPro uses EMF UML2 as its metamodel. However, EMF only supports a very limited number of primitive data types, comparing to the rich set of native data types supported by both the Java programming language and XML schemas. Therefore, ModelPro includes an optional Model Library that defines a set of primitive types that can be used by the model developer. The Model Library can be accessed at http://portal.modeldriven.org/content/uml-profiles.

Figure 10

The primitive types defined in the Model Library are shown in the Figure 10. The table below explains how these types are mapped to the data types defined in the Java language and XML schemas.

Model Type	Java Type	Schema Type
Value	--	--
Number	--	--
Boolean	boolean	boolean
Integer	int	int
Byte	byte	byte
Short	short	short
Long	long	long
Natural	java.math.BigInteger	nonNegativeInteger
Real	java.math.BigDecimal	decimal
Float	float	float
Double	double	double
Decimal	java.math.BigDecimal	decimal
String	java.lang.String	string
Simple String	java.lang.String	string
Text	java.lang.String	string
Date	java.util.Calendar	dateTime
URI	java.net.URI	anyURI

The data type mapping used by ModelPro is the same as the default mapping defined in the Java Architecture for XML Binding (JAXB) specification, with the following exceptions:

JAXB maps all XML date related data types to a javax.xml.datatype.XMLGregorianCalendar class, while the Java Cartridge uses java.util.Calendar for the Date model type in the provisioned Java artifacts. This is because Cartridge assumes that the application will be developed mostly in UML with certain logic written in Java.
JAXB maps anyURI XML type to java.lang.String class while the Cartridge maps the URI model type to the java.net.URI class.

Version	Description	Author	Date
1.0	Initial Version	Model Driven Solutions	4/27/2009
1.01	Explained Primitive Type Support	Model Driven Solutions	5/1/2009