| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html> |
| <head> |
| |
| <link type="text/css" rel="stylesheet" href="/resources/site.css"> |
| <script src='/resources/space.js'></script> |
| |
| <meta http-equiv="Content-type" content="text/html;charset=UTF-8"> |
| <meta name="keywords" content="business integration, EAI, SOA, Service Oriented Architecture, web services, SOAP, JBI, JMS, WSDL, XML, EDI, Electronic Data Interchange, standards support, integration standards, application integration, middleware, software, solutions, services, CXF, open source"> |
| <meta name="description" content="Apache CXF, Services Framework - Simple Frontend"> |
| |
| |
| <link type="text/css" rel="stylesheet" href="/resources/highlighter/styles/shCoreCXF.css"> |
| <link type="text/css" rel="stylesheet" href="/resources/highlighter/styles/shThemeCXF.css"> |
| |
| <script src='/resources/highlighter/scripts/shCore.js'></script> |
| <script src='/resources/highlighter/scripts/shBrushXml.js'></script> |
| <script src='/resources/highlighter/scripts/shBrushJava.js'></script> |
| <script> |
| SyntaxHighlighter.defaults['toolbar'] = false; |
| SyntaxHighlighter.all(); |
| </script> |
| |
| |
| <title> |
| Apache CXF -- Simple Frontend |
| </title> |
| </head> |
| <body onload="init()"> |
| |
| |
| <table width="100%" cellpadding="0" cellspacing="0"> |
| <tr> |
| <td id="cell-0-0" colspan="2"> </td> |
| <td id="cell-0-1"> </td> |
| <td id="cell-0-2" colspan="2"> </td> |
| </tr> |
| <tr> |
| <td id="cell-1-0"> </td> |
| <td id="cell-1-1"> </td> |
| <td id="cell-1-2"> |
| <!-- Banner --> |
| <div class="banner" id="banner"><div><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr><td align="left" colspan="1" nowrap> |
| <a shape="rect" href="http://cxf.apache.org/" title="Apache CXF"><span style="font-weight: bold; font-size: 170%; color: white">Apache CXF</span></a> |
| </td><td align="right" colspan="1" nowrap> |
| <a shape="rect" href="http://www.apache.org/" title="The Apache Sofware Foundation"><img border="0" alt="ASF Logo" src="http://cxf.apache.org/images/asf-logo.png"></a> |
| </td></tr></table></div></div> |
| <!-- Banner --> |
| <div id="top-menu"> |
| <table border="0" cellpadding="1" cellspacing="0" width="100%"> |
| <tr> |
| <td> |
| <div align="left"> |
| <!-- Breadcrumbs --> |
| <a href="index.html">Index</a> > <a href="frontends.html">Frontends</a> > <a href="simple.html">Simple</a> > <a href="simple-frontend.html">Simple Frontend</a> |
| <!-- Breadcrumbs --> |
| </div> |
| </td> |
| <td> |
| <div align="right"> |
| <!-- Quicklinks --> |
| <div id="quicklinks"><p><a shape="rect" href="http://cxf.apache.org/download.html">Download</a> | <a shape="rect" href="http://cxf.apache.org/docs/index.html">Documentation</a></p></div> |
| <!-- Quicklinks --> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </td> |
| <td id="cell-1-3"> </td> |
| <td id="cell-1-4"> </td> |
| </tr> |
| <tr> |
| <td id="cell-2-0" colspan="2"> </td> |
| <td id="cell-2-1"> |
| <table> |
| <tr valign="top"> |
| <td height="100%"> |
| <div id="wrapper-menu-page-right"> |
| <div id="wrapper-menu-page-top"> |
| <div id="wrapper-menu-page-bottom"> |
| <div id="menu-page"> |
| <!-- NavigationBar --> |
| <div id="navigation"><ul class="alternate"><li><a shape="rect" href="overview.html">Overview</a></li><li><a shape="rect" href="how-tos.html">How-Tos</a></li><li><a shape="rect" href="frontends.html">Frontends</a></li><li><a shape="rect" href="databindings.html">DataBindings</a></li><li><a shape="rect" href="transports.html">Transports</a></li><li><a shape="rect" href="configuration.html">Configuration</a></li><li><a shape="rect" href="debugging-and-logging.html">Debugging and Logging</a></li><li><a shape="rect" href="tools.html">Tools</a></li><li><a shape="rect" href="restful-services.html">RESTful Services</a></li><li><a shape="rect" href="wsdl-bindings.html">WSDL Bindings</a></li><li><a shape="rect" href="service-routing.html">Service Routing</a></li><li><a shape="rect" href="dynamic-languages.html">Dynamic Languages</a></li><li><a shape="rect" href="ws-support.html">WS-* Support</a></li><li><a shape="rect" href="advanced-integration.html">Advanced Integration</a></li><li><a shape="rect" href="deployment.html">Deployment</a></li><li><a shape="rect" href="schemas-and-namespaces.html">Use of Schemas and Namespaces</a></li></ul><hr><ul class="alternate"><li><p>Search</p></li></ul><form enctype="application/x-www-form-urlencoded" method="get" id="cse-search-box" action="http://www.google.com/cse"> |
| <div> |
| <input type="hidden" name="cx" value="002890367768291051730:o99qiwa09y4"> |
| <input type="hidden" name="ie" value="UTF-8"> |
| <input type="text" name="q" size="21"> |
| <input type="submit" name="sa" value="Search"> |
| </div> |
| </form> |
| <script type="text/javascript" src="http://www.google.com/cse/brand?form=cse-search-box&lang=en"></script><hr><ul class="alternate"><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest/">API 3.2.x (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest-3.1.x/">API 3.1.x (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/">CXF Website</a></li></ul><p> </p><p><a shape="rect" class="external-link" href="http://www.apache.org/events/current-event.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://www.apache.org/events/current-event-125x125.png" data-image-src="http://www.apache.org/events/current-event-125x125.png"></span></a></p></div> |
| <!-- NavigationBar --> |
| </div> |
| </div> |
| </div> |
| </div> |
| </td> |
| <td height="100%"> |
| <!-- Content --> |
| <div class="wiki-content"> |
| <div id="ConfluenceContent"><p>CXF provides the 'simple' frontend to map Java APIs to and from WSDL models for web services. The simple front end is much like <a shape="rect" href="jax-ws.html">JAX-WS</a>, however, where JAX-WS uses Java annotations to specify detailed configuration (and, indeed, requires a few), Simple is willing to map a 'naked' interface or class to a service, and respects some configuration options from .aegis.xml files shared with the Aegis data binding.</p> |
| |
| <div class="confluence-information-macro confluence-information-macro-note"><p class="title">Most Applications Should Use JAX-WS</p><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"> |
| <p>The JAX-WS frontend is far more flexible than the Simple frontend. There are only two reasons to select Simple over JAX-WS:</p> |
| <ol><li>You must avoid the use of Java annotations. JAX-WS requires them, Simple does not.</li><li>You want to have the absolutely smallest possible collection of additional dependencies. JAX-WS has more dependencies than Simple.</li></ol> |
| |
| |
| <p>Other than these items, Simple has no advantages over JAX-WS. The implementation classes of JAX-WS in CXF are all subclasses of the implementation classes of Simple. In a 'simple' case, very nearly identical things happen in the Simple front end as in JAX-WS. CXF's extensions to JAX-WS, on the other hand, make it very 'simple' to use.</p></div></div> |
| <h2 id="SimpleFrontend-SimplePitfall:UnreliableParameterNames">Simple Pitfall: Unreliable Parameter Names</h2> |
| |
| <p>The typical pattern of a web service is to define a Service Endpoint Interface and then create a class that implements that interface. When you own both ends of the process, you can simply use the SEI in both the server and the client.</p> |
| |
| <p>The problem has to do with a quirk of Java reflection. If a program uses Java reflection to examine a concrete method of a class, the data available <strong>may</strong> provide the parameter names from the source. The behavior of current Java compilers depends on whether you ask them to provide debug symbols. However, if a program uses reflection to look at an <strong>abstract method</strong>, current Java compilers <strong>never</strong> provide the parameter names. </p> |
| |
| <p>If there are no names, Simple creates ugly parameters named <code>arg0</code>, <code>arg1</code>, ... Further, if you forget to specify the SEI when creating a service, and only provide the SEB, Simple will see your concrete methods and assign actual parameter names (if you have debug symbols). If you client uses the SEI, they won't communicate. If you change your mind about debug symbols, you will change the contract.</p> |
| |
| <p>Thus, while JAX-WS <code>@WebParam</code> annotations may seem noisy and inconvenient, they are, in fact, ensuring that your service has a consistent contract.</p> |
| |
| <p>If you choose to use the Simple front end, you will need to use <code>parameter</code> elements in a <code>.aegis.xml</code> file to give useful names, or be sure to provide the SEI to the <code>ServerFactoryBean</code>. </p> |
| |
| <h2 id="SimpleFrontend-SimpleandDataBindings">Simple and Data Bindings</h2> |
| |
| <p>By default CXF uses the JAXB databinding. This is a historical default, but often not what you will want, both due to the pitfall described above and the JAX-B issue described at the bottom of this page. If you choose to use the Simple front end, we recommend that you use <a shape="rect" href="aegis-21.html">the Aegis databinding</a>.</p> |
| |
| <h2 id="SimpleFrontend-ServerFactoryBean–MakingaServiceEndpoint">ServerFactoryBean – Making a Service Endpoint</h2> |
| <p>The ServerFactoryBean produces a Server instance for you. It requires a service class and an address to publish the service on. By creating a Server you'll have started your service and made it available to the outside world.</p> |
| |
| <p>First you'll want to create your service class:</p> |
| <div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default"> |
| public interface HelloWorld { |
| String sayHi(String text); |
| } |
| </pre> |
| </div></div> |
| <p>This does not have to be an interface, but we're going to use an interface for this example because</p> |
| <ol><li>It is good to separate out your service contract (your interface) from your implementation</li><li>This allows us to easily create a Java Proxy client</li></ol> |
| |
| |
| <p>We'll also need an implementation class:</p> |
| <div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default"> |
| public class HelloWorldImpl implements HelloWorld { |
| public String sayHi(String text) { |
| return "Hello " + text; |
| } |
| } |
| </pre> |
| </div></div> |
| |
| <p>And now we'll want to create a Server from this</p> |
| <div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default"> |
| import org.apache.cxf.frontend.ServerFactoryBean; |
| ... |
| |
| // Create our service implementation |
| HelloWorldImpl helloWorldImpl = new HelloWorldImpl(); |
| |
| // Create our Server |
| ServerFactoryBean svrFactory = new ServerFactoryBean(); |
| svrFactory.setServiceClass(HelloWorld.class); |
| svrFactory.setAddress("http://localhost:9000/Hello"); |
| svrFactory.setServiceBean(helloWorldImpl); |
| svrFactory.create(); |
| </pre> |
| </div></div> |
| |
| <p>Your service is now started! You can access the wsdl at "<a shape="rect" class="external-link" href="http://localhost:9000/Hello?wsdl" rel="nofollow">http://localhost:9000/Hello?wsdl</a>".</p> |
| |
| <h2 id="SimpleFrontend-ClientProxyFactoryBean–MakingaClientProxy">ClientProxyFactoryBean – Making a Client Proxy</h2> |
| <p>You'll also want to create a client for your service. CXF includes a ClientProxyFactoryBean which will create a Java proxy for you from your interface which will invoke the service.</p> |
| |
| <div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default"> |
| import demo.hw.server.HelloWorld; |
| import org.apache.cxf.frontend.ClientProxyFactoryBean; |
| ... |
| |
| ClientProxyFactoryBean factory = new ClientProxyFactoryBean(); |
| factory.setServiceClass(HelloWorld.class); |
| factory.setAddress("http://localhost:9000/Hello"); |
| HelloWorld client = (HelloWorld) factory.create(); |
| </pre> |
| </div></div> |
| |
| <p>You simply need to set your service class and your service's URL on the bean. Calling create() will then create a proxy for you based on your interface.</p> |
| |
| <h2 id="SimpleFrontend-ConfigurewithSpring">Configure with Spring </h2> |
| |
| <p>The XML configuration for do-it-yourself Spring beans and cxf.xml or cxf-servlet.xml are all very similiar. <br clear="none"> |
| The simple front-end does not have its own extension, so you don't need any extra imports if are setting up your<br clear="none"> |
| own application context.</p> |
| |
| <p>Here's an example cxf-servlet.xml with simple front end endpoint configuration. If you use your own application context, you'll need to import the soap extension and http servlet extension. </p> |
| |
| <div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default"> |
| <beans xmlns="http://www.springframework.org/schema/beans" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xmlns:simple="http://cxf.apache.org/simple" |
| xmlns:soap="http://cxf.apache.org/bindings/soap" |
| xsi:schemaLocation=" |
| http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd |
| http://cxf.apache.org/bindings/soap http://cxf.apache.org/schemas/configuration/soap.xsd |
| http://cxf.apache.org/simple http://cxf.apache.org/schemas/simple.xsd"> |
| |
| <simple:server id="pojoservice" serviceClass="demo.hw.server.HelloWorld" address="/hello_world"> |
| <simple:serviceBean> |
| <bean class="demo.hw.server.HelloWorldImpl" /> |
| </simple:serviceBean> |
| </simple:server> |
| </beans> |
| </pre> |
| </div></div> |
| |
| <h2 id="SimpleFrontend-DeployingSimpleFrontEndservicetoacontainer">Deploying Simple FrontEnd service to a container</h2> |
| <p>If you are looking to deploy the service to a container follow the steps in "Transports->HTTP Transport -> Servlet Transport" section from the Table of contents. Add the xml content from the above section "Configure cxf-servlet.xml". Name your configuration file as say services.xml. Do not name it as cxf-servlet.xml.<br clear="none"> |
| You need to add the import statements from the sample configuration file in "Transports->HTTP Transport -> Servlet Transport"</p> |
| |
| <h2 id="SimpleFrontend-Well-KnownIssue">Well-Known Issue</h2> |
| <div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"> |
| <p>There is a known issue for the JAXB data binding with POJO, please see Dan Kulp's comment in <a shape="rect" class="external-link" href="https://issues.apache.org/jira/browse/CXF-897">https://issues.apache.org/jira/browse/CXF-897</a> .<br clear="none"> |
| If you want to use JAXB binding you should use the <a shape="rect" href="jax-ws.html">JAX-WS</a> Frontend. Mixing Simple Frontend and JAXB binding leads to problems. The article <a shape="rect" href="a-simple-jax-ws-service.html">A simple JAX-WS service</a> shows a code first JAX-WS service that is almost as easy to use as the Simple Frontend.</p></div></div></div> |
| </div> |
| <!-- Content --> |
| </td> |
| </tr> |
| </table> |
| </td> |
| <td id="cell-2-2" colspan="2"> </td> |
| </tr> |
| <tr> |
| <td id="cell-3-0"> </td> |
| <td id="cell-3-1"> </td> |
| <td id="cell-3-2"> |
| <div id="footer"> |
| <!-- Footer --> |
| <div id="site-footer"> |
| <a href="http://cxf.apache.org/privacy-policy.html">Privacy Policy</a> - |
| (<a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=49556">edit page</a>) |
| (<a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=49556&showComments=true&showCommentArea=true#addcomment">add comment</a>)<br> |
| Apache CXF, CXF, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.<br> |
| All other marks mentioned may be trademarks or registered trademarks of their respective owners. |
| </div> |
| <!-- Footer --> |
| </div> |
| </td> |
| <td id="cell-3-3"> </td> |
| <td id="cell-3-4"> </td> |
| </tr> |
| <tr> |
| <td id="cell-4-0" colspan="2"> </td> |
| <td id="cell-4-1"> </td> |
| <td id="cell-4-2" colspan="2"> </td> |
| </tr> |
| </table> |
| |
| <script type="text/javascript"> |
| var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); |
| document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); |
| </script> |
| <script type="text/javascript"> |
| try { |
| var pageTracker = _gat._getTracker("UA-4458903-1"); |
| pageTracker._trackPageview(); |
| } catch(err) {}</script> |
| |
| </body> |
| </html> |
| |
