| |
| <!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 - Coding Guidelines"> |
| |
| |
| |
| |
| <title> |
| Apache CXF -- Coding Guidelines |
| </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 Software Foundation"><img width="214px" height="88" border="0" alt="ASF Logo" src="https://apache.org/img/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="coding-guidelines.html">Coding Guidelines</a> |
| <!-- Breadcrumbs --> |
| </div> |
| </td> |
| <td> |
| <div align="right"> |
| <!-- Quicklinks --> |
| <div id="quicklinks"><p><a shape="rect" href="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"><h3 id="Navigation-ApacheCXF"><a shape="rect" href="index.html">Apache CXF</a></h3><ul class="alternate"><li><a shape="rect" href="index.html">Home</a></li><li><a shape="rect" href="download.html">Download</a></li><li><a shape="rect" href="people.html">People</a></li><li><a shape="rect" href="project-status.html">Project Status</a></li><li><a shape="rect" href="roadmap.html">Roadmap</a></li><li><a shape="rect" href="mailing-lists.html">Mailing Lists</a></li><li><a shape="rect" class="external-link" href="http://issues.apache.org/jira/browse/CXF">Issue Reporting</a></li><li><a shape="rect" href="special-thanks.html">Special Thanks</a></li><li><a shape="rect" class="external-link" href="http://www.apache.org/licenses/">License</a></li><li><a shape="rect" href="security-advisories.html">Security Advisories</a></li></ul><h3 id="Navigation-Users">Users</h3><ul class="alternate"><li><a shape="rect" href="http://cxf.apache.org/docs/index.html">User's Guide</a></li><li><a shape="rect" href="support.html">Support</a></li><li><a shape="rect" href="faq.html">FAQ</a></li><li><a shape="rect" href="resources-and-articles.html">Resources and Articles</a></li></ul><h3 id="Navigation-Search">Search</h3><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> <h3 id="Navigation-Developers">Developers</h3><ul class="alternate"><li><a shape="rect" href="http://cxf.apache.org/docs/cxf-architecture.html">Architecture Guide</a></li><li><a shape="rect" href="source-repository.html">Source Repository</a></li><li><a shape="rect" href="building.html">Building</a></li><li><a shape="rect" href="automated-builds.html">Automated Builds</a></li><li><a shape="rect" href="testing-debugging.html">Testing-Debugging</a></li><li><a shape="rect" href="coding-guidelines.html">Coding Guidelines</a></li><li><a shape="rect" href="getting-involved.html">Getting Involved</a></li><li><a shape="rect" href="release-management.html">Release Management</a></li></ul><h3 id="Navigation-Subprojects">Subprojects</h3><ul class="alternate"><li><a shape="rect" href="distributed-osgi.html">Distributed OSGi</a></li><li><a shape="rect" href="xjc-utils.html">XJC Utils</a></li><li><a shape="rect" href="build-utils.html">Build Utils</a></li><li><a shape="rect" href="fediz.html">Fediz</a></li></ul><h3 id="Navigation-ASF"><a shape="rect" class="external-link" href="http://www.apache.org">ASF</a></h3><ul class="alternate"><li><a shape="rect" class="external-link" href="http://www.apache.org/foundation/how-it-works.html">How Apache Works</a></li><li><a shape="rect" class="external-link" href="http://www.apache.org/foundation/">Foundation</a></li><li><a shape="rect" class="external-link" href="http://www.apache.org/foundation/sponsorship.html">Sponsor Apache</a></li><li><a shape="rect" class="external-link" href="http://www.apache.org/foundation/thanks.html">Thanks</a></li><li><a shape="rect" class="external-link" href="http://www.apache.org/security/">Security</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"><h1 id="CodingGuidelines-Introduction">Introduction</h1><p>CXF makes use of both PMD and CheckStyle to enforce common coding conventions. However, not everything can be expressed in a rule in one of these systems. This page describes additional conventions and considerations.</p><h2 id="CodingGuidelines-CodeFormatting">Code Formatting</h2><p>We use an indent of 4 characters with spaces not tabs. The line length is 110 characters.<br clear="none"> For Eclipse there is a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/etc/eclipse/CXFCodeFormatter.xml" rel="nofollow">CXFCodeFormatter.xml</a> you can use.</p><h2 id="CodingGuidelines-Projectsandpackages(proposal)">Projects and packages (proposal)</h2><p>The package base for all CXF packages is "org.apache.cxf".</p><p>CXF is organized in maven projects. The groupId and artifactId of a project should relate to the base package name of the project. So for example<br clear="none"> a maven project with groupId="org.apache.cxf" and artifactId="cxf-rt-transports-http-jetty" should only contain packages below "org.apache.cxf.transports.http-jetty.*".</p><p>It should always be avoided to have the same package name in more than one maven project as this will cause a lot of trouble in OSGi.</p><h2 id="CodingGuidelines-CyclicDependencies(proposal)">Cyclic Dependencies (proposal)</h2><p>Cyclic dependencies between packages should be avoided as they make maintenance harder and make it more difficult to understand the architecture. Some more details can be found at: <a shape="rect" class="external-link" href="http://www.headwaysoftware.com/blog/2008/12/software-erosion-and-package-tangles/" rel="nofollow">Software erosion and package tangles</a></p><p>Every CXF committer can get a free license of the Architecture tool <a shape="rect" class="external-link" href="http://www.headwaysoftware.com/downloads/index.php?product=Structure101" rel="nofollow">structure 101</a> which is very helpful in finding and avoiding cyclic dependencies. Just tell them that you are committer at Apache CXF to get a free license.</p><h2 id="CodingGuidelines-CommonsXMLSchema">Commons XML Schema</h2><p>CXF makes internal use of the Apache Commons XML Schema. Web services are defined in terms of XML Schemas, and that library provides a data model.</p><p>The code from the XML Schema project provides almost no consistency checking. For each object in the model, it provides all the fields for all the possible settings. It does not provide or enforce a consistent discipline. It is very easy to write code that produces paradoxical schemas that have unexpected consequences. CXF includes some utilities that address some of these issues.</p><p>The XML Schema developers are very fond of 'final', so CXF does not have the option of using subclasses as a way to implement and enforce a model. Instead, CXF defines utilities and wrappers in org.apache.cxf.common.xmlschema.</p><h3 id="CodingGuidelines-ElementNamesandReferences">Element Names and References</h3><p>In the standard for XML Schema, an element can have a name (a QName) or a refName (another QName). Not both. Commons XML Schema provides the Element object with a QName, a Name, and a refName. The first is a string while the latter two are QNames.</p><p>The possibilities for inconsistency here are numerous. You can set the name to be different from the local part of the QName. You can set both a name and a refName.</p><p>To avoid this, use the functions in the XmlSchemaTools class. It provides functions for setting these three values.</p><p>CXF code should never call XmlSchemaElement.setName. The XMLSchemaTools functions will always set it, as a convenience value, to the local part of the refName or the QName, whichever is active.</p><p>CXF code should never call XmlSchemaElement.setQName or setRefName. Call XmlSchemaTools.setElementQName or <br clear="none"> XmlSchemaTools.setElementRefName. These function will throw an exception in the case of an inconsistency, and will also call setName<br clear="none"> with the local part.</p><h3 id="CodingGuidelines-TheSchemaCollection">The Schema Collection</h3><p>Each CXF service (or, if you prefer, WSDL), has a collection of XML schemas (schemata?). When one schema element refers to another with a qualified name, (e.g. type="bloop:Bleep"), the prefix is as defined for the current schema (or the WSDL as a whole), and the namespace referenced by the schema must be one of the schemas in the collection.</p><p>Commons XML Schema provides XmlSchemaCollection for this purpose. It has a number of, well, surprising characteristics. Generally, its authors gave much more thought to the case of reading schemas in from XML files than to creating them in a program. One example: each global type or element has to be presented to the collection API twice for it to be visible to the lookup APIs.</p><p>CXF wraps XmlSchemaCollection in the SchemaCollection class to deal with these items.</p><p><a shape="rect" class="external-link" href="http://www.docjar.com/docs/api/org/apache/cxf/common/xmlschema/FixedExtensionDeserializer.html" rel="nofollow"><code>FixedExtensionDeserializer</code></a> is a class that works around a specific XML Schema bug.</p></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=71542">edit page</a>) |
| (<a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=71542&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> |
| |
