Anyframe CXF JAX-WS Plugin

Anyframe CXF JAX-WS PluginVersion 4.5.3Copyright © 2007-2010 Samsung SDSThe copyright of this document is the property of Samsung SDS.Permission is granted to use this document for free only forthe purpose of open source community activity. The copyrightholder should be clearly stated in case this document is copied ordistributed, and changed contents should be specified. Permission isnot granted for the commercial use of the modification of the originaldocument. Should there be parts considered to have errors in thisdocument, please register the issue for which we will take properaction.

I. Installation ................................................................................................................ 11. Install a CXF JAX-WS Plugin ................................................................................. 2II. Web Services ............................................................................................................ 32. Overview .......................................................................................................... 42.1. Web Services Concept ............................................................................. 42.1.1. Architecture ................................................................................. 42.1.2. SOAP (Simple Object Access Protocol) .............................................. 42.1.3. WSDL (Web Services Description Language) ....................................... 52.1.4. Technical standards ...................................................................... 62.2. Implementation Technology ....................................................................... 72.2.1. JAX-RPC vs. JAX-WS ...................................................................... 72.2.2. XML Schema ............................................................................... 82.2.3. Other implementation descriptions ................................................... 92.3. Web Services Framework .......................................................................... 92.3.1. Web Services Framework type ......................................................... 92.3.2. The Characteristics of Apache CXF ................................................. 102.4. Tools ................................................................................................. 113. Databinding .................................................................................................... 123.1. JAXB Databinding .................................................................................. 123.1.1. Server Configuration .................................................................... 133.1.2. Notes ....................................................................................... 143.2. MTOM Databinding ................................................................................ 153.2.1. Server Configuration .................................................................... 153.2.2. Client Configuration ..................................................................... 173.2.3. References - Contents related to MTOM .......................................... 173.3. Resources ........................................................................................... 184. JAX-WS Frontend .............................................................................................. 194.1. Developing Web Service ......................................................................... 204.1.1. Samples ................................................................................... 204.2. Spring Configuration XML - Use jaxws:endpoint tag ....................................... 214.2.1. Samples ................................................................................... 214.3. Server: Using JAX-WS Frontend API ........................................................... 224.3.1. Samples ................................................................................... 234.4. Spring Configuration XML - Using jaxws:client tag ......................................... 234.4.1. Samples ................................................................................... 234.5. Client: Using JAX-WS Frontend API ............................................................ 244.5.1. Samples ................................................................................... 244.6. Defining annotation ............................................................................... 244.6.1. @WebService (javax.jws.WebService) ............................................... 254.6.2. @WebParam (javax.jws.WebParam) ................................................. 264.6.3. @WebMethod (javax.jws.WebMethod) .............................................. 274.6.4. @OneWay (javax.jws.OneWay) ........................................................ 274.6.5. @WebResult (javax.jws.WebResult) ................................................. 274.6.6. Samples ................................................................................... 274.7. Resources ........................................................................................... 295. Asynchronous Invocation ................................................................................... 305.1. Server Configuration .............................................................................. 305.1.1. Samples ................................................................................... 305.2. Client Configuration ............................................................................... 335.2.1. Samples ................................................................................... 335.3. Resources ........................................................................................... 356. WAS(Web Application Server) Configuration ........................................................... 366.1. Tomcat ............................................................................................... 366.1.1. 5.5.23, 6.0.x, 7.0.x .................................................................... 366.2. JEUS .................................................................................................. 36ii

Anyframe CXF JAX-WS Plugin6.2.1. 5.0 .......................................................................................... 366.2.2. 6.0 .......................................................................................... 366.3. WebLogic ............................................................................................. 376.3.1. 9.2 .......................................................................................... 376.3.2. 10.1 ........................................................................................ 386.3.3. 10.3.3 ..................................................................................... 39iii

