cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF > Coding Guidelines
Date Tue, 21 May 2013 07:58:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/15/_/styles/combined.css?spaceKey=CXF&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF/Coding+Guidelines">Coding
Guidelines</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~christian%2Bschneider">Christian
Schneider</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >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. <br>
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h2.
Code Formatting <br> <br>We use an indent of 4 characters with spaces not tabs.
The line length is 110 characters. <br>For Eclipse there is a [CXFCodeFormatter.xml|http://svn.apache.org/repos/asf/cxf/trunk/etc/eclipse/CXFCodeFormatter.xml]
you can use. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h2. Projects and packages (proposal)
<br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="CodingGuidelines-Introduction"></a>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><a name="CodingGuidelines-CodeFormatting"></a>Code Formatting</h2>

<p>We use an indent of 4 characters with spaces not tabs. The line length is 110 characters.<br/>
For Eclipse there is a <a href="http://svn.apache.org/repos/asf/cxf/trunk/etc/eclipse/CXFCodeFormatter.xml"
class="external-link" rel="nofollow">CXFCodeFormatter.xml</a> you can use.</p>

<h2><a name="CodingGuidelines-Projectsandpackages%28proposal%29"></a>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/>
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><a name="CodingGuidelines-CyclicDependencies%28proposal%29"></a>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 href="http://www.headwaysoftware.com/blog/2008/12/software-erosion-and-package-tangles/"
class="external-link" rel="nofollow">Software erosion and package tangles</a></p>

<p>Every CXF committer can get a free license of the Architecture tool <a href="http://www.headwaysoftware.com/downloads/index.php?product=Structure101"
class="external-link" rel="nofollow">structure 101</a> which is very helpfull in
finding and avoiding cyclic dependencies. Just tell them that you are committer at Apache
CXF to get a free license.</p>

<h2><a name="CodingGuidelines-CommonsXMLSchema"></a>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><a name="CodingGuidelines-ElementNamesandReferences"></a>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/>
XmlSchemaTools.setElementRefName. These function will throw an exception in the case of an
inconsistency, and will also call setName<br/>
with the local part.</p>

<h3><a name="CodingGuidelines-TheSchemaCollection"></a>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 href="http://www.docjar.com/docs/api/org/apache/cxf/common/xmlschema/FixedExtensionDeserializer.html"
class="external-link" rel="nofollow"><tt>FixedExtensionDeserializer</tt></a>
is a class that works around a specific XML Schema bug.</p>


    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CXF/Coding+Guidelines">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=71542&revisedVersion=4&originalVersion=3">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CXF/Coding+Guidelines?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message