FUSE ESB Using the FUSE Services Framework Service Engine
Version 3.3 December 2007
Making Software Work Together™ Draft Draft
Using the FUSE Services Framework Service Engine IONA Technologies Version 3.3
Published 12 May 2008 Copyright © 2001-2008 IONA Technologies PLC
Trademark and Disclaimer Notice
IONA Technologies PLC and/or its subsidiaries may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this publication. Except as expressly provided in any written license agreement from IONA Technologies PLC, the furnishing of this publication does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Any rights not expressly granted herein are reserved.
IONA, IONA Technologies, the IONA logo, Orbix, High Performance Integration, Artix, FUSE, and Making Software Work Together are trademarks or registered trademarks of IONA Technologies PLC and/or its subsidiaries.
Java and J2EE are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. CORBA is a trademark or registered trademark of the Object Management Group, Inc. in the United States and other countries. All other trademarks that appear herein are the property of their respective owners.
While the information in this publication is believed to be accurate, IONA Technologies PLC makes no warranty of any kind to this material including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. IONA shall not be liable for errors contained herein, or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.
Copyright Notice
No part of this publication may be reproduced, stored in a retrieval system or transmitted, in any form or by any means, photocopying, recording or otherwise, without prior written consent of IONA Technologies PLC. No third-party intellectual property right liability is assumed with respect to the use of the information contained herein. IONA Technologies PLC assumes no responsibility for errors or omissions contained in this publication. This publication and features described herein are subject to change without notice. Portions of this document may include Apache Foundation documentation, all rights reserved. Draft Draft
Table of Contents
Introduction to the FUSE Services Framework Service Engine ...... 9 Developing a Service Using Java as a Starting Point ...... 11 Creating the SEI ...... 12 Annotating the Code ...... 15 Required Annotations ...... 16 Optional Annotations ...... 19 Developing a Service Using WSDL as a Starting Point ...... 29 Creating a Service Unit to Deploy a Service ...... 33 Using MTOM to Process Binary Content ...... 37 Using Message Interceptors ...... 39 A. Endpoint Properties ...... 41 B. Using the Maven Tooling ...... 43 Setting Up a FUSE ESB Project ...... 44 A Service Unit Project ...... 46 A Service Assembly Project ...... 47 Index ...... 49
3 4 Draft Draft
List of Tables
1. @WebService Properties ...... 16 2. @SOAPBinding Properties ...... 20 3. @WebMethod Properties ...... 21 4. @RequestWrapper Properties ...... 22 5. @ResponseWrapper Properties ...... 23 6. @WebFault Properties ...... 23 7. @WebParam Properties ...... 25 8. @WebResult Properties ...... 26 9. Optional Endpoint Attributes ...... 35 10. Elements Used to Configure an Endpoint's Interceptor Chain ...... 39 A.1. Endpoint Property Attributes ...... 41 A.2. Endpoint Property Beans ...... 41
5 6 Draft Draft
List of Examples
1. Simple SEI ...... 13 2. Simple Implementation Class ...... 14 3. Interface with the @WebService Annotation ...... 17 4. Annotated Service Implementation Class ...... 18 5. Specifying an RPC/LITERAL SOAP Binding with the @SOAPBinding Annotation ...... 20 6. SEI with Annotated Methods ...... 24 7. Fully Annotated SEI ...... 26 8. FUSE Services Framework Code Generation Command ...... 29 9. Maven Configuration for Generating Starting Point Code From WSDL ...... 30 10. JBI Descriptor for a FUSE Services Framework Service Engine Service Unit ...... 33 11. Namespace Declaration for Using FUSE Services Framework Service Engine Endpoints ...... 34 12. Simple Endpoint Configuration ...... 34 13. Adding a Jar to a Service Unit's Classpath ...... 36 14. Configuring an Endpoint to Use MTOM ...... 37 15. Method Using Binary Data ...... 38 16. Configuring an Interceptor Chain ...... 40 B.1. POM Elements for Using FUSE ESB Tooling ...... 44
7 8 Draft Draft
Introduction to the FUSE Services Framework Service Engine
Summary
The FUSE Services Framework service engine allows you to deploy JAX-WS based POJOs into the FUSE ESB and expose them as endpoints inside the ESB.
Overview The FUSE Services Framework service engine allows you to develop services as annotated POJOs and deploy them as endpoints inside the ESB. Once the services are exposed inside the ESB other ESB endpoints can access the services they provide.
When working with this service engine involves three steps:
1. Implementing your service logic as an annotated POJO.
2. Adding the needed configuration to your service unit.
3. Packaging the configuration and required jars into a service assembly for deployment.
Key features The FUSE Services Framework service engine has the following features:
• automatic WSDL generation
• jsr181 support
• JAX-WS Support
• JAXB 2.0 support
• MTOM support
• Java proxy support
Steps for working with the FUSE Using the FUSE Services Framework service engine to develop a service Services Framework service usually involves the following steps: engine
9 Draft Draft
1. Implementing the service's functionality using an annotated POJO.
If you want to start with Java code see Developing a Service Using Java as a Starting Point.
If you want to start with a WSDL contract see Developing a Service Using WSDL as a Starting Point.
2. Create a service unit to deploy the POJO into the FUSE Services Framework service engine.
See Creating a Service Unit to Deploy a Service.
3. Bundle the service unit into a service assembly so it can be deployed into the FUSE ESB container.
More information For more information about developing services using FUSE Services Framework see the FUSE Services Framework library. [http://open.iona.com/documentation/fuse-service-framework-documentation].
10 Draft Draft
Developing a Service Using Java as a Starting Point
Summary
Developing a service using a POJO is as simple as annotating your classes to add in the information needed to generate a WSDL contract.
Table of Contents
Creating the SEI ...... 12 Annotating the Code ...... 15 Required Annotations ...... 16 Optional Annotations ...... 19
11 Draft Creating the SEI Draft
Creating the SEI
The service endpoint interface (SEI) is the piece of Java code that is shared between a service implementation and the consumers that make requests on it. It defines the methods implemented by the service and provides details about how the service will be exposed as an endpoint. When starting with a WSDL contract, the SEI is generated by the code generators. However, when starting from Java, it is the up to a developer to create the SEI.
There are two basic patterns for creating an SEI:
• Green field development
You are developing a new service from the ground up. When starting fresh, it is best to start by creating the SEI first. You can then distribute the SEI to any developers that are responsible for implementing the service providers and consumers that use the SEI. Note
The recommended way to do green field service development is to start by creating a WSDL contract that defines the service and its interfaces. See Developing a Service Using WSDL as a Starting Point.
• Service enablement
In this pattern, you typically have an existing set of functionality that is implemented as a Java class and you want to service enable it. This means that you will need to do two things:
1. Create an SEI that contains only the operations that are going to be exposed as part of the service.
2. Modify the existing Java class so that it implements the SEI.
12 Draft Creating the SEI Draft
Note
You can add the JAX-WS annotations to a Java class, but that is not recommended.
Writing the interface The SEI is a standard Java interface. It defines a set of methods that a class will implement. It can also define a number of member fields and constants to which the implementing class has access.
In the case of an SEI the methods defined are intended to be mapped to operations exposed by a service. The SEI corresponds to a wsdl:portType element. The methods defined by the SEI correspond to wsdl:operation elements in the wsdl:portType element.
Tip
JAX-WS defines an annotation that allows you to specify methods that are not exposed as part of a service. However, the best practice is to leave such methods out of the SEI.
Example 1, “Simple SEI” shows a simple SEI for a stock updating service.
Example 1. Simple SEI package com.iona.demo;
public interface quoteReporter { public Quote getQuote(String ticker); }
Implementing the interface Because the SEI is a standard Java interface, the class that implements it is just a standard Java class. If you started with a Java class you will need to modify it to implement the interface. If you are starting fresh, the implementation class will need to implement the SEI.
Example 2, “Simple Implementation Class” shows a class for implementing the interface in Example 1, “Simple SEI”.
13 Draft Creating the SEI Draft
Example 2. Simple Implementation Class package com.iona.demo;
import java.util.*;
public class stockQuoteReporter implements quoteReporter { ... public Quote getQuote(String ticker) { Quote retVal = new Quote(); retVal.setID(ticker); retVal.setVal(Board.check(ticker));1 Date retDate = new Date(); retVal.setTime(retDate.toString()); return(retVal); } }
1Board is an assumed class whose implementation is left to the reader.
14 Draft Annotating the Code Draft
Annotating the Code Table of Contents Required Annotations ...... 16 Optional Annotations ...... 19
JAX-WS relies on the annotation feature of Java 5. The JAX-WS annotations are used to specify the metadata used to map the SEI to a fully specified service definition. Among the information provided in the annotations are the following:
• The target namespace for the service.
• The name of the class used to hold the request message.
• The name of the class used to hold the response message.
• If an operation is a one way operation.
• The binding style the service uses.
• The name of the class used for any custom exceptions.
• The namespaces under which the types used by the service are defined. Tip
Most of the annotations have sensible defaults and do not need to be specified. However, the more information you provide in the annotations, the better defined your service definition. A solid service definition increases the likelihood that all parts of a distributed application will work together.
15 Draft Required Annotations Draft
Required Annotations
In order to create a service from Java code you are only required to add one annotation to your code. You must add the @WebService() annotation on both the SEI and the implementation class.
The @WebService annotation The @WebService annotation is defined by the javax.jws.WebService interface and it is placed on an interface or a class that is intended to be used as a service. @WebService has the following properties:
Table 1. @WebService Properties
Property Description name Specifies the name of the service interface. This property is mapped to the name attribute of the wsdl:portType element that defines the service's interface in a WSDL contract. The default is to append PortType to the name of the implementation class. a targetNamespace Specifies the target namespace under which the service is defined. If this property is not specified, the target namespace is derived from the package name. serviceName Specifies the name of the published service. This property is mapped to the name attribute of the wsdl:service element that defines the published service. The default is to use the name of the service's implementation class. a wsdlLocation Specifies the URI at which the service's WSDL contract is stored. The default is the URI at which the service is deployed. endpointInterface Specifies the full name of the SEI that the implementation class implements. This property is only used when the attribute is used on a service implementation class. portName Specifies the name of the endpoint at which the service is published. This property is mapped to the name attribute of the wsdl:port element that specifies the endpoint details for a published service. The default is the append Port to the name of the service's implementation class. a aWhen you generate WSDL from an SEI the interface's name is used in place of the implementation class' name.
16 Draft Required Annotations Draft
Tip
You do not need to provide values for any of the @WebService annotation's properties. However, it is recommended that you provide as much information as you can.
Annotating the SEI The SEI requires that you add the @WebService annotation. Since the SEI is the contract that defines the service, you should specify as much detail as you can about the service in the @WebService annotation's properties.
Example 3, “Interface with the @WebService Annotation” shows the interface defined in Example 1, “Simple SEI” with the @WebService annotation.
Example 3. Interface with the @WebService Annotation package com.iona.demo; import javax.jws.*;
@WebService(name="quoteUpdater", ❶ targetNamespace="http:\\demos.iona.com", ❷ serviceName="updateQuoteService", ❸ wsdlLocation="http:\\demos.iona.com\quoteExampleService?wsdl", ❹ portName="updateQuotePort") ❺ public interface quoteReporter { public Quote getQuote(String ticker); }
The @WebService annotation in Example 3, “Interface with the @WebService Annotation” does the following:
❶ Specifies that the value of the name attribute of the wsdl:portType element defining the service interface is quoteUpdater. ❷ Specifies that the target namespace of the service is http:\\demos.iona.com. ❸ Specifies that the value of the name of the wsdl:service element defining the published service is updateQuoteService.
17 Draft Required Annotations Draft
❹ Specifies that the service will publish its WSDL contract at http:\\demos.iona.com\quoteExampleService?wsdl. ❺ Specifies that the value of the name attribute of the wsdl:port element defining the endpoint exposing the service is updateQuotePort.
Annotating the service In addition to annotating the SEI with the @WebService annotation, you also implementation have to annotate the service implementation class with the @WebService annotation. When adding the annotation to the service implementation class you only need to specify the endpointInterface property. As shown in Example 4, “Annotated Service Implementation Class” the property needs to be set to the full name of the SEI.
Example 4. Annotated Service Implementation Class package org.eric.demo;
import javax.jws.*;
@WebService(endpointInterface="com.iona.demo.quoteReporter") public class stockQuoteReporter implements quoteReporter { public Quote getQuote(String ticker) { ... } }
18 Draft Optional Annotations Draft
Optional Annotations
While the @WebService annotation is sufficient for service enabling a Java interface or a Java class, it does not provide a lot of information about how the service will be exposed as a service provider. The JAX-WS programming model uses a number of optional annotations for adding details about your service, such as the binding it uses, to the Java code. You add these annotations to the service's SEI. Tip
The more details you provide in the SEI the easier it will be for developers to implement applications that can use the functionality it defines. It will also provide for better generated WSDL contracts. Defining the Binding Properties with Annotations
If you are using a SOAP binding for your service, you can use JAX-WS annotations to specify a number of the bindings properties. These properties correspond directly to the properties you can specify in a service's WSDL contract.
The @SOAPBinding annotation The @SOAPBinding annotation is defined by the javax.jws.soap.SOAPBinding interface. It provides details about the SOAP binding used by the service when it is deployed. If the @SOAPBinding annotation is not specified, a service is published using a wrapped doc/literal SOAP binding.
You can put the @SOAPBinding annotation on the SEI and any of the SEI's methods. When it is used on a method, setting of the method's @SOAPBinding annotation take precedent.
Table 2, “@SOAPBinding Properties” shows the properties for the @SOAPBinding annotation.
19 Draft Optional Annotations Draft
Table 2. @SOAPBinding Properties
Property Values Description style Style.DOCUMENT (default) Specifies the style of the SOAP message. If RPC style is specified, each message part within the SOAP body is a parameter or return Style.RPC value and will appear inside a wrapper element within the soap:body element. The message parts within the wrapper element correspond to operation parameters and must appear in the same order as the parameters in the operation. If DOCUMENT style is specified, the contents of the SOAP body must be a valid XML document, but its form is not as tightly constrained. use Use.LITERAL (default) Specifies how the data of the SOAP message is streamed.
Use.ENCODED parameterStylea ParameterStyle.BARE Specifies how the method parameters, which correspond to message parts in a WSDL contract, are placed into the SOAP message body. ParameterStyle.WRAPPED A parameter style of BARE means that each parameter is placed (default) into the message body as a child element of the message root. A parameter style of WRAPPED means that all of the input parameters are wrapped into a single element on a request message and that all of the output parameters are wrapped into a single element in the response message. aIf you set the style to RPC you must use the WRAPPED parameter style.
Example 5, “Specifying an RPC/LITERAL SOAP Binding with the @SOAPBinding Annotation” shows an SEI that uses rpc/literal SOAP messages.
Example 5. Specifying an RPC/LITERAL SOAP Binding with the @SOAPBinding Annotation
package org.eric.demo;
import javax.jws.*; import javax.jws.soap.*; import javax.jws.soap.SOAPBinding.*;
@WebService(name="quoteReporter") @SOAPBinding(style=Style.RPC, use=Use.LITERAL) public interface quoteReporter {
20 Draft Optional Annotations Draft
... }
Defining Operation Properties with Annotations
When the runtime maps your Java method definitions into XML operation definitions it fills in details such as:
• what the exchanged messages look like in XML.
• if the message can be optimized as a one way message.
• the namespaces where the messages are defined.
The @WebMethod annotation The @WebMethod annotation is defined by the javax.jws.WebMethod interface. It is placed on the methods in the SEI. The @WebMethod annotation provides the information that is normally represented in the wsdl:operation element describing the operation to which the method is associated.
Table 3, “@WebMethod Properties” describes the properties of the @WebMethod annotation.
Table 3. @WebMethod Properties
Property Description operationName Specifies the value of the associated wsdl:operation element's name. The default value is the name of the method. action Specifies the value of the soapAction attribute of the soap:operation element generated for the method. The default value is an empty string. exclude Specifies if the method should be excluded from the service interface. The default is false.
The @RequestWrapper The @RequestWrapper annotation is defined by the annotation javax.xml.ws.RequestWrapper interface. It is placed on the methods in
21 Draft Optional Annotations Draft
the SEI. As the name implies, @RequestWrapper specifies the Java class that implements the wrapper bean for the method parameters that are included in the request message sent in a remote invocation. It is also used to specify the element names, and namespaces, used by the runtime when marshalling and unmarshalling the request messages.
Table 4, “@RequestWrapper Properties” describes the properties of the @RequestWrapper annotation.
Table 4. @RequestWrapper Properties
Property Description localName Specifies the local name of the wrapper element in the XML representation of the request message. The default value is the name of the method or the value of the @WebMethod annotation's operationName property.
targetNamespace Specifies the namespace under which the XML wrapper element is defined. The default value is the target namespace of the SEI. className Specifies the full name of the Java class that implements the wrapper element.
Tip
Only the className property is required.
The @ResponseWrapper The @ResponseWrapper annotation is defined by the annotation javax.xml.ws.ResponseWrapper interface. It is placed on the methods in the SEI. As the name implies, @ResponseWrapper specifies the Java class that implements the wrapper bean for the method parameters that are included in the response message sent in a remote invocation. It is also used to specify the element names, and namespaces, used by the runtime when marshalling and unmarshalling the response messages.
Table 5, “@ResponseWrapper Properties” describes the properties of the @ResponseWrapper annotation.
22 Draft Optional Annotations Draft
Table 5. @ResponseWrapper Properties
Property Description localName Specifies the local name of the wrapper element in the XML representation of the response message. The default value is the name of the method with Response appended or the value of the @WebMethod annotation's operationName property with Response appended.
targetNamespace Specifies the namespace under which the XML wrapper element is defined. The default value is the target namespace of the SEI. className Specifies the full name of the Java class that implements the wrapper element.
Tip
Only the className property is required.
The @WebFault annotation The @WebFault annotation is defined by the javax.xml.ws.WebFault interface. It is placed on exceptions that are thrown by your SEI. The @WebFault annotation is used to map the Java exception to a wsdl:fault element. This information is used to marshall the exceptions into a representation that can be processed by both the service and its consumers.
Table 6, “@WebFault Properties” describes the properties of the @WebFault annotation.
Table 6. @WebFault Properties
Property Description name Specifies the local name of the fault element. targetNamespace Specifies the namespace under which the fault element is defined. The default value is the target namespace of the SEI. faultName Specifies the full name of the Java class that implements the exception.
23 Draft Optional Annotations Draft
Important
The name property is required.
The @OneWay annotation The @OneWay annotation is defined by the javax.jws.OneWay interface. It is placed on the methods in the SEI that will not require a response from the service. The @OneWay annotation tells the run time that it can optimize the execution of the method by not waiting for a response and not reserving any resources to process a response.
Example Example 6, “SEI with Annotated Methods” shows an SEI whose methods are annotated.
Example 6. SEI with Annotated Methods package com.iona.demo; import javax.jws.*; import javax.xml.ws.*;
@WebService(name="quoteReporter") public interface quoteReporter { @WebMethod(operationName="getStockQuote") @RequestWrapper(targetNamespace="http://demo.iona.com/types", className="java.lang.String") @ResponseWrapper(targetNamespace="http://demo.iona.com/types", className="org.eric.demo.Quote") public Quote getQuote(String ticker); }
Defining Parameter Properties with Annotations
The method parameters in the SEI coresspond to the wsdl:message elements and their wsdl:part elements. JAX-WS provides annotations that allow you to describe the wsdl:part elements that are generated for the method parameters.
The @WebParam annotation The @WebParam annotation is defined by the javax.jws.WebParam interface. It is placed on the parameters on the methods defined in the SEI. The @WebParam annotation allows you to specify the direction of the parameter,
24 Draft Optional Annotations Draft
if the parameter will be placed in the SOAP header, and other properties of the generated wsdl:part.
Table 7, “@WebParam Properties” describes the properties of the @WebParam annotation.
Table 7. @WebParam Properties
Property Values Description name Specifies the name of the parameter as it appears in the WSDL. For RPC bindings, this is name of the wsdl:part representing the parameter. For document bindings, this is the local name of the XML element representing the parameter. Per the JAX-WS specification, the default is argN, where N is replaced with the zero-based argument index (i.e., arg0, arg1, etc.). targetNamespace Specifies the namespace for the parameter. It is only used with document bindings where the parameter maps to an XML element. The defaults is to use the service's namespace. mode Mode.IN (default) Specifies the direction of the parameter.
Mode.OUT
Mode.INOUT header false (default) Specifies if the parameter is passed as part of the SOAP header.
true partName Specifies the value of the name attribute of the wsdl:part element for the parameter when the binding is document.
The @WebResult annotation The @WebResult annotation is defined by the javax.jws.WebResult interface. It is placed on the methods defined in the SEI. The @WebResult annotation allows you to specify the properties of the generated wsdl:part that is generated for the method's return value.
Table 8, “@WebResult Properties” describes the properties of the @WebResult annotation.
25 Draft Optional Annotations Draft
Table 8. @WebResult Properties
Property Description name Specifies the name of the return value as it appears in the WSDL. For RPC bindings, this is name of the wsdl:part representing the return value. For document bindings, this is the local name of the XML element representing the return value. The default value is return.
targetNamespace Specifies the namespace for the return value. It is only used with document bindings where the return value maps to an XML element. The defaults is to use the service's namespace. header Specifies if the return value is passed as part of the SOAP header. partName Specifies the value of the name attribute of the wsdl:part element for the return value when the binding is document.
Example Example 7, “Fully Annotated SEI” shows an SEI that is fully annotated.
Example 7. Fully Annotated SEI package com.iona.demo; import javax.jws.*; import javax.xml.ws.*; import javax.jws.soap.*; import javax.jws.soap.SOAPBinding.*; import javax.jws.WebParam.*;
@WebService(targetNamespace="http://demo.iona.com", name="quoteReporter") @SOAPBinding(style=Style.RPC, use=Use.LITERAL) public interface quoteReporter { @WebMethod(operationName="getStockQuote") @RequestWrapper(targetNamespace="http://demo.iona.com/types", className="java.lang.String") @ResponseWrapper(targetNamespace="http://demo.iona.com/types", className="org.eric.demo.Quote") @WebResult(targetNamespace="http://demo.iona.com/types", name="updatedQuote")
26 Draft Optional Annotations Draft
public Quote getQuote( @WebParam(targetNamespace="http://demo.iona.com/types", name="stockTicker", mode=Mode.IN) String ticker ); }
27 28 Draft Draft
Developing a Service Using WSDL as a Starting Point
Summary
FUSE ESB provides Maven tools that allow you to generate the required stub code from a WSDL file. You simply need to provide the application logic to implement your service.
Overview When starting with a WSDL file, ,you need to generate the stub code for your service. You may also need to generate the starting point code for your service. To generate the required code you have two options:
• use the FUSE Services Framework wsdltojava tool
• use the wsdl2java goal of the Maven Apache CXF code generation plug-in
Once the stub code is generated, you can implement your service's logic and deploy it.
Using the FUSE Services If you have a copy of FUSE Services Framework, or Apache CXF, installed on Framework code generation tool your system, you can use the wsdl2java tool to generate the stub code and the starting point code. Example 8, “FUSE Services Framework Code Generation Command” shows the command and the options to use.
Example 8. FUSE Services Framework Code Generation Command
wsdl2java -impl -d outDir myService.wsdl
The -impl flag tells the tool to generate the starting point code for your implementation. The -d outDir flag tells the tool the name of the folder into the generated code is written. Important
FUSE ESB 3.3 only supports FUSE Services Framework 2.0.x or Apache CXF 2.0.x.
29 Draft Draft
For more information about using the FUSE Services Framework tooling see the FUSE Services Framework library. [http://open.iona.com/documentation/fuse-service-framework-documentation].
Using the Maven tools Even if you do not have FUSE Services Framework or Apache CXF installed, you can generate the required Java classes using the Maven tooling. You need to include the Apache CXF code generation plug-in in your project file and configure it to use the wsdl2java goal.
Example 9, “Maven Configuration for Generating Starting Point Code From WSDL” shows the XML needed to configure the Apache CXF code generate plug-in to generate the stubs and starting point code.
Example 9. Maven Configuration for Generating Starting Point Code From WSDL
...
30 Draft Draft
...
The Maven POM fragment shown in Example 9, “Maven Configuration for Generating Starting Point Code From WSDL” does the following:
❶ Specifies that the Apache CXF code generation plug-in is to be loaded. ❷ Specifies the version of the Apache CXF code generation plug-in to use. Important
FUSE ESB only supports version 2.0.x of Apache CXF.
❸ Specifies that the plug-in is run during the generate-sources phase of a project build. You evoke the generate-sources phases using the mvn generate-sources command. ❹ Specifies the directory into which the generated source files will be placed. ❺ Specifies the path to the WSDL file from which the source code will be generated. ❻ Specifies that a starting point implementation class is to be generated. ❼ Specifies that the Apache CXF code generation plug-in will use its wsdl2java goal.
Generated code The implementation code consists of two files:
• portTypeName.java is the service interface(SEI) for the service.
• portTypeNameImpl.java is the class you will use to implement the operations defined by the service.
Implement the operation's logic You provide the business logic for your service's operations by completing the stub methods in portTypeNameImpl.java. For the most part, you use standard Java to implement the business logic. If your service uses custom XML Schema types, you will need to use the generated classes for each type to manipulate them. There are also some FUSE Services Framework specific APIs that you can use to access some advanced features.
31 32 Draft Draft
Creating a Service Unit to Deploy a Service
Summary
In order for your service to be deployed as an endpoint in the ESB, you must package it into a service unit. The service unit contains the configuration needed by the ESB to load the service and expose it as an endpoint.
Overview All endpoints deployed into FUSE ESB must be packaged in a JBI service unit. The service unit configures the FUSE Services Framework service engine to load the jars that implements your service. It also determines if the service can handle MTOM attachments.
Contents of a FUSE Services A service unit that configures the FUSE Services Framework service engine Framework service engine service will contain at least three things: unit xbean.xml configuration file
The xbean.xml file contains the XML configuration for the endpoint defined by the service unit. The contents of this file are the focus of Defining the service's endpoint. Note
The service unit can define more than one endpoint.
meta-inf/jbi.xml
The jbi.xml file is the JBI descriptor for the service unit. Example 10, “JBI Descriptor for a FUSE Services Framework Service Engine Service Unit” shows a JBI descriptor for a FUSE Services Framework service engine service unit.
Example 10. JBI Descriptor for a FUSE Services Framework Service Engine Service Unit
33 Draft Draft
service implementation class files All of the classes needed to implement the service(s) being deployed need to be included in the service unit. These can either be stored as class files or bundled into jar files. This is discussed in Including the class files
The service unit may also contain a WSDL document describing the service.
Namespace The elements used to configure FUSE Services Framework service engine endpoints are defined in the http://servicemix.apache.org/cxfse/1.0 namespace. You will need to add a namespace declaration similar to the one in Example 11, “Namespace Declaration for Using FUSE Services Framework Service Engine Endpoints” to your xbeans.xml file's beans element.
Example 11. Namespace Declaration for Using FUSE Services Framework Service Engine Endpoints
Defining the service's endpoint The configuration that tells the service engine to load a service's implementation and expose it as an endpoint is specified in the service unit's xbean.xml file. It will contain one endpoint element for each service implementation being exposed.
The endpoint element requires the use of the pojo attribute. The pojo attribute's value is a reference to a bean element configuring the service's implementation class. Example 12, “Simple Endpoint Configuration” shows a simple FUSE Services Framework configuration.
Example 12. Simple Endpoint Configuration
34 Draft Draft
Note
You can also configure the endpoint's implementation class using a pojo child element. The pojo element wraps the bean element configuring the service's implementation class.
By default, the service, endpoint, and interface names are determined from the service implementation. The endpoint element also has optional attributes that allow you to override the determined names. Table 9, “Optional Endpoint Attributes” describe these attributes.
Table 9. Optional Endpoint Attributes
Name Description service Specifies the QName of the service containing the endpoint. endpoint Specifies the name used by the endpoint.
interfaceName Specifies the QName of the interface implemented by the endpoint.
Including the class files You can include the implementation of your service in one of two ways: plain class files or bundled into jar files.
If you chose to use class files, the root folder of your hierarchy is the root of the exploded service unit. All of the class files must be placed into a folder hierarchy that matches the package structure of your code. For example the class file for the class com.widgetVendor.demo.GreenWidgetServiceImpl would be stored in /com/widgetVendor/demo/GreenWidgetServiceImpl.class.
If you chose to use jar files, you will need to add the jars to the classpath used by the service unit. This is done by adding a classpath element to the service unit's configuration file. The classpath element contains one or more location elements. The location elements specify the jars to be added to the classpath. Example 13, “Adding a Jar to a Service Unit's Classpath” shows an example that adds foo/lib.jar to the service unit's classpath.
35 Draft Draft
Example 13. Adding a Jar to a Service Unit's Classpath
36 Draft Draft
Using MTOM to Process Binary Content
Summary
Enabling MTOM support allows your service implementation to consume an produce messages that contain binary data.
Overview SOAP Message Transmission Optimization Mechanism (MTOM) specifies an optimized method for sending binary data as part of a SOAP message using the XML-binary Optimized Packaging (XOP) packages for transmitting binary data. The FUSE Services Framework service engine supports the use of MTOM to send and receive binary data. MTOM support is enabled on an endpoint by endpoint basis.
Configuring an endpoint to As shown in Example 14, “Configuring an Endpoint to Use MTOM”, you support MTOM configure an endpoint to support MTOM by setting its mtomEnabled attribute to true.
Example 14. Configuring an Endpoint to Use MTOM
Using MTOM in a service MTOM is supported for the following classes: implementation • DataSource
• DataHandler
• byte[]
Example 15, “Method Using Binary Data” shows a method for an operation that uses binary data.
37 Draft Draft
Example 15. Method Using Binary Data public String echo(String msg, DataHandler binary) { ... }
38 Draft Draft
Using Message Interceptors
Summary
You can use low-level message interceptors to process messages before they are delivered to your endpoint's service implementation.
Overview Interceptors are a low-level pieces of code that process messages as they are passed between the message channel and service's implementation. They have access to the raw message data and can be used to process SOAP action entries, process security tokens, or correlate messages. Interceptors are called in a chain and you can configure what interceptors are used at a number of points along the chain.
Configuring an endpoint's A FUSE Services Framework service engine endpoint's interceptor chain has interceptor chain four points at which you can insert an interceptor:
• in interceptors process messages when they are received from the NMR
• in fault interceptors process fault messages that are generated before the service implementation gets called
• out interceptors process messages as they pass from the service implementation to the NMR
• out fault interceptors process fault messages that are generated by the service implementation or by an out interceptor
An endpoint's interceptor chain is configured using children of its endpoint element. Table 10, “Elements Used to Configure an Endpoint's Interceptor Chain” lists the elements used to configure an endpoint's interceptor chain.
Table 10. Elements Used to Configure an Endpoint's Interceptor Chain
Name Description inInterceptors Specifies a list of interceptors that process incoming messages. inFaultInterceptors Specifies a list of interceptors that process incoming fault messages.
39 Draft Draft
Name Description outInterceptors Specifies a list of interceptors that process outgoing messages. outFaultInterceptors Specifies a list of interceptors that process outgoing fault messages.
Example 16, “Configuring an Interceptor Chain” shows an endpoint configured to use the FUSE Services Framework logging interceptors.
Example 16. Configuring an Interceptor Chain
Implementing an interceptor You can implement a custom interceptor by extending the org.apache.cxf.phase.AbstractPhaseInterceptor class or one of its sub-classes. Extending AbstractPhaseInterceptor provides you with access to the generic message handling APIs used by FUSE Services Framework. Extending one of the sub-classes provides you with more specific APIs. For example, extending the AbstractSoapInterceptor class allows your interceptor to work directly with the SOAP APIs.
More information For more information about writing FUSE Services Framework interceptors see the Apache CXF documentation [http://cwiki.apache.org/CXF20DOC/interceptors.html].
40 Draft Draft
Appendix A. Endpoint Properties Attributes The attributes described in Table A.1, “Endpoint Property Attributes” are used to configure a FUSE Services Framework service engine endpoint.
Table A.1. Endpoint Property Attributes
Name Type Description Required endpoint string Specifies a the name of the endpoint no (defaults to the value determined by the exposed to the ESB. POJO's annotations) interfaceName QName Specifies the interface name of the endpoint. no (defaults to the value determined by the POJO's annotations) service QName Specifies the service name of the endpoint. no (defaults to the value determined by the POJO's annotations) mtomEnabled boolean Specifies if the service can consume MTOM no (defaults to false) formatted binary data.
Beans The elements described in Table A.2, “Endpoint Property Beans” are used to configure an endpoint.
Table A.2. Endpoint Property Beans
Name Type Description Required pojo Object Specifies the class yes implementing the service provided by the endpoint. inInterceptors org.apache.cxf.phase.PhaseInterceptor Specifies a list of no interceptors that process incoming messages. inFaultInterceptors org.apache.cxf.phase.PhaseInterceptor Specifies a list of no interceptors that process incoming fault messages. outInterceptors org.apache.cxf.phase.PhaseInterceptor Specifies a list of no interceptors that process outgoing messages.
41 Draft Draft
Name Type Description Required outFaultInterceptors org.apache.cxf.phase.PhaseInterceptor Specifies a list of no interceptors that process outgoing fault messages.
42 Draft Draft
Appendix B. Using the Maven Tooling
Table of Contents
Setting Up a FUSE ESB Project ...... 44 A Service Unit Project ...... 46 A Service Assembly Project ...... 47
43 Draft Setting Up a FUSE ESB Project Draft
Setting Up a FUSE ESB Project Setting up the Maven tools In order to use the FUSE ESB Maven tooling, you add the elements shown in Example B.1, “POM Elements for Using FUSE ESB Tooling” to your POM file.
Example B.1. POM Elements for Using FUSE ESB Tooling ...
44 Draft Setting Up a FUSE ESB Project Draft
These elements point Maven to the correct repositories to download the FUSE ESB Maven tooling and load the plug-in that implements the tooling.
45 Draft A Service Unit Project Draft
A Service Unit Project
46 Draft A Service Assembly Project Draft
A Service Assembly Project
47 48 Draft Draft
wsdlLocation property, 16 Index A annotations Symbols @OneWay (see @OneWay) @OneWay, 24 @RequestWrapper (see @RequestWrapper) @RequestWrapper, 21 @ResponseWrapper (see @ResponseWrapper) className property, 22 @SOAPBinding (see @SOAPBinding) localName property, 22 @WebFault (see @WebFault) targetNamespace property, 22 @WebMethod (see @WebMethod) @ResponseWrapper, 22 @WebParam (see @WebParam) className property, 23 @WebResult (see @WebResult) localName property, 23 @WebService (see @WebService) targetNamespace property, 23 @SOAPBinding, 19 parameterStyle property, 20 C style property, 20 classpath, 35 use property, 20 code generation @WebFault, 23 Apache CXF tools, 29 faultName property, 23 FUSE Services Framework tools, 29 name property, 23 Maven tools, 30 targetNamespace property, 23 @WebMethod, 21 E action property, 21 endpoint, 34 exclude property, 21 endpoint, 35 operationName property, 21 interfaceName, 35 @WebParam, 24 mtomEnabled, 37 header property, 25 pojo, 34 mode property, 25 service, 35 name property, 25 partName property, 25 targetNamespace property, 25 G generated code @WebResult, 25 service implementation, 31 header property, 26 name property, 26 partName property, 26 I targetNamespace property, 26 implementation @WebService, 16 SEI, 13 endpointInterface property, 16 service operations, 13, 31 name property, 16 inFaultInterceptors, 39 portName property, 16 inInterceptors, 39 serviceName property, 16 targetNamespace property, 16
49 Draft Draft
J jbi.xml, 33 M Maven tooling set up, 44 N namespace, 34 O outFaultInterceptors, 40 outInterceptors, 40 P pojo, 34 S SEI, 12 annotating, 15 creating, 13 creation patterns, 12 relationship to wsdl:portType, 13 required annotations, 17 service implementing the operations, 31 service enablement, 12 service endpoint interface (see SEI) service implementation operations, 13 required annotations, 18 W wsdl2java, 29 wsdl:portType, 13 X xbean.xml, 33, 34
50