I.InstallationThere are various open source frameworks frequently used to implement Web Service which include Apache CXF,Apache Axis/Axis2, and Spring Web Services. cxf-jaxws plugin consists of sample code that provides basic guidelineson how to use Apache CXF [http://cxf.apache.org/] and reference library to use this open source.

1.Install a CXF JAX-WS PluginThis chapter describes how to implement Web Service using CXF, centered on sample code created bycxf-jaxws plugin installation.Let's start with installing Cxf-jaxws plugin on your local PC.1. To install Cxf-jaxws plugin, Foundation Plugin which is the base of allplugins should be installed. If you need to install Foundation Plugin, go toInstall Foundation Plugin [http://dev.anyframejava.org/docs.en/anyframe/plugin/foundation/4.6.1/reference/htmlsingle/foundation.html#foundation_installation].2. After moving to sample project on the command window, start sample DB by executing db/hsqldb/start.cmd (or start.sh). (If you wish to use another DB instead of HsqlDB which is basically provided,go to Change DB [http://dev.anyframejava.org/docs.en/anyframe/ide/1.0.1/reference/htmlsingle/ide.html#cli_maven_db] in Anyframe IDE Manual.)3. Enter the following command in the command window to install cxf-jaxws plugin.mvn anyframe:install -DpluginName=cxf-jaxws4. Enter the following command in the command window, and when the Jetty Server starts, check ifcxf-jaxws plugin is installed properly through browser. (Enter http://localhost:8080/myproject in thebrowser address box if the created sample project name is myproject.)mvn clean jetty:runAs seen in the figure above, a CXF-JAXWS Sample menu has been created other than the Foundationsample menu on the left menu bar. (You will see CXF-JAXWS Sample instead of the CXF Samplemenu shown in the figure above.) Click CXF-JAXWS Sample menu and check the execution of list anddetailed search and the creation of WSDL through web service implemented as CXF.Notice for each WAS (Web Application Server)This document describes Jetty and Tomcat as WAS for executing sample applicationcreated by Plugin installation. However, as the sample application created by Plugininstallation is not dependent on a specific WAS, it is possible to deploy and execute otherWAS such as WebLogic and JEUS after packaging through executing command such as"mvn clean compile war:war". However, there are cases when library version referred toby sample application is not supported by relevant WAS. In this case, refer to WAS(WebApplication Server) Configuration.2

II.Web ServicesAnyframe provides Web Service using Apache CXF 2.3.0 version.Web Service interacts previous application system as standard technology through Internet network, and makes allbusinesses possible using this standard technology.Web Service provides information and services anytime, anywhere. It does not define perfectly like other previoussoftware and but confirms the definition of exchanged data standard to perform as a link to overcome thecommunications differences between a very flexible and heterogeneous operation system and heterogeneousprogram language.Web Service Architecture Working Group. W3C [http://www.w3.org/2002/ws/arch/] (Web Services Glossary, WebServices Architecture, etc. data search) defines Web Services as the following."A Web service is a software system designed to support interoperable machine-to-machineinteraction over a network. It has an interface described in a machine-processable format(specifically WSDL). Other systems interact with the Web Service in a manner prescribed byits description using SOAP-messages, typically conveyed using HTTP with an XMLserializationin conjunction with other Web-related standards."

2.Overview2.1.Web Services Concept2.1.1.ArchitectureWeb Service is a technology that is implemented according to an architecture model composed of threeroles (Service Provider, Service Broker, Service Consumer).• The three roles of Web ServiceRoleService ProviderService Broker (ServiceRegistry)Service Consumer (ServiceRequester)• Web Service ScenarioDescriptionProvides service that implements a certain service spec.Connects service that Service Provider provides with ServiceConsumer through service registration and search, save, andmanagement.Finds a specific service through Service Broker, and requests therelated service from Service Provider.Procedure Role Description1 Service Provider Create a WSDL file containing your business information,service information to be provided, and how to use thisinformation.2 Service Provider Register your service WSDL in UDDI registry. A specific IDbased on UUID will be provided for registered services.3 Service Consumer Searches services from UDDI registry through varioussearch terms such as classification and identificationsystems. When the related service is found, the WSDL fileof the service is received.4 Service Consumer Provided with service connecting with Service Provider usingWSDL information. Execution results are received in XMLformat using SOAP.• Three basic description factors of Web ServicesDescriptionfactorsWSDLSOAPUDDIDescriptionLanguage that expresses and describes Web Services (service expression)Message protocol used in Web Service that is universal and scalable (datacommunication protocol)Web Service registry to search services (service registration, search)2.1.2.SOAP (Simple Object Access Protocol)SOAP(Simple Object Access Protocol) is a protocol that uses HTTP, HTTPS, SMTP, etc. to exchangeXML-based SOAP message on computer network. It is a basic means of message transmission in4

OverviewWeb Service. A structure that consists of envelope/header/body, transport, and a interaction neutralityconcept have been introduced in XML-RPC and WDDX.• SOAP Message StructureSOAP message has Envelope as route factor, and has SOAP Header and Body as sub-factors. SOAPmessage structure is based on XML and is designed in a pattern that combines Header and Body.The contents of messages to be transmitted are stated in Body (mandatory). (Header is optional.)• The Characteristics of SOAPMeritsDescription1 SOAP generally runs based on HTTP, so communication is easy without beingblocked by proxy or firewall like HTTP.2 SOAP can use transmission protocols other that HTTP which is standardprotocol.3 Independent of platform or programming language.4 Simple, can be extended, and supports SOAP XML message that integratesattachments (using multipart MIME structure).DemeritsDescription1 Slow compared to middleware technology such as CORBA because it iscomposed in XML format tag. (In large part, this problem has been solved dueto the rapid development of network speed and performance optimization.)2.1.3.WSDL (Web Services Description Language)WSDL(Web Services Description Language) is makeup language based on XML for describing informationon services that are provided through Web Service.In other words, it is a Web Service description language that is provided in XML format and describeswhere the service is located, what you can do with the service, and how you can execute the service.• WSDL Document StructureWith root as , it is divided into abstract definition (types/message/portType) and specific definition(binding/service). By describing abstract definition and specificdefinition separately, abstract definition of service can be reused when implementing differentservices.• WSDL Document Structure DetailsDescriptions of WSDL include Web Service name and URI information, how to encode SOAP message,protocol information for SOAP transmission, and interface information on using Web Services. WSDLconsists of the following.Descriptions for detailed WSDL factors are as follows.FactorsDescriptionDefines the physical location of Endpoint (application implemented as WebService) and describes the port address for each binding.5

OverviewFactorsDescriptionDefines binding information and address location. (Changed to inWSDL 2.0.)Defines portType and network protocol mapping information. In other words,defines which communication protocol to use for communication.Defines methods of interface. Interface (Changed from WSDL 2.0 to.)Defines Request/Response message used in method.Defines message that service uses. Declares message argument and returnvalue. (In WSDL 2.0, XML schema type is used through for description.)Defines data type used in document.2.1.4.Technical standardsWeb Service provided basic technical standards centered on SOAP, WSDL, and UDDI, and providesvarious extension standards for security, transaction handling, and credibility to enhance the qualityof service.• SecurityStandardsWS-SecurityWS-TrustWS-SecureConversationDescriptionMakes SOAP message extension mechanism rules to reinforceIntegrity and Confidentiality, Authentication, etc. Includes WS-Policy, WS-Trust, WS-SecureConversation, WS-Federation, and WS-Authorization.Standard for trust model that sets the maintenance and terminationof trust relationship for interactive Web Service to operate safely.Management standards for security context that indicate how securityis managed when exchanging messages.• TransactionStandardsWS-CoordinationWS-TransactionDescriptionStandards (Coordination Framework) for mechanisms that create andmanage, adjust, and complete activities so that various Web Servicesthat are distributed can participate in transaction.Standards (Coordination Protocols) for Atomic or Business transactionprotocols.• Reliable MessagingStandardWS-ReliableMessagingWS-AddressingDescriptionStandard that defines ACK (acknowledge) message, etc. that isexchanged among scattered Web Services to secure messaging trustassuring that messages arrive at destination.Standard which provides mechanisms that transfer messages amongWeb Services.6

Overview2.2.Implementation TechnologyIn java API that provides ways to develop Web Services with Java, there are JAX-RPC and JAX-WS. Otherimplementation technologies are also required.2.2.1.JAX-RPC vs. JAX-WSJAX-WS 2.0 is a following version of JAX-RPC 1.1. It is a standard java API that is used when implementingWeb Services.* JAX-WS : Java API for XML-Based Web Services* JAX-RPC : Java API for XML-Based RPC(Remote Procedure call)• Table Comparing JAX-RPC and JAX-WSWhen JAX-RPC 2.0, the following version of JAX-RPC 1.1, was introduced, WS which is messageorientedWeb Service was used instead of RPC, so the name became JAX-WS 2.0.JAX-RPC 1.1 JAX-WS 2.0Java EnvironmentWeb Services API used in JDK 1.4/J2EE1.4 environmentWeb Services API used in Web ServicesAPI environment (loading).SOAP SOAP 1.1 SOAP 1.1, SOAP 1.2XML/HTTPDoes not support HTTP binding (onlysupports SOAP binding)Supports HTTP binding (transmits XMLthrough HTTP without SOAP)WS-I Basic Profile WS-I Basic Profile 1.0 WS-I Basic Profile 1.1DataModelMappingHas specific data mapping model.(Covers 90% of schema type.) Thosethat are not covered are mapped asjavax.xml.soap.SOAPElement.JAXB (maps all XML schema 100%)Interface MappingModelDynamicProgrammingModelNot supportedNot supportedUse Java 5.0 function or introduceasynchronous functionIntroduce message-oriented or dynamicasynchronous functionMTOM Not supported Add support for MTOM that is newAttachment spec. through JAXB.Handler Model Based on SAAJ 1.2 Based on SAAJ 1.3• When JAX-RPC 1.1 should be usedCaseDescription1 When JDK 1.4 should be used continuously2 When SOAP encoding message or RPC/encoded style WSDL should be sent• When using JAX-WS 2.0Layered Programming Model is provided. The parent class enables easy development usingAnnotation, and the child class enables detailed adjustments based on API.CaseDescription1 When new message-oriented API should be used7

OverviewCaseDescription2 When attached data should be used with MTOM3 For better support of XML schema through JAXB4 When using asynchronous programming model on Web Service client5 When there should be client and service that handles SOAP 1.2 message6 When you wish to use only XML/HTTP binding without SOAP in Web Service• The Demerits of JAX-RPCThe previous JAX-RPC version has the following demerits.Demerits1 Supports limited XML Schema.Description2 Lacks mapping support between Java and WSDL.3 Low application portability.4 Large Runtime size.2.2.2.XML Schema5 Development is complicated.Is a language that indicate the file that defines the structure and contents of XML files. Defines documentstructure like DTD and provides all rules for grammar, vocabulary, structure, data type, etc.* XML Schema Definition (XSD) : XML Schema language for developing XML Schema• XML Schema vs. DTDXML Schema was introduced to solve the problems of DTD. XML Schema has higher expression skills,is a new structure definition language that provides precise data structure, and uses XML Schemaas Web Services.XML SchemaDevelop as XML grammarSupports namespaceDTDNot XML grammar (uses EBNF grammar)Does not support namespaceSupports various data types, can extend data type Limited data typeSupports object-oriented concept such asinheritanceOpen contents model• XML Schema element definitionDoes not have object-oriented conceptClosed contents modelThe descriptions for each property is as follows.PropertynametyperefDescriptionelement nameelement data typeUse to refer to entire element declaration8

OverviewPropertyDescriptionminOccurs Minimum number of element occurrences, default is 1maxOccurs Maximum number of element occurrences, default is 1default Default appointed when element value is not definedfixedFixed value to put in element• XML Schema attribute definitionDescriptions for each property are as follows.PropertynametyperefformusedefaultfixedDescriptionattribute nameattribute data typeUsed to refer to entire attribute declarationWhether it is limited name (qualified/unqualified)Condition of use (optional/prohibited/required)Default for when attribute value is not definedFixed value to put in attribute2.2.3.Other implementation descriptions• JAXB(Java Architecture for XML Binding)Java API for binding XML schema and Java class has two functions. They are functions that unmarshallXML to java object. This is opposite to marshalling java object to XML. For more information, go toHere [http://java.sun.com/developer/technicalArticles/WebServices/jaxb/]• MTOM(Message Transmission Optimization Mechanism)Mechanism that reduces message size by transmitting a large binary attachment file with SOAPmessage to raw byte. Optimizes message transmission for XML including binary data. For moreinformation, refer to Here [http://www.w3.org/TR/soap12-mtom/].• SAAJ (SOAP with Attachments API for Java)Java API that provides a way to create SOAP message, attach file, and transmit. For more information,refer to Here [http://java.sun.com/webservices/saaj/docs.html].2.3.Web Services FrameworkFrequently used Web Service open source framework includes Apache CXF, Apache Axis/Axis2, andSpring Web Services. Among various frameworks, Web Service framework that fits the purpose of useis selected. Anyframe has chosen Apache CXF.2.3.1.Web Services Framework typeWeb Service implementation style largely consists of Contract-Last and Contract-First. Contract-Laststyle is implementation type that automatically creates WSDL after first developing Java source code9

Overview(also called Code-First), and Contract-First style is development type that develops Java source codeafter WSDL file.There are many types of Web Service Open Source Frameworks. The following is four of the mostfrequently used.• Apache CXFSupports both Contract-First style and Contract-Last style. For more information, refer to http://cxf.apache.org/ [http://cxf.apache.org/].• Apache AxisThe procedures for developing Web Service with the previous version of Axis 2 is complicated. Formore information, refer to http://ws.apache.org/axis/ [http://ws.apache.org/axis/].• Apache Axis 2The structure of Apache Axis upgrade version has been changed. It is similar to Apache CXFfunctionally. For more information, refer to http://ws.apache.org/axis2/.• Spring Web ServicesSupports only Contract-First style Web Service development. For more information, refer to http://static.springframework.org/spring-ws/site/.2.3.2.The Characteristics of Apache CXFApache CXF was chosen among various Web Service Frameworks because of the followingcharacteristics.CharacteristicSupports JAX-WSSpring IntegrationAegis DatabindingRESTful servicesWS-* SupportApache LicensedCreated by Celtix and X-FireprojectSupports Web ServicestandardProvide Frontend ModelDescriptionCXF implements JAX-WS API, so Web Service is easily implemented.CXF supports Spring 2.X onwards, and makes it easy to integrateendpoint setting or client injection, etc. with Spring.CXF supports both JAXB and Aegis Databinding. Unlike JAXB, it doesnot need to be used in Annotation way, and using various data typeincluding List/Map/Date is easy. Anyframe recommends using standardJAXB Databinding, so details on Aegis Databinding are not stated in themanual.Makes RESTful service implementation easier with Annotation setting.For more information on developing RESTful services using Apache CXF,refer to Anyframe CXF-JAXRS Plugin.CXF supports various Web Service spec (WS-Addressing, WS-Policy, WS-ReliableMessaging, WS-Security).Free to use for apache license.Improvements have been made to strengthen functions and enhanceusability.SOAP, the Basic Profile, WSDL, WS-Addressing, WS-Policy, WS-ReliableMessaging, WS-SecurityProvides JAX-WS Frontend and Simple Frontend. Anyframe recommendsJAX-WS Frontend model that uses JAX-WS which is standard API so themanual does not state details of Simple Frontend.10

OverviewUsability2.4.ToolsCharacteristicSupports binary and previousprotocolAsynchronous call functionSupports JDK 1.5 onwardsDescriptionCan implement service by simply using API. Provides Tool (ANT Task,etc.).Provides XML/non-XML type binding (JSON, CORBA), provides pluggablearchitecture that can support several transmission protocols.Asynchronous calling is possible (provides Asynchronous InvocationModel).Supports JDK 1.5 onwards for various reasons including Annotationfunction.Provides various Tools in Apache CXF to make it easier to develop during Web Service implementation.Eclipse Plugin and Maven Plugin tools other than the Tools mentioned below are also provided. DownloadBinary distribution from Download Page [http://cxf.apache.org/download.html] and extract file, and youwill see Tool in bin folder under route folder. For more information refer to Here [http://cwiki.apache.org/CXF20DOC/tools.html].Ant TasksJava to WSJava to WSDLtoolDescriptionProvides ant task for wsdl2java and java2ws.Creates WSDL document, wrapper bean class, and server/client sidesource code from SEI class and related type class. (CXF 2.1)Creates WSDL document from SEI class and related type classes. (CXF2.0.x)Maven Integration and Plugin Provides Maven Plugin so that Maven can be used as build tool withMaven Repository that deploys related library.XSD to WSDLWSDL to JavaWSDL to ServiceWSDL to SOAPWSDL to XMLWSDLValidatorCreates WSDL document through XSD (Schema file)Creates ANT-based XML file that can build Java source codeand application developed with annotation needed for serviceimplementation from WSDL document.Creates new WSDL document that has HTTP or JMS service definitionfrom WSDL document.Creates new WSDL document that has SOAP binding information fromWSDL document.Creates new WSDL document that has XML binding information fromWSDL document.Checks if WSDL document or WSDL URL is well-formed document, anddeveloped properly based on Schema.11

3.DatabindingDatabinding means mapping XML document and JavaBeans objects based on XSD Schema of XMLdocument. It is a technology used to transfer XML document between server and client in Web Services.Apache CXF uses JAXB as a default for databinding, and additionally supports Aegis and MTOM. Typesof databinding are as follows.• JAXBJAXB stands for Java Architecture for XML Binding. It binds class data and performs unmarshalling ofobject from XML. On the other hand, it can also perform marshalling by saving object in xml.• AegisUnlike JAXB, Aegis is not standard (Spec.), but plays a same role to JAXB as a function provided onlyin Apache CXF. It first started as a part of Xfire project, but has been developed to be included inApache CXF as a combination of Celtix and Xfire. Anyframe recommends using JAXB Databinding, sothis manual does not include details about Aegis Databinding.• MTOMMTOM stands for Message Transmission Optimization Mechanism. It is an optimization mechanismof SOAP message transmission. This is a standard to transmit binary data more conveniently throughWeb Service.Types of databinding technology are shown in the following figure. Usually, databinding is used in JAXB,JAXB+MTOM, Aegis, Aegis+MTOM type. In the figure, the reason there is a common ground betweenJAXB and Aegis is that several JAXB annotations can be used while using Aegis.Here is how to use databinding by each technology.3.1.JAXB DatabindingJAXB stands for Java Architecture for XML Binding. It binds class data from XML Schema and performsthe unmarshalling of object from XML. On the other hand, it can also perform marshalling by savingobject in xml.The characteristics of JAXB are the following.• When using Apache CXF, default databinding is JAXB. Therefore, no additional setting for JAXB isneeded.• By setting Annotation such as @XmlElement in JavaBeans code, you can modify the element name.• You can use JAXB even without annotation in JavaBeans code.• As databinding supports list-type but not map-type, XmlAdapter class must be additionally developedto perform databinding using map-type.The mapping relation between JavaBeans object and XML Schema is as follows.The following figure shows the performing of JAXB role.The following is how to use JAXB function between server and client layer.12

Databinding3.1.1.Server ConfigurationWhen exposing Movie Service to Web Services using JAX-WS Frontend, declare and test the types ofinterface method parameter and return value in various types.3.1.1.1.SamplesHere is an example of the definition of Movie Service interface class and XmlAdapter class to use maptype.• Interface ClassThe following is a part of MovieService.java which developed Movie Service interface class.Note that @XmlSeeAlso annotation is set because Movie class type saved in Map object during JAXBDatabinding should be known. @XmlSeeAlso annotation does not have to be set if another methodof this Web Service uses Movie object as Input or Output parameter class type.@WebService@XmlSeeAlso(Movie.class)public interface MovieFinder {@XmlJavaTypeAdapter(CXFMapAdapter.class)Map get(String movieId) throws Exception;...• XmlAdapter Class [Provided by Anyframe]If return type is Map among interface methods of Movie Service, XmlAdapter should be additionallydeveloped. If Map type is not used, there is no need to develop this. The following is apart of CXFMapAdapter.java that inherits and implements XmlAdapter class. Developers useanyframe.common.cxf.map.CXFMapAdapter class provided by Anyframe, without needing specialimplementation.public class CXFMapAdapter extends XmlAdapter {public CXFMap marshal(Map v) throws Exception {CXFMap map = new CXFMap();for (Map.Entry e : v.entrySet()) {CXFMap.CXFEntry iue = new CXFMap.CXFEntry();iue.setValue(e.getValue());iue.setKey(e.getKey());map.getEntries().add(iue);}return map;}}...public Map unmarshal(CXFMap v) throws Exception {Map map = new LinkedHashMap();for (CXFMap.CXFEntry e : v.getEntries()) {map.put(e.getKey(), e.getValue());}return map;}• Additional class used in XmlAdapter Class [Provided by Anyframe]13

DatabindingWhen performing marshalling/unmarshalling in XmlAdapter class developed above, CXFMap classused must also be additionally developed. If map type is not used, there is no need todevelop this. The following is a part of CXFMap.java developing CXFMap class. Developers useanyframe.common.cxf.map.CXFMap class provided by Anyframe, without needing without specialimplementation.@XmlType(name = "CXFMap")@XmlAccessorType(XmlAccessType.FIELD)public class CXFMap {@XmlElement(nillable = false, name = "entry")private List entries = new ArrayList();public List getEntries() {return entries;}@XmlAccessorType(XmlAccessType.FIELD)@XmlType(name = "IdentifiedCXF")static class CXFEntry {// Map keys cannot be null@XmlElement(required = true, nillable = false)private String key;private Object value;3.1.2.Notespublic String getKey() {return key;}public void setKey(String key) {this.key = key;}public Object getValue() {return value;}public void setValue(Object value) {this.value = value;}...Notes when accessing method exposed to Web Services using JAXB Databinding.3.1.2.1.When databinding is needed in Java Type classundefined in SEI class during runtimeIn case of Java Type class which was not referred to as input value or return value of the method definedin SEI class, the following error message appears during databinding at runtime.org.apache.cxf.interceptor.Fault: Marshalling Error: class anyframe.sample.domain.Movie nor any of itssuper class is known to this context.The problem is solved as below.• Interface ClassIf method that returns List-type return value from SEI (Service Endpoint Interface) class methodexists and Java Type class saved in the related List is not referred to, when client calls the method,14

DatabindingJAXB Databinding is tried at runtime and Marshalling Error occurs. To prevent this, set @XmlSeeAlsoAnnotation or Generic Type of JDK1.5.Example of using @XmlSeeAlso@WebService@XmlSeeAlso({Movie.class})public interface MovieService {public List getMovieList(SearchVO searchVO);...Example of using Generic Type of JDK 1.5@WebServicepublic interface MovieService {public List getMovieList(SearchVO searchVO);...3.2.MTOM DatabindingMTOM stands for Message Transmission Optimization Mechanism. It is an optimization mechanismof SOAP message transmission. This is a standard to transmit binary data more convenientlythrough Web Service. It can be used with JAXB Databinding or Aegis Databinding. This is astandard enabling transmitting binary data more effectively through service, and data is transmittedin attachment type that is not in XML document by setting annotation in Schema Type or Java code.If xmime:expectedContentTypes="application/octet-stream" is additionally set in Schema Type, byte[]array type for base64Binary element is not created, but DataHandler for data streaming is created.The characteristics of MTOM are as follows.• When using Apache CXF, as MTOM function is not working as default, additional setting is neededto use MTOM.• Data is transmitted in attachment type, not in xml document.• Define attribute of JavaBeans which shows binary data as javax.activation.DataHandler type, andadditionally set @XmlMimeType("application/octet-stream") Annotation.The following is how to use MTOM function between server and client layer. Example includes using JAX-WS Frontend, JAXB, and MTOM together.• Server Configuration• Client Configuration• References - Contents related to MTOM3.2.1.Server ConfigurationThis is an example of exposing movie service to Web Services using JAX-WS Frontend. Let's take a lookat additional task for testing MTOM. Also, let's take a look at the case of transmitting binary data inthe existing xml document not using MOTM, and the case of transmitting data in attachment type (notin xml document) using MTOM. The example will check whether binary transmission is properly workingin those cases.15

Databinding3.2.1.1.SamplesThe following is an example of Movie class definition, data transmitted between client and server throughMovie Service interface method.• JavaBeans ClassThe following is a part of Movie.java which states Movie class, that is data transmitted between clientand server, through Movie Service interface method.public class Movie implements Serializable {private String movieId = "";private String title = "";private String director = "";private byte[] posterImgByteArray = null;@XmlMimeType("application/octet-stream")private DataHandler posterImgDataHandler = null;public byte[] getPosterImgByteArray() {return posterImgByteArray;}public void setPosterImgByteArray(byte[] posterImgByteArray) {this.posterImgByteArray = posterImgByteArray;}public DataHandler getPosterImgMTOM() {return posterImgDataHandler;}public void setPosterImgDataHandler(DataHandler posterImgDataHandler) {this.posterImgDataHandler = posterImgDataHandler;}...• Test caseUsing Spring Configuration XML Server setting (JAX-WS Frontend)Using MTOM Databinding can be defined through setting Spring Configuration XML....16

Databinding3.2.2.Client ConfigurationAmong ways to develop client to access Web Services, if you use Spring Configuration XML setting, youcan use it simply and conveniently.3.2.2.1.SamplesThe following is an example of accessing Movie Service exposed to Web Services.• Test CaseWhen using binary data in attachment type, not as a part of xml document, using MTOM, it testswhether MTOM Databinding is properly working and thereby searching and modifying poster imagebinary file of Movie.Using Spring Configuration XML Client setting (JAX-WS Frontend)Using MTOM Databinding can be defined through setting Spring Configuration XML....3.2.3.References - Contents related to MTOM• Spec. suggested by W3C for enhancing Web Services performance• In January 2005, W3C (World Wide Web Consortium) suggested the following three Web Servicesspecs. They provide ways to efficiently package or transmit binary data referring to or includingSOAP 1.2 message.• XOP (XML-binary Optimized Packaging), MTOM (SOAP Message Transmission OptimizationMechanism), RRSHB (Resource Representation SOAP Header Block)• Binary data transmission• When a part of xml document is binary data, it must be encoded as base64. This increases CPUusage percentage and payload size. One of the characteristics of Web Services is that transmittedmessage is composed of xml and eases transmission between heterogeneous systems. This isbecause of the fact that as xml is a kind of text document, the portability is good between differenttypes. However, to add binary data to text xml document, encoding is needed in base64 type, whichleads to more than 50% of binary data capacity. Also, to handle encoding and decoding, 5~10%of CPU load is added. In other words, when transferring binary data, using Web Services causesreduced performance.• Using MTOM creates binary data in SOAP-Attachment type, not as a part of xml document. Therefore,it can resolve the problems mentioned above.• If you add xmime:expectedContentTypes="application/octet-stream" to Schema type, byte[] forbase64Binary element is not created, but DataHandler for data streaming is created.• Providing the means and ways to transmit large-size binary data.17

Databinding• By using XOP and MTOM, more efficient serialization and transmission of SOAP message ispossible.• As XOP provides a standard means to include binary data in transmission packet as it is, itcan efficiently work even in a small space or narrow data transmission bandwidth. By using XMLInformation Set(InfoSet), xml document is serialized in various ways.• MTOM which implements XOP handles SOAP transmission using functions provided by XOP. Bydefining transmission mechanism optimizing SOAP binding and transmission, it reduces requiredtransmission bandwidth and time required for encoding and decoding large-size binary data. Inaddition, when transmitting various binary data, it performs SOAP transmission in MIME attachmenttype.• RRSHB(Resource Representation SOAP Header Block) enables SOAP message receiver to accesslocal cache of remotely-located resources. By using it with MTOM, request handling speed willdramatically improve when local cache already exists in the remotely-located data. For yourreference, message receiver can select and use one between the file identified by URI or localcache sent in SOAP transmission.3.3.Resources• References• JSR 222: Java Architecture for XML Binding (JAXB) 2.0 [http://jcp.org/en/jsr/detail?id=222]• Java Architecture for XML Binding (JAXB) [http://java.sun.com/developer/technicalArticles/WebServices/jaxb/]• SOAP Message Transmission Optimization Mechanism [http://www.w3.org/TR/soap12-mtom/]• Apache CXF User's Guide - JAXB Databinding [http://cwiki.apache.org/CXF20DOC/jaxb.html]• Apache CXF User's Guide - MTOM Attachments with JAXB [http://cwiki.apache.org/CXF20DOC/mtom-attachments-with-jaxb.html]18

4.JAX-WS FrontendThis is a Frontend model that enables implementation of Web Services through Annotation using JAX-WS, a Web Services standard API.JAX-WS (Java API for XML Web Services) is a JAVA API to develop Web Services, as a part of Java EE. LikeJava API of another Java EE, JAX-WS uses Annotation adopted at Java SE 5 and eases the developmentand deployment of Web Service client and server module. JAX-WS, a developed concept of JAX-RPCstandard, is a Web Service standard integrated and developed based on JAXB standard for XML binding,SAX standard for standard streaming parser, and a new SAAJ standard with enhanced functions. JAX-WS is characterized by the following.• More convenient to develop Web Services than JAX-RPCCompared with JAX-RPC, developing Web Services is much more convenient. Developing Web ServiceEndpoint and mapping between Java type and WSDL can be performed explicitly through Annotationsetting. By replacing Web Service deployment descriptor which had to be developed to create WebServices in JAX-RPC environment with Annotation, difficulties with developing Web Services aresignificantly reduced.• Task through AnnotationHandles mapping between Java and WSDL, and schema-type mapping between Java type andmessage referred to by WSDL. Provides necessary information among runtime process handling WebService messages and is used to respond to calling Web Services.• Annotation-related Spec.Annotation used in JAX-WS 2.x is separately defined in Web Services Metadata(JSR-181) Spec.and JAX-WS 2.x Spec. Annotation used in other message-type mapping is defined in JAXB2.x Spec. Representative annotation defined in Web Services Metadata(JSR-181) Spec. is asfollows. (javax.jws.WebService, javax.jws.WebMethod, javax.jws.WebParam, javax.jws.WebResult,javax.jws.soap.SOAPBinding)The following figure shows JAX-WS process.The following are instructions on how to use JAX-WS Frontend in server and client layer. JAX-WS Frontendcan develop server and client mainly by two ways: using Frontend API or using Spring Configuration.• Server Configuration1. Web Service development19

JAX-WS Frontend2. Running server (Select one of two)• Spring Configuration XML - Use tag (Recommended)• [Server] Use JAX-WS Frontend API• Client Configuration1. Developing client (Select one of two)• Spring Configuration XML - Use tag (Recommended)• [Client] Use JAX-WS Frontend API• [Reference] Annotation setting when developing Web Services4.1.Developing Web ServiceWhen developing service to be exposed to Web Service, the method is same to developing generalservice bean. However, @WebService Annotation must be set in interface.4.1.1.SamplesThe following is an example of Movie Service to be exposed to Web Service. Service composes ofinterface class, implementation class, DAO(Data Access Object) class, and VO(Value Object) class,same to developing general Spring bean.• Interface ClassThe following is a part of MovieFinder.java which developed MovieFinder Service interface class.@WebService Annotation must be defined in the top of interface class. Although there are variousproperty values of @WebService Annotation and various Annotation types to define by method andparameter, the only required Annotation is @WebService. For additionally defining another type ofAnnotation, refer to [Reference] Annotation when defining Web Services setting method.@WebServicepublic interface MovieFinder {Page getPagingList(Movie movie, int pageIndex) throws Exception;@XmlJavaTypeAdapter(CXFMapAdapter.class)Map get(String movieId) throws Exception;}...• Implementation ClassAs a class which implemented interface class, it can be developed regardless of Web Serviceimplementation. The following is a part of MovieFinderImpl.java which implemented MovieFinderService interface class. By using MovieDAO internally, it manages Movie information. @WebServiceAnnotation can be defined at the top of the implementation class. As @WebService Annotation wasalready defined at the top of interface class, it will be skipped here. For instructions on how to setannotation, refer to [Reference] Annotation when developing Web Services.@Service("cxfMovieFinder")public class MovieFinderImpl implements MovieFinder {@Inject@Named("cxfMovieDao")20

JAX-WS Frontendprivate MovieDao movieDao;public Page getPagingList(Movie movie, int pageIndex) throws Exception {return this.movieDao.getPagingList(movie, pageIndex);}public Map get(String movieId) throws Exception {return this.movieDao.get(movieId);}}...4.2.Spring Configuration XML - Usejaxws:endpoint tagTo run server exposing the developed service to Web Service, two methods are supported. Among them,let's use Spring Configuration XML - tag to run server. (Apache CXF also providesways to run server using tag, but Anyframe uses tag, so the manualdoes not include information on tag.)Each property value of tag is as shown in the following table. There are also manyproperties that are not shown in the table. Note that the following is an explanation of property valuesthat need to be defined. For explanation on other property values, refer to JAX-WS Spring Configuration[http://cwiki.apache.org/CXF20DOC/jax-ws-configuration.html].Property Name Description Required DefaultValueid Define spring bean id. Y N/AimplementorDefine implementation class. If you want to replace classname with spring bean id, add # in front of bean id.address Define the address to run service in relative path. Y N/A4.2.1.SamplesThe following is an example of running server to expose MovieFinder Service to Web Service by usingSpring Configuration XML - tag.• The following is a part of context-cxf-jaxws.xml which defines the properties of tagthat exposes business layer service to Web Service.ConfigurationYN/A21

JAX-WS FrontendRun web application using WAS of Jetty or Tomcat server and expose business layer service toWeb Service. In this case, Spring configuration XML file must be registered in web.xml usingorg.springframework.web.context.ContextLoaderListener. The following is a part of web.xml definingCXFServlet and ContextLoaderListener.

JAX-WS Frontend4.3.1.SamplesThe following is an example of running server exposing MovieFinder Service to Web Service usingJaxWsServerFactoryBean provided in Apache CXF.• Running server using Apache CXF JaxWsServerFactoryBeanThe following is an example of developing code which runs server exposing business layer serviceto Web Service.MovieFinderImpl implementor = new MovieFinderImpl();JaxWsServerFactoryBean svrFactory=new JaxWsServerFactoryBean();svrFactory.setServiceClass(MovieFinder.class);svrFactory.setAddress("http://localhost:8080/myproject/cxf-jaxws/ws");svrFactory.setServiceBean(implementor);svrFactory.create();4.4.Spring Configuration XML - Usingjaxws:client tagTo develop client accessing web service, two methods are provided. Among them, let's develop clientusing Spring Configuration XML - tag to access web services. Each property value of tag is as shown in the following table. There are also many properties that are notshown in the following table. Note that the following is an explanation of property values that needto be defined. For explanation on other property values, refer to JAX-WS Spring Configuration [http://cwiki.apache.org/CXF20DOC/jax-ws-configuration.html] .Property Name Description Required Default Valueid Define spring bean id. Y N/AserviceBeanDefine service interfaceclass.address Define URL addressto access service inabsolute path.4.4.1.SamplesYYN/AN/AThe following is an example of accessing Movie Service using Spring Configuration XML - tag.• ConfigurationThe following is a part of cxf-jaxws-servlet.xml, a configuration file of tag accessingMovieFinder Service exposed to Web Services.

JAX-WS Frontendhttp://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd">• ControllerThe following is a part of MovieFinderController.java, a Controller class accessing to MovieFinderService exposed to Web Service based on the above-mentioned configuration files.@Controller("cxfMovieFinderController")@RequestMapping("/cxfMovieFinder.do")public class MovieFinderController {@Inject@Named("cxfWsClientMovieFinder")private MovieFinder movieFinder;@RequestMapping(params = "method=get")public String get(@RequestParam("movieId") String movieId, Model model)throws Exception {Map resultMap = this.movieFinder.get(movieId);model.addAttribute(resultMap.get("movie"));return "cxfViewMovie";}...4.5.Client: Using JAX-WS Frontend APITo develop client accessing Web Service, two methods are provided. Among them, let's develop clientusing JAX-WS Frontend API and access Web Service. It is possible to directly call JAX-WS Frontend APIprovided in Apache CXF and is also possible to register JaxWsProxyFactoryBean class as a bean ofSpring Configuration file.4.5.1.SamplesHere is an example of accessing Movie Service exposed to Web Services by directly usingJaxWsProxyFactoryBean provided in Apache CXF.• Client using Apache CXF JaxWsProxyFactoryBeanThe following is an example of developing code accessing Movie Service exposed to Web Servicesusing JaxWsProxyFactoryBean class provided in Apache CXF.JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean();factory.setServiceClass(MovieFinder.class);factory.setAddress("http://localhost:8080/myproject/cxf-jaxws/ws");MovieFinder movieFinder = (MovieFinder) factory.create();Map resultMap = movieFinder.get("MV-00003");4.6.Defining annotationOnly @WebService() is required, and in most cases, defining annotation is not required as default valueis provided.24

JAX-WS Frontend4.6.1.@WebService (javax.jws.WebService)This is used when java class containing Annotation specifies Web Service Endpoint interface class orimplementation class, and is defined in SEI and implementation class. (Required) No need to define allproperty values, but it is recommended to define as much information as possible. The more Annotationinformation defined in SEI, the more well-defined WSDL can be created. Details on property are as shownin the following table.Property Name Type Required WSDLMappingDefaultDescriptionname String X wsdl:portType Class name Mapped as aweb servicename ofwsdl:portType.Default valueis the nameexcludinginterfaceclass orimplementationclasspackage.targetNamespace String X N/A PackageNameserviceName String X wsdl:service Class name +"Service"wsdlLocation String X N/A ServiceDeploy URIXMLnamespaceto be usedin WSDL andXML elementcreated fromWeb ServiceCannot beset in SEI.Mapped asa servicename ofwsdl:service.Default valueis the nameexcludinginterfaceclass orimplementationclasspackagename +"Service"portType andbindingdefined inWSDL inthe predefinedWSDLlocation must25

JAX-WS FrontendProperty Name Type Required WSDLMappingDefaultDescriptionbe consistentwith valuesdeveloped inserviceimplementationclass.endpointInterface String X N/A Class nameincluding SEIpackagename,implementationclassclass name +"Port"portName String X wsdl:port Implementation• Method rules in class where @WebService annotation setting is applied.class name +"Port"Cannot setin SEI, SEIname ofimplementationCannot set inSEI. Mappedas wsdl:port.Default valueisimplementationclass name +"Port"• When @WebService annotation of implementation class refers to SEI, there must be no@WebMethod annotation in implementation class.• All common methods of SEI are considered methods exposed to Web Service regardless of@WebMethod annotation setting.• In case of implementation class not referring to SEI, method is not exposed to Web Service when@WebMethod annotation is defined as exclude=true value.4.6.2.@WebParam (javax.jws.WebParam)Sets mapping between Java method input parameter of Web Service and XML element showingparameter in WSDL file. Details on property is as shown in the following table.Property Type Required Descriptionname String X Web Service that has a parameter name is RPC style is mapped aswsdl:part. Web Service of Document style becomes the local name ofXML element showing parameter. Default value is parameter name ofmethod.targetNamespace String X Used only in document style Web Service where XML namespaceof parameter is matched with XML element. Default value istargetNamespace of Web Service.mode Enum X As a direction where parameter is transferred, select one among IN,OUT or INOUT. Default value is IN.header Boolean X If defined as true, parameter will be fetched from SOAP messageheader, not from SOAP message body. Default value is false.26

JAX-WS FrontendProperty Type Required DescriptionpartName String X This is only used if the operation is RPC style, or if the operation isdocument style and the parameter style is BARE.4.6.3.@WebMethod (javax.jws.WebMethod)Used when exposing methods to Web Service. @WebMethod annotation is provided only in the classwhere @WebService annotation is defined. Details of property are shown in the following table.Property Type Required DescriptionoperationName String X Mapped as method name of wsdl:operation. Default value isjava method name.action String X As an action property applied to method, it determines thevalue of SOAPAction header in SOAP message.exclude Boolean X Defines whether to exclude method in Web Service. Defaultvalue is false.4.6.4.@OneWay (javax.jws.OneWay)Used when defining one-way method where there is input value but no return value. Used along with@WebMethod annotation and special property definition is not needed.4.6.5.@WebResult (javax.jws.WebResult)Used when defining mapping between return value of the method exposed to Web Service and XMLelement showing WSDL return value. Details of property are shown in the following table.Property Type Required Descriptionname String X Element name showing the return value in WSDL. ForRPC style web services, this is the name of the wsdl:partattribute representing the return value. For document styleweb services, this is the local name of the XML elementrepresenting the return value. The default value is returnfor RPC and DOCUMENT/WRAPPED bindings. The defaultvalue is the method name + Response for DOCUMENT/BAREbindings.targetNamespace String X Specifies the XML namespace for the return value. Thisparameter is only used if the operation is RPC style or ifthe operation is DOCUMENT style and the parameter styleis BARE. Default value is targetNamespace value of WebService.header String X Specifies whether the result is carried in a header. Defaultvalue is false.partName String X Specifies the part name for the result with RPCor DOCUMENT/BARE operations. The default value is@WebResult.name.4.6.6.SamplesHere is an example of setting various Annotations in Movie Service interface class.27

JAX-WS Frontend• Interface ClassThe following is a part of MovieService.java class which develops Movie Service interface class.Setting @WebService Annotation at the top of interface class is required. Also, let's take a look into@WebMethod, @Oneway, and @WebParam Annotation and see how they work.@WebService@XmlSeeAlso(Movie.class)public interface MovieService {@WebMethod(exclude = true)public void remove(String movieId) throws Exception;// ================= method for Annotation tests@WebMethod(operationName = "testAnnotationMethodInclude")public void testAnnotationMethod();@Onewaypublic String testAnnotationOneWay();public String testAnnotationWebParam(@WebParam(name = "movieAnnotationWebParam") String input);...• Implementation ClassThe following is a part of MovieServiceImpl.java which implements Movie Service interface class.@Service("movieService")public class MovieServiceImpl implements MovieService {// ================= method for Annotation testspublic void testAnnotationMethod() {System.out.println("testAnnotationMethod method is called.");}public String testAnnotationOneWay() {System.out.println("testAnnotationOneWay method is called.");return "testAnnotationOneWay";}public String testAnnotationWebParam(String input) {System.out.println("testAnnotationWebParam method is calledwith the input parameter=" + input);return "testAnnotationWebParam";}...• Test CaseThe following is an example of developing code that accesses Movie Service exposed to Web Servicesusing JaxWsProxyFactoryBean class provided in Apache CXF. Let's take a look at how it worksaccording to the value defined in WebServices Annotation.JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean();factory.setServiceClass(MovieService.class);factory.setAddress("http://localhost:8080/myproject/ws/movieList");MovieService movieService = (MovieService) factory.create();/*** Do not let specific method be exposed to Web Service method using @WebMethodannotation.* Set exclude value as true among @WebMethod property values.28

JAX-WS Frontend* (ex. @WebMethod(exclude=true) )*/try {movieService.remove("MV-00003");} catch (WebServiceException e) {// Exception should be occurred.}/*** Using @WebMethod annotation, change specific method name to another name to enablecalling.* Among @WebMethod property value, define operationName value as another name.* (ex. @WebMethod(operationName="testAnnotationMethodInclude") )** Only testAnnotationMethod is actually provided in SEI.* As operationName was defined as testAnnotationMethodInclude among @WebMethod propertyvalues,* call by redefining Service Interface class which contains testAnnotationMethodIncludemethod* when calling Web Service method at client.*/try {movieService.testAnnotationMethodInclude();} catch (Exception e) {// It should not be failed.}/*** Use @Oneway annotation* to define one-way method where there can be a specific method input value but no returnvalue.* Other property value settings of @Oneway are not needed.* (ex. @Oneway )*/try {movieService.testAnnotationOneWay().trim();fail();} catch (NullPointerException e) {// Exception should be occurred.}4.7.Resources• References• JAX-WS 2.0 Specification [http://jcp.org/en/jsr/detail?id=224]• Building Web Services with JAX-WS [http://java.sun.com/javaee/5/docs/tutorial/doc/bnayl.html]• JAX-WS Spring Configuration [http://cwiki.apache.org/CXF20DOC/jax-ws-configuration.html]29

5.Asynchronous InvocationAlong with general synchronous invocation, Apache CXF supports two types (Polling approach, Callbackapproach) of asynchronous invocation defined in JAX-WS Spec. In other words, calling Web Services inserver side from client side can be done asynchronously.The characteristics of Polling approach are as follows.• Server) Add method (method name: target method name + "Async") in service interface. In this case,define method whose return type is Response.• Client) To call method existing remotely, call the specific method returning javax.xml.ws.Responseobject without output parameter.• Response object which extended javax.util.concurrency.Future interface is used to check whether theresponse message arrived.The characteristics of Callback approach are as follows.• Server) Add method (method name: target method name + "Async") in service interface. In this case,define method whose return type is Future and input parameter is AsynchHandler.• Client) Need to implement AsyncHandler class.• Client) To call the method existing remotely, call the method defined above, one of whose parametersare in reference relation with callback object of javax.xml.ws.AsyncHandler type.• As soon as response message arrives to client, Apache CXF runtime environment recalls AsyncHandlerobject to transfer response message to response message contents.The following shows which task to be done on server and client side to use Asynchronous MethodInvocation. Let's look into an example for the two types (Polling approach and Callback approach) ofasynchronous invocation.5.1.Server ConfigurationBy using tool provided in Apache CXF, it supports asynchronous invocation of Web Services. The followingis an example of how asynchronous invocation is possible using tool.If tool is not yet prepared, download Apache CXF from download page [http://cxf.apache.org/download.html] and extract the file to use tool existing in bin folder under root folder.5.1.1.SamplesCreate WSDL file by using java2ws Tool targeting interface class of Movie Service to exposeto Web Service. After creating WSDL, create java source codes which enable asynchronousinvocation (classes under anyframe.sample.movie.jaxws.asynch.asynch_soap_http package (SEI,WebServiceClient, complex type classes)) by using WSDL file and asynch_binding.xml file throughwsdl2java Tool. In this case there is no need to use java2ws Tool if you already have WSDL file.• Temporary Interface ClassThe following is a part of MovieServiceAsynch.java which developed interface class of Movie Service.As it implements Web Services using JAX-WS Frontend model, make sure to define @WebServiceAnnotation in the top of interface class. Define findMovieListAll() as interface method and client callsthis method asynchronously. In fact, this interface is not used. It is developed to create WSDL file.The one that is used is the interface class created from WSDL file.30

Asynchronous Invocation@WebService(targetNamespace = "http://asynch.jaxws.movie.sample.anyframe/asynch_soap_http")public interface MovieServiceAsynch {public List findMovieListAll() throws Exception;}...• Creating WSDL fileCreate WSDL file based on interface class. In this case, create it using java2ws among tools providedin Apache CXF. Execute the following command on command prompt. The execution location is theroot folder where the project exists.command>java2ws - wsdl - cp target/classesanyframe.sample.movie.jaxws.asynch.MovieServiceAsynchThe following is a part of the created WSDL file (MovieServiceAsynchService.wsdl). After created, ifyou wish to, you can modify information such as soap:address location.

Asynchronous Invocation...• Creating Java CodeUsing the WSDL file and asynch_binding.xml file, create java source code that provides asynchronousfunction. In this case, create it using wsdl2java among the tools provided in Apache CXF. Executethe following command on Command Prompt. The execution location is the root folder of where theproject exists.command>wsdl2java -d src -b src/test/resources/webservices/asynch/wsdl/asynch_binding.xmlsrc/test/resources/webservices/asynch/wsdl/MovieServiceAsynchService.wsdlAll the java codes created through tool are located underanyframe.sample.movie.jaxws.asynch.asynch_soap_http package. Various java source codesare created such as MovieServiceAsynch.java (Interface class of MovieService),MovieServiceAsynchService.java (WebService client class to access MovieService), and Movie.java(JavaBeans class). The following is a part of MovieServiceAsynch.java which is a created interfaceclass. This interface class is actually used. Two findMovieListAllAsync() methods which are used inPolling approach and Callback approach are additionally added.@WebService(targetNamespace = "http://asynch.jaxws.movie.sample.anyframe/asynch_soap_http",name = "MovieServiceAsynchService")@XmlSeeAlso( {ObjectFactory.class })public interface MovieServiceAsynch {@ResponseWrapper(localName = "findMovieListAllResponse",targetNamespace = "http://asynch.jaxws.movie.sample.anyframe/asynch_soap_http",className ="anyframe.sample.movie.jaxws.asynch.asynch_soap_http.FindMovieListAllResponse")@RequestWrapper(localName = "findMovieListAll",targetNamespace = "http://asynch.jaxws.movie.sample.anyframe/asynch_soap_http",className = "anyframe.sample.movie.jaxws.asynch.asynch_soap_http.FindMovieListAll")@WebResult(name = "return", targetNamespace = "")@WebMethodpublic java.util.ListfindMovieListAll() throws Exception;@ResponseWrapper(localName = "findMovieListAllResponse",targetNamespace = "http://asynch.jaxws.movie.sample.anyframe/asynch_soap_http",className ="anyframe.sample.movie.jaxws.asynch.asynch_soap_http.FindMovieListAllResponse")@RequestWrapper(localName = "findMovieListAll",targetNamespace = "http://asynch.jaxws.movie.sample.anyframe/asynch_soap_http",className = "anyframe.sample.movie.jaxws.asynch.asynch_soap_http.FindMovieListAll")@WebMethod(operationName = "findMovieListAll")publicResponsefindMovieListAllAsync();@ResponseWrapper(localName = "findMovieListAllResponse",targetNamespace = "http://asynch.jaxws.movie.sample.anyframe/asynch_soap_http",className ="anyframe.sample.movie.jaxws.asynch.asynch_soap_http.FindMovieListAllResponse")@RequestWrapper(localName = "findMovieListAll",targetNamespace = "http://asynch.jaxws.movie.sample.anyframe/asynch_soap_http",className = "anyframe.sample.movie.jaxws.asynch.asynch_soap_http.FindMovieListAll")@WebMethod(operationName = "findMovieListAll")public Future findMovieListAllAsync(32

Asynchronous Invocation@WebParam(name = "asyncHandler", targetNamespace = "")AsyncHandlerasyncHandler);}...• Implementation ClassAs the class implementing interface class, create method with empty logic about twofindMovieListAllAsync() methods. Not called in reality. The following is a part of MovieServiceImpl.javawhich implements MovieServiceAsynch, a Movie Service interface class.@WebService(serviceName = "MovieServiceAsynchService", portName ="MovieServiceAsynchPort", ...public class MovieServiceImpl implements MovieServiceAsynch {public List findMovieListAll() throws Exception {return this.movieDAO.findMovieListAll();}public Response findMovieListAllAsync() {return null;/* not called */}public Future findMovieListAllAsync(AsyncHandler asyncHandler) {return null;/* not called */}...• Running server using Apache CXF JaxWsServerFactoryBeanThe following is an example code of running server which exposes server side service to Web Services.Define interface class, instance of implementation class, and address of Web Services as propertyinformation of JaxWsServerFactoryBean.MovieServiceImpl implementor = new MovieServiceImpl();JaxWsServerFactoryBean svrFactory=new JaxWsServerFactoryBean();svrFactory.setServiceClass(MovieServiceAsynch.class);svrFactory.setAddress("http://localhost:8080/myproject/cxf-jaxws/ws");svrFactory.setServiceBean(implementor);svrFactory.create();5.2.Client ConfigurationWhen calling server side Web Service from client, try asynchronous invocation. In this case, access WebService using MovieServiceAsynchService among the java codes created through the tools above.5.2.1.SamplesThe following is an example of asynchronous invocation of Movie Service exposed to Web Services.• Implementing AsyncHandler class when using Callback approachWhen using polling approach, no class needs to be additionally developed. When using Callbackapproach, AsynchHandler class must be additionally implemented. javax.xml.ws.AsyncHandler33

Asynchronous Invocationinterface and handleReponse method should be implemented. The following is a part ofMovieAsyncHandler.java which implements AsyncHandler class.public class MovieAsyncHandler implements AsyncHandler {private FindMovieListAllResponse reply;public void handleResponse(Response response) {try {System.err.println("handleResponse called");reply = response.get();} catch (Exception ex) {ex.printStackTrace();}}public List getResponse() {return reply.getReturn();}...• Test caseThe following is an example of accessing Movie Service exposed to Web Services usingjava codes which were created through the above-mentioned codes and tools. ThroughMovieServiceAsynchService, a WebService client code created through tool, asynchronously call themethod of Movie Service interface exposed to Web Services. In this case, access using WSDL fileand Service Name. After getting Movie Service, call findMovieListAllAsync() method asynchronous ofMovie Service and test if the calling is working properly.private static final QName SERVICE_NAME =new QName("http://asynch.jaxws.movie.sample.anyframe/asynch_soap_http","MovieServiceAsynchService");/*** Search for the whole movie list in Polling approach* among Asynchronous method invocations.*/File wsdl = new File("src/test/resources/webservices/asynch/wsdl/MovieServiceAsynchService.wsdl");MovieServiceAsynchService client =new MovieServiceAsynchService(wsdl.toURL(), SERVICE_NAME);MovieServiceAsynch movieService = client.getMovieServiceAsynchPort();// 1. find movie list allResponse response =movieService.findMovieListAllAsync();// 2. wait for response after asynchronous method invocationwhile (!response.isDone()) {Thread.sleep(100);}// 3. check the movie list countFindMovieListAllResponse reply = response.get();assertEquals(2, reply.getReturn().size());/*** Search for the whole movie list in Callback approach34

Asynchronous Invocation* among Asynchronous method invocations.*/File wsdl = new File("src/test/resources/webservices/asynch/wsdl/MovieServiceAsynchService.wsdl");MovieServiceAsynchService client =new MovieServiceAsynchService(wsdl.toURL(), SERVICE_NAME);MovieServiceAsynch movieService = client.getMovieServiceAsynchPort();// 1. find movie list allMovieAsyncHandler asynchHandler = new MovieAsyncHandler();Future response = movieService.findMovieListAllAsync(asynchHandler);// 2. wait for response after asynchronous method invocationwhile (!response.isDone()) {Thread.sleep(100);}// 3. check the movie list countList reply = asynchHandler.getResponse();assertEquals(2, reply.size());...5.3.Resources• References• Developing a Consumer - Asynchronous Invocation Model [http://cxf.apache.org/docs/developinga-consumer.html]• Asynchronous Web Service Invocation with JAX-WS 2.0 [http://today.java.net/pub/a/today/2006/09/19/asynchronous-jax-ws-web-services.html]35

6.WAS(Web Application Server)ConfigurationWeb application that includes Apache CXF-based Web Services is deployed in WAS (Web ApplicationServer). In this case, additional work is needed to execute Apache CXF in each WAS. This chapterexplains what to do when additional environment setting is needed for each WAS. Apache CXF supportsJDK 1.5 onwards, and WAS to be installed is also limited to WAS that supports JDK 1.5 onwards.The following is information on each WAS.6.1.TomcatApache CXF supports JDK 1.5 onwards, Tomcat server version should be 5.5.x onwards. Refer to Here[http://tomcat.apache.org/] for information on Tomcat server and downloading.However, in case of sample application created by Plugin installation, refer to Noticefor each WAS(Web Application Server) [http://dev.anyframejava.org/docs.en/anyframe/plugin/foundation/4.6.1/reference/htmlsingle/foundation.html#foundation_overview_note] in Foundationmanual to check notices for each WAS to use opensource. When there is a Plugin installed other thanFoundation Plugin, also refer to Installation > "Notice for each WAS(Web Application Server)" in eachPlugin manual.6.1.1.5.5.23, 6.0.x, 7.0.x6.2.JEUS6.2.1.5.06.2.2.6.0Apache CXF can be used without additional setting.Apache CXF supports JDK 1.5 onwards, so JEUS server version should be 5 or 6, but in case of JEUS 5,Apache CXF cannot be used because of JAXB library conflict. Refer to TmaxSoft website for informationon JEUS server and downloading.However, in case of sample application created by Plugin installation, refer to Noticefor each WAS(Web Application Server) [http://dev.anyframejava.org/docs.en/anyframe/plugin/foundation/4.6.1/reference/htmlsingle/foundation.html#foundation_overview_note] in Foundationmanual to check notices for each WAS to use opensource. When there is Plugin other than FoundationPlugin, also refer to Installation > "Notice for each WAS(Web Application Server)" in each Plugin manual.Cannot use Apache CXF. Does not run, because of the difference between the versions of JAXB API, IMPLand reference libraries deployed in JEUS server (JAXB 1.x), and libraries deployed in web applicationimplemented using Apache CXF.Can be used in Apache CXF without additional setting. Runs without problem, because the versions ofJAXB API, IMPL and reference libraries deployed in JEUS server (JAXB 1.x), and libraries deployed in webapplication implemented using Apache CXF, match.36

WAS(Web ApplicationServer) ConfigurationHowever, Plugins provided in Anyframe are developed based on Jetty, so they basically use 8080 port.Therefore, when using JEUS, open cxf-jaxws-servlet.xml file, and change the 'http://localhost:8080/...'part to 'http://localhost:{JEUS use port}/...'.6.3.WebLogic6.3.1.9.2Apache CXF supports JDK 1.5 onwards, so WebLogic server version should be WebLogic 9.2(JDK1.5), 10.1(JDK 1.5), 10.3(JDK 1.6). Refer to Here [http://www.oracle.com/appserver/index.html] forinformation on WebLogic and downloading .However, in case of sample application created by Plugin installation, refer to Noticefor each WAS(Web Application Server) [http://dev.anyframejava.org/docs.en/anyframe/plugin/foundation/4.6.1/reference/htmlsingle/foundation.html#foundation_overview_note] in Foundationmanual to check notices for each WAS to use opensource. When there is Plugin other than FoundationPlugin, also refer to Installation > "Notice for each WAS(Web Application Server)" in each Plugin manual.The below additional work is needed for resolving library problems when installing CXF-JAXWS Plugin.You can choose between how to compose web application with EAR file [1] and how to copy geronimows-metadata_2.0_spec-1.1.2.jarfile [2].[1] How to compose web application with EAR file• However, Plugins provided in Anyframe are developed based on Jetty, so they basically use8080 port. Therefore, when using JEUS, open cxf-jaxws-servlet.xml file, and change the 'http://localhost:8080/...' part to 'http://localhost:{JEUS use port}/...'.• Create EAR Folder. For instance, the following two folders can be created when project named'myproject' will be packaged with ear.myproject.ear/ META-INF/ myproject• Deploy application.xml file in META-INF folder. Refer to the below as an example.Samplemyproject/myproject• Deploy weblogic-application.xml file in META-INF folder. Define so that library in WEB-INF/lib folder forjavax.jws package is referred to first. Refer to Here [http://cwiki.apache.org/CXF20DOC/applicationserver-specific-configuration-guide.html#ApplicationServerSpecificConfigurationGuide-WebLogic]onhow to define weblogic-application.xml.37

WAS(Web ApplicationServer) Configurationjavax.jws.*• Deploy weblogic.xml file in WEB-INF inside myproject folder. Define so that library and class files inweb application are referred to first. Refer to the below as an example.true6.3.2.10.1• Remove xmlbeans-x.x.x.jar file in WEB-INF/lib folder inside myproject folder.[2] How to copy geronimo-ws-metadata_2.0_spec-1.1.2.jar file• Copy geronimo-ws-metadata_2.0_spec-1.1.2.jar file in JDK_HOME/jre/lib/endorsed folder.• Check the location of JDK 1.5 set when installing WebLogic server, create endorsed folder underJDK_HOME/jre/lib folder, and copy geronimo-ws-metadata_2.0_spec-1.1.2.jar file, under WEB-INF/libfolder of web application currently deployed, to endorsed folder.[Reference] In this case, note that the above work influences the entire WebLogic server.The below additional work is needed for resolving library problems when installing CXF-JAXWS Plugin.• However, Plugins provided in Anyframe are developed based on Jetty, so they basically use 8080 port.Therefore, open cxf-jaxws-servlet.xml file, and change the 'http://localhost:8080/...' part to 'http://localhost:{JEUS use port}/...'.• Create EAR Folder. For instance, the following two folders can be created when project namedmyproject is packaged with ear.myproject.ear/ META-INF/ myproject• Deploy application.xml file in META-INF folder. Refer to the below as an example.Samplemyproject/myproject• Deploy weblogic-application.xml file in META-INF folder. Define so that library in WEB-INF/lib folder forjavax.jws package is referred to first. Refer to the below as an example.38

WAS(Web ApplicationServer) Configurationjavax.persistence.*javax.jws.*• Deploy weblogic.xml file in WEB-INF inside myproject folder. Define so that library and class files inweb application are referred to first. Refer to the below as an example.true• Remove xmlbeans-x.x.x.jar file in WEB-INF/lib folder inside myproject folder.6.3.3.10.3.3The below additional work is needed for resolving library problems when installing CXF-JAXWS Plugin.• However, Plugins provided in Anyframe are developed based on Jetty, so they basically use 8080 port.Therefore, open cxf-jaxws-servlet.xml file, and change the 'http://localhost:8080/...' part to 'http://localhost:{JEUS use port}/...'.• Create EAR Folder. For instance, the following two folders can be created when project namedmyproject is packaged with ear.myproject.ear/ META-INF/ myproject• Deploy application.xml file in META-INF folder. Refer to the below as an example.Samplemyproject/myproject• Deploy weblogic-application.xml file in META-INF folder. Refer to the below as an example.javax.persistence.*• Deploy weblogic.xml file in WEB-INF inside myproject folder. Set so that library and class files in webapplication are referred to first. Refer to the below as an example.39

WAS(Web ApplicationServer) Configurationtrue• Using Apache CXF 2.3: The currently deployed Anyframe CXF-JAXWS Plugin depends on Apache CXF2.3 version. In this case, remove xercesImpl-x.x.x.jar file in WEB-INF/lib folder, and deploy in lib folderunder Weblogic domain to be used.[Reference] Using Apache CXF 2.2.7 : Previous version of Anyframe CXF Plugin depends on ApacheCXF 2.2.7 version. In this case, remove xercesImpl-x.x.x.jar and stax-api-x.x.jar files in WEB-INF/libfolder, and deploy xercesImpl-x.x.x.jar file only in lib folder under Weblogic domain to be used.• Remove xmlbeans-x.x.x.jar and geronimo-stax-api_1.0_spec-x.x.x.jar files in WEB-INF/lib folder insidemyproject folder.40