Google Git
Sign in
eclipse / www.eclipse.org / smila / 4d9b0a6ca03ce45766f7d9cc111d87c752b4ddc9 / . / documentation / 1.0 / wiki.eclipse.org / SMILA / Development_Guidelines.1.html
blob: 730bdf5e8d49593336b875bbe0adab3c413e69d0 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="keywords" content="SMILA/Development Guidelines,SMILA/Development Guidelines/3rd party bundle,SMILA/Development Guidelines/Create a bundle (plug-in),SMILA/Development Guidelines/Declarative Services,SMILA/Development Guidelines/How to implement a Crawler,SMILA/Development Guidelines/How to integrate new bundle into build process,SMILA/Development Guidelines/How to integrate test bundle into build process,SMILA/Development Guidelines/Howto build a SMILA-Distribution,SMILA/Development Guidelines/Introduction to make.xml,SMILA/Development Guidelines/Setup for JAXB code generation,SMILA/HowTo" />
<link rel="shortcut icon" href="http://wiki.eclipse.org/SMILA/favicon.ico" />
<link rel="search" type="application/opensearchdescription+xml" href="http://wiki.eclipse.org/opensearch_desc.php" title="Eclipsepedia (English)" />
<link rel="alternate" type="application/rss+xml" title="Eclipsepedia RSS Feed" href="http://wiki.eclipse.org/index.php?title=Special:Recentchanges&amp;feed=rss" />
<link rel="alternate" type="application/atom+xml" title="Eclipsepedia Atom Feed" href="http://wiki.eclipse.org/index.php?title=Special:Recentchanges&amp;feed=atom" />
<title>SMILA/Development Guidelines - Eclipsepedia</title>
<style type="text/css" media="screen,projection">/*<![CDATA[*/ @import "/skins/eclipsenova/novaWide.css?116"; /*]]>*/</style>
<link rel="stylesheet" type="text/css" media="print" href="http://wiki.eclipse.org/skins/eclipsenova/eclipsenovaPrint.css?116" />
<link rel="stylesheet" type="text/css" media="handheld" href="http://wiki.eclipse.org/skins/eclipsenova/handheld.css?116" />
<link rel="stylesheet" type="text/css" href="http://wiki.eclipse.org/skins/eclipsenova/Nova/css/header.css" media="screen" />
<link rel="stylesheet" type="text/css" href="http://wiki.eclipse.org/skins/eclipsenova/tabs.css" media="screen" />
<link rel="stylesheet" type="text/css" href="http://wiki.eclipse.org/skins/eclipsenova/Nova/css/visual.css" media="screen" />
<link rel="stylesheet" type="text/css" href="http://wiki.eclipse.org/skins/eclipsenova/Nova/css/layout.css" media="screen" />
<link rel="stylesheet" type="text/css" href="http://wiki.eclipse.org/skins/eclipsenova/Nova/css/footer.css" media="screen" />
<!--[if IE]><link rel="stylesheet" type="text/css" href="/skins/eclipsenova/IEpngfix.css" media="screen" /><![endif]-->
<!--[if lt IE 5.5000]><style type="text/css">@import "/skins/eclipsenova/IE50Fixes.css?116";</style> <![endif]-->
<!--[if IE 5.5000]><style type="text/css">@import "/skins/eclipsenova/IE55Fixes.css?116";</style><![endif]-->
<!--[if IE 6]><style type="text/css">@import "/skins/eclipsenova/IE60Fixes.css?116";</style><![endif]-->
<!--[if IE 7]><style type="text/css">@import "/skins/eclipsenova/IE70Fixes.css?116";</style><![endif]-->
<!--[if lt IE 7]><script type="text/javascript" src="/skins/common/IEFixes.js?116"></script>
<meta http-equiv="imagetoolbar" content="no" /><![endif]-->
<script type= "text/javascript">/*<![CDATA[*/
var skin = "eclipsenova";
var stylepath = "/skins";
var wgArticlePath = "/$1";
var wgScriptPath = "";
var wgScript = "/index.php";
var wgServer = "http://wiki.eclipse.org";
var wgCanonicalNamespace = "";
var wgCanonicalSpecialPageName = false;
var wgNamespaceNumber = 0;
var wgPageName = "SMILA/Development_Guidelines";
var wgTitle = "SMILA/Development Guidelines";
var wgAction = "view";
var wgRestrictionEdit = [];
var wgRestrictionMove = [];
var wgArticleId = "15197";
var wgIsArticle = true;
var wgUserName = null;
var wgUserGroups = null;
var wgUserLanguage = "en";
var wgContentLanguage = "en";
var wgBreakFrames = false;
var wgCurRevisionId = "286078";
var wgVersion = "1.12.0";
var wgEnableAPI = true;
var wgEnableWriteAPI = false;
/*]]>*/</script>
<script type="text/javascript" src="http://wiki.eclipse.org/skins/common/wikibits.js?116"><!-- wikibits js --></script>
<!-- Performance mods similar to those for bug 166401 -->
<script type="text/javascript" src="http://wiki.eclipse.org/index.php?title=-&amp;action=raw&amp;gen=js&amp;useskin=eclipsenova"><!-- site js --></script>
<!-- Head Scripts -->
<script type="text/javascript" src="http://wiki.eclipse.org/skins/common/ajax.js?116"></script>
<style type="text/css">/*<![CDATA[*/
.source-java {line-height: normal; font-size: medium;}
.source-java li {line-height: normal;}
/**
* GeSHi Dynamically Generated Stylesheet
* --------------------------------------
* Dynamically generated stylesheet for java
* CSS class: source-java, CSS id:
* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter)
*/
.source-java .de1, .source-java .de2 {font-family: 'Courier New', Courier, monospace; font-weight: normal;}
.source-java {}
.source-java .head {}
.source-java .foot {}
.source-java .imp {font-weight: bold; color: red;}
.source-java .ln-xtra {color: #cc0; background-color: #ffc;}
.source-java li {font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;}
.source-java li.li2 {font-weight: bold;}
.source-java .kw1 {color: #7F0055; font-weight: bold;}
.source-java .kw2 {color: #7F0055; font-weight: bold;}
.source-java .kw3 {color: #000000; font-weight: normal}
.source-java .kw4 {color: #7F0055; font-weight: bold;}
.source-java .co1 {color: #3F7F5F; font-style: italic;}
.source-java .co2 {color: #3F7F5F;}
.source-java .co3 {color: #3F7F5F; font-style: italic; font-weight: bold;}
.source-java .coMULTI {color: #3F5FBF; font-style: italic;}
.source-java .es0 {color: #000000;}
.source-java .br0 {color: #000000;}
.source-java .st0 {color: #2A00ff;}
.source-java .nu0 {color: #000000;}
.source-java .me1 {color: #000000;}
.source-java .me2 {color: #000000;}
/*]]>*/
</style>
<style type="text/css">/*<![CDATA[*/
@import "/index.php?title=MediaWiki:Geshi.css&usemsgcache=yes&action=raw&ctype=text/css&smaxage=18000";
/*]]>*/
</style><link rel="stylesheet" type="text/css" href="Development_Guidelines.1.html" /> </head>
<body class="mediawiki ns-0 ltr page-SMILA_Development_Guidelines">
<div id="globalWrapper">
<div id="column-one">
<!-- Eclipse Additions for the Top Nav start here M. Ward-->
<div id="header">
<div id="header-graphic">
<img src="http://wiki.eclipse.org/skins/eclipsenova/eclipse.png" alt="Eclipse Wiki">
</div>
<!-- Pulled 101409 Mward -->
<div class="portlet" id="p-personal">
<div class="pBody">
<ul>
<li id="pt-login"><a href="http://wiki.eclipse.org/index.php?title=Special:Userlogin&amp;returnto=SMILA/Development_Guidelines">Log in</a></li>
</ul>
</div>
</div>
<div id="header-icons">
<div id="sites">
<ul id="sitesUL">
<li><a href="http://www.eclipse.org"><img src="http://dev.eclipse.org/custom_icons/eclipseIcon.png" width="28" height="28" alt="Eclipse Foundation" title="Eclipse Foundation" /><div>Eclipse Foundation</div></a></li>
<li><a href="http://marketplace.eclipse.org"><img src="http://dev.eclipse.org/custom_icons/marketplace.png" width="28" height="28" alt="Eclipse Marketplace" title="Eclipse Marketplace" /><div>Eclipse Marketplace</div></a></li>
<li><a href="https://bugs.eclipse.org/bugs"><img src="http://dev.eclipse.org/custom_icons/system-search-bw.png" width="28" height="28" alt="Bugzilla" title="Bugzilla" /><div>Bugzilla</div></a></li>
<li><a href="http://live.eclipse.org"><img src="http://dev.eclipse.org/custom_icons/audio-input-microphone-bw.png" width="28" height="28" alt="Live" title="Live" /><div>Eclipse Live</div></a></li>
<li><a href="http://planeteclipse.org"><img src="http://dev.eclipse.org/large_icons/devices/audio-card.png" width="28" height="28" alt="PlanetEclipse" title="Planet" /><div>Planet Eclipse</div></a></li>
<li><a href="http://portal.eclipse.org"><img src="http://dev.eclipse.org/custom_icons/preferences-system-network-proxy-bw.png" width="28" height="28" alt="Portal" title="Portal" /><div>My Foundation Portal</div></a></li>
</ul>
</div>
</div>
</div>
<!-- NEW HEADER STUFF HERE -->
<div id="header-menu">
<div id="header-nav">
<ul> <li><a class="first_one" href="http://wiki.eclipse.org/" target="_self">Home</a></li> <li><a href="http://www.eclipse.org/downloads/" target="_self">Downloads</a></li>
<li><a href="http://www.eclipse.org/users/" target="_self">Users</a></li>
<li><a href="http://www.eclipse.org/membership/" target="_self">Members</a></li>
<li><a href="http://wiki.eclipse.org/index.php/Development_Resources" target="_self">Committers</a></li>
<li><a href="http://www.eclipse.org/resources/" target="_self">Resources</a></li>
<li><a href="http://www.eclipse.org/projects/" target="_self">Projects</a></li>
<li><a href="http://www.eclipse.org/org/" target="_self">About Us</a></li>
</ul>
</div>
<div id="header-utils">
<!-- moved the search window here -->
<form action="http://wiki.eclipse.org/Special:Search" >
<input class="input" name="search" type="text" accesskey="f" value="" />
<input type='submit' onclick="this.submit();" name="go" id="searchGoButton" class="button" title="Go to a page with this exact name if one exists" value="Go" />&nbsp;
<input type='submit' onclick="this.submit();" name="fulltext" class="button" id="mw-searchButton" title="Search Eclipsepedia for this text" value="Search" />
</form>
</div>
</div>
<!-- Eclipse Additions for the Header stop here -->
<!-- Additions and mods for leftside nav Start here -->
<!--Started nav rip here-->
<!-- these are the nav controls main page, changes etc -->
<div id="novaContent" class="faux">
<div id="leftcol">
<ul id="leftnav">
<!-- these are the page controls, edit history etc -->
<li class="separator"><a class="separator">Navigation &#160;&#160;</li>
<li id="n-mainpage"><a href="http://wiki.eclipse.org/Main_Page">Main Page</a></li>
<li id="n-portal"><a href="http://wiki.eclipse.org/Eclipsepedia:Community_Portal">Community portal</a></li>
<li id="n-currentevents"><a href="http://wiki.eclipse.org/Eclipsepedia:Current_events">Current events</a></li>
<li id="n-recentchanges"><a href="http://wiki.eclipse.org/Special:Recentchanges">Recent changes</a></li>
<li id="n-randompage"><a href="http://wiki.eclipse.org/Special:Random">Random page</a></li>
<li id="n-help"><a href="http://wiki.eclipse.org/Help:Contents">Help</a></li>
<li class="separator"><a class="separator">Toolbox &#160;&#160;</a></li>
<li id="t-whatlinkshere"><a href="http://wiki.eclipse.org/Special:Whatlinkshere/SMILA/Development_Guidelines">What links here</a></li>
<li id="t-recentchangeslinked"><a href="http://wiki.eclipse.org/Special:Recentchangeslinked/SMILA/Development_Guidelines">Related changes</a></li>
<!-- This is the toolbox section -->
<li id="t-upload"><a href="http://wiki.eclipse.org/Special:Upload">Upload file</a></li>
<li id="t-specialpages"><a href="http://wiki.eclipse.org/Special:Specialpages">Special pages</a></li>
<li id="t-print"><a href="http://wiki.eclipse.org/index.php?title=SMILA/Development_Guidelines&amp;printable=yes">Printable version</a></li> <li id="t-permalink"><a href="http://wiki.eclipse.org/index.php?title=SMILA/Development_Guidelines&amp;oldid=286078">Permanent link</a></li> </ul>
</div>
<!-- Additions and mods for leftside nav End here -->
<div id="column-content">
<div id="content">
<a name="top" id="top"></a>
<div id="tabs">
<ul class="primary">
<li class="active"><a href="Development_Guidelines.1.html"><span class="tab">Page</span></a></li>
<li><a href="http://wiki.eclipse.org/index.php?title=Talk:SMILA/Development_Guidelines&amp;action=edit"><span class="tab">Discussion</span></a></li>
<li><a href="http://wiki.eclipse.org/index.php?title=SMILA/Development_Guidelines&amp;action=edit"><span class="tab">View source</span></a></li>
<li><a href="http://wiki.eclipse.org/index.php?title=SMILA/Development_Guidelines&amp;action=history"><span class="tab">History</span></a></li>
<li><a href="http://wiki.eclipse.org/index.php?title=Special:Userlogin&amp;returnto=SMILA/Development%20Guidelines"><span class="tab">Edit</span></a></li>
</ul>
</div>
<script type="text/javascript"> if (window.isMSIE55) fixalpha(); </script>
<h1 class="firstHeading">SMILA/Development Guidelines</h1>
<div id="bodyContent">
<h3 id="siteSub">From Eclipsepedia</h3>
<div id="contentSub"><span class="subpages">&lt; <a href="../SMILA.html" title="SMILA">SMILA</a></span></div>
<div id="jump-to-nav">Jump to: <a href="Development_Guidelines.1.html#column-one">navigation</a>, <a href="Development_Guidelines.1.html#searchInput">search</a></div> <!-- start content -->
<p>This page covers a collection of development guidelines whose compliance should ensure that SMILA appears as a unified product rather than as a loose collection of parts worked on by a variety of individuals each with their own styles and ways of working. Furthermore it contains information on the used software components and requirements and provides descriptions (how-tos) of common tasks (e.g. setting up the development environment).
</p>
<table id="toc" class="toc" summary="Contents"><tr><td><div id="toctitle"><h2>Contents</h2></div>
<ul>
<li class="toclevel-1"><a href="Development_Guidelines.1.html#How-to_manuals"><span class="tocnumber">1</span> <span class="toctext">How-to manuals</span></a></li>
<li class="toclevel-1"><a href="Development_Guidelines.1.html#Development_requirements"><span class="tocnumber">2</span> <span class="toctext">Development requirements</span></a>
<ul>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Official_JVM"><span class="tocnumber">2.1</span> <span class="toctext">Official JVM</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#OSGi_runtime"><span class="tocnumber">2.2</span> <span class="toctext">OSGi runtime</span></a></li>
</ul>
</li>
<li class="toclevel-1"><a href="Development_Guidelines.1.html#Development_conventions"><span class="tocnumber">3</span> <span class="toctext">Development conventions</span></a>
<ul>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Description_of_make.xml"><span class="tocnumber">3.1</span> <span class="toctext">Description of make.xml</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Continuous_integration"><span class="tocnumber">3.2</span> <span class="toctext">Continuous integration</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#File_header_.26_copyright_notice"><span class="tocnumber">3.3</span> <span class="toctext">File header &amp; copyright notice</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Eclipse_code_formatter_profile"><span class="tocnumber">3.4</span> <span class="toctext">Eclipse code formatter profile</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Checkstyle"><span class="tocnumber">3.5</span> <span class="toctext">Checkstyle</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Creation_of_bundles"><span class="tocnumber">3.6</span> <span class="toctext">Creation of bundles</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Version_number"><span class="tocnumber">3.7</span> <span class="toctext">Version number</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#XML_schemas.2C_namespace_convention.2C_and_versioning"><span class="tocnumber">3.8</span> <span class="toctext">XML schemas, namespace convention, and versioning</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Naming_conventions_for_launch_files_.28.launch.29"><span class="tocnumber">3.9</span> <span class="toctext">Naming conventions for launch files (.launch)</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Generated_source_code_goes_into_code.2Fgen_source_folder_.28like_Jaxb.29"><span class="tocnumber">3.10</span> <span class="toctext">Generated source code goes into code/gen source folder (like Jaxb)</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Sources_of_third_party_bundles"><span class="tocnumber">3.11</span> <span class="toctext">Sources of third party bundles</span></a></li>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#Logging_guidelines"><span class="tocnumber">3.12</span> <span class="toctext">Logging guidelines</span></a>
<ul>
<li class="toclevel-3"><a href="Development_Guidelines.1.html#When_to_use_what_log_level_and_what_information_to_provide.3F"><span class="tocnumber">3.12.1</span> <span class="toctext">When to use what log level and what information to provide?</span></a></li>
</ul>
</li>
</ul>
</li>
<li class="toclevel-1"><a href="Development_Guidelines.1.html#Used_technologies"><span class="tocnumber">4</span> <span class="toctext">Used technologies</span></a>
<ul>
<li class="toclevel-2"><a href="Development_Guidelines.1.html#OSGi_related_information"><span class="tocnumber">4.1</span> <span class="toctext">OSGi related information</span></a></li>
</ul>
</li>
</ul>
</td></tr></table><script type="text/javascript"> if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); } </script>
<a name="How-to_manuals"></a><h2> <span class="mw-headline"> How-to manuals </span></h2>
<p>Find a list of How-To manuals at <a href="HowTo.html" class="mw-redirect" title="SMILA/HowTo">SMILA How-to manuals</a>.
</p>
<a name="Development_requirements"></a><h2> <span class="mw-headline"> Development requirements </span></h2>
<a name="Official_JVM"></a><h3> <span class="mw-headline"> Official JVM </span></h3>
<p>The officially JVM needed for this project is &gt; Java 1.6.0_04. (see <a href="http://dev.eclipse.org/mhonarc/lists/smila-dev/msg00682.html" class="external text" title="http://dev.eclipse.org/mhonarc/lists/smila-dev/msg00682.html" rel="nofollow">Mail</a>)
</p>
<a name="OSGi_runtime"></a><h3> <span class="mw-headline"> OSGi runtime </span></h3>
<p>The OSGi implementation of Equinox of Eclipse 3.5 (Galileo) or later and the corresponding OSGi specification(s).
Currently SMILA is by default targeted to Eclipse 3.7.x.
&nbsp;
</p>
<a name="Development_conventions"></a><h2> <span class="mw-headline"> Development conventions </span></h2>
<a name="Description_of_make.xml"></a><h3> <span class="mw-headline"> Description of make.xml </span></h3>
<p>For a description of the build file <tt>make.xml</tt> refer to <a href="Development_Guidelines/Introduction_to_make.xml.html" title="SMILA/Development Guidelines/Introduction to make.xml">Introduction to make.xml</a>.
</p>
<a name="Continuous_integration"></a><h3> <span class="mw-headline"> Continuous integration </span></h3>
<p>Everyone should be aware of the following workflow with Bamboo:
</p><p>Bamboo should improve the source code quality but it should not be used as a (JUnit) test server.
Therefore each developer should check his code before committing it to subversion regarding:
</p>
<ul><li> Compilation errors
</li><li> Checkstyle (see <a href="Development_Guidelines.1.html#Checkstyle" title="">Checkstyle</a>)
</li><li> Tests: Run a local build with the <tt>build.xml</tt> to test all existing JUnit tests.
<dl><dd>(see <a href="Development_Guidelines/Howto_build_a_SMILA-Distribution.html" class="mw-redirect" title="SMILA/Development Guidelines/Howto build a SMILA-Distribution">How to build a SMILA distribution</a> for the setup)
</dd><dd>Be aware that running tests in Eclipse doesn't mean that they run with the pdebbuild.
</dd></dl>
</li><li> Build process: Check if your bundles and your test bundle is fully integrated in the whole build process
<dl><dd>(see <a href="Development_Guidelines/How_to_integrate_new_bundle_into_build_process.html" class="mw-redirect" title="SMILA/Development Guidelines/How to integrate new bundle into build process">How to integrate new bundle into build process</a> and <a href="Development_Guidelines/How_to_integrate_test_bundle_into_build_process.html" class="mw-redirect" title="SMILA/Development Guidelines/How to integrate test bundle into build process">How to integrate test bundle into build process</a>)
</dd></dl>
</li></ul>
<p>We have added a feature to the <tt>build.xml</tt>: The failed JUnit tests are reported at the end of the build output.
</p><p>Furthermore the full JUnit reports are generate under <tt>eclipse.build/reports/junit/</tt> and the
error messages from the JUnit reports are stored under <tt>eclipse.build/reports_errors_txt/</tt>.
</p><p>Everyone should monitor the trunk at the build server and if there is a "red" build everyone should look if he has committed the error.
</p><p>If the error could not be solved within the next build, the developer should inform the developer team that there is a problem with the build and that he is working on the solution.
</p>
<a name="File_header_.26_copyright_notice"></a><h3> <span class="mw-headline"> File header &amp; copyright notice </span></h3>
<p>For guidelines on file header and copyright notices see <a href="Project_Guidelines.html" title="SMILA/Project Guidelines">Project Guidelines</a>.
</p>
<a name="Eclipse_code_formatter_profile"></a><h3> <span class="mw-headline"> Eclipse code formatter profile </span></h3>
<p>The Eclipse code formatter file is available in trunk at <tt>SMILA.builder/eclipse-formatter/Eclipse-formatter-Brox-3.2-3.3.xml</tt>.
</p><p>You can also download the latest versions of Eclipse-formatter-Brox-3.2-3.3 and brox_checks here: <a href="http://wiki.eclipse.org/images/5/50/Brox-eclipse-files.zip" class="internal" title="Brox-eclipse-files.zip">Brox-Eclipse-Files</a>
</p><p>To import the Eclipse code formatter profile:
</p>
<ol><li> Download the profile configuration file.
</li><li> Select <i>Window &gt; Preferences</i> in Eclipse and switch to the <i>Java &gt; Code Style &gt; Formatter</i> preferences page.
</li><li> Click the <i>Import</i> button and select the downloaded formatter file.
</li></ol>
<div class="messagebox" style="background-color: #def3fe; border: 1px solid #c5d7e0; color: black; padding: 5px; margin: 1ex 0; min-height: 35px; padding-left: 45px;">
<div style="float: left; margin-left: -40px;"><a href="http://wiki.eclipse.org/Image:Note.png" class="image" title="Note.png"><img alt="" src="http://wiki.eclipse.org/images/c/cc/Note.png" width="35" height="35" border="0" /></a></div>
<div><b>formatter vs. save actions</b><br />most source files have been edited with the save action turned on: "remove trailing white spaces on all lines". If you dont have this set then formatting the whole file will result in a lot white space of changes, which is cumbersome as is clutters diffs and poses problems to patches. So plz turn this feature on.</div>
</div>
<a name="Checkstyle"></a><h3> <span class="mw-headline"> Checkstyle </span></h3>
<p>Each Eclipse project (bundles) should follow the SMILA Coding Conventions.
</p><p>We use different checkstyle rules for "normal" bundles and test bundles. So there are two files containing the Checkstyle configurations in the trunk that you have to import (see below).
</p><p><b>Eclipse checkstyle plugin</b>
</p><p>The eclipse-cs Checkstyle plugin integrates the source code analyzer Checkstyle into Eclipse IDE. By using this plugin your code is constantly inspected for problems. Within the Eclipse workbench you are notified of problems via the Eclipse <i>Problems</i> View and source code annotations just as you would see with compiler errors or warnings. The Checkstyle Eclipse plugin can be obtained from the update site: <a href="http://eclipse-cs.sourceforge.net/update/" class="external autonumber" title="http://eclipse-cs.sourceforge.net/update/" rel="nofollow">[1]</a>. Instructions about how to set up the Checkstyle plugin for your project can be obtained from <a href="http://eclipse-cs.sourceforge.net/basic_setup_project.html" class="external autonumber" title="http://eclipse-cs.sourceforge.net/basic_setup_project.html" rel="nofollow">[2]</a>.
</p><p><b>Setup checkstyle configuration</b>
</p>
<ol><li> Click <i>Window &gt; Preferences</i> in Eclipse.
</li><li> Select the <i>Checkstyle</i> preference page and click the <i>New</i> button.
</li><li> Select <i>External Configuration File</i> as <i>Type</i> and point to the location of the file
<dl><dd> <i>(if using checkstyle 4.x)</i> <tt>SMILA.Builder/checkstyle/smila_checkstyle.xml</tt>.
</dd><dd> <i>(if using checkstyle 5.x - recommended)</i> <tt>SMILA.Builder/checkstyle/smila_checkstyle-5.xml</tt>.
</dd></dl>
</li><li> This Checkstyle configuration profile should be named (while importing): <strong>"SMILA Checkstyle"</strong> and it should be set as <i>default</i>.
</li><li> Select <i>External Configuration File</i> as <i>Type</i> and point to the location of the file
<dl><dd> <i>(if using checkstyle 4.x)</i> <tt>SMILA.Builder/checkstyle/smila-test_checkstyle.xml</tt>.
</dd><dd> <i>(if using checkstyle 5.x - recommended)</i> <tt>SMILA.Builder/checkstyle/smila-test_checkstyle-5.xml</tt>.
</dd></dl>
</li><li> This Checkstyle configuration profile should be named (while importing): <strong>"SMILA Test Checkstyle"</strong>.
</li></ol>
<p><b>Warnings</b>
</p><p>Most checkstyle warnings will be self-explaining. But there are two metrics considering method complexity that should be pointed to here explicitly, in case you got appropriate warnings:
</p>
<dl><dd><ul><li> <a href="http://checkstyle.sourceforge.net/config_metrics.html" class="external text" title="http://checkstyle.sourceforge.net/config_metrics.html" rel="nofollow">CyclomaticComplexity</a>
</li><li> <a href="http://checkstyle.sourceforge.net/config_metrics.html" class="external text" title="http://checkstyle.sourceforge.net/config_metrics.html" rel="nofollow">NPathComplexity </a>
</li></ul>
</dd></dl>
<p><b>Reduce javadoc overhead</b>
</p><p>Instead of writing member variable comments as
</p>
<div dir="ltr" style="text-align: left;"><pre class="source-java"><span class="coMULTI">/**
* switch to true to add newlines for better readability, but poorer performance.
*/</span>
<span class="kw1">private</span> <span class="kw1">final</span> <span class="kw4">boolean</span> _printPretty;</pre></div>
<p>it's more readable and clearer to write such javadoc comments as one line:
</p>
<div dir="ltr" style="text-align: left;"><pre class="source-java"><span class="coMULTI">/** switch to true to add newlines for better readability, but poorer performance. */</span>
<span class="kw1">private</span> <span class="kw1">final</span> <span class="kw4">boolean</span> _printPretty;</pre></div>
<a name="Creation_of_bundles"></a><h3> <span class="mw-headline"> Creation of bundles </span></h3>
<p>For information on creating and integrating bundles refer to the following pages:
</p>
<ul><li> <a href="Development_Guidelines/Create_a_bundle_(plug-in).html" class="mw-redirect" title="SMILA/Development Guidelines/Create a bundle (plug-in)">Create a bundle (plug-in)</a>
</li><li> <a href="Development_Guidelines/How_to_integrate_new_bundle_into_build_process.html" class="mw-redirect" title="SMILA/Development Guidelines/How to integrate new bundle into build process">How to integrate a new bundle into the build process</a>
</li><li> <a href="Development_Guidelines/How_to_integrate_test_bundle_into_build_process.html" class="mw-redirect" title="SMILA/Development Guidelines/How to integrate test bundle into build process">How to integrate a test bundle into the build process</a>
</li><li> <a href="Development_Guidelines/3rd_party_bundle.html" class="mw-redirect" title="SMILA/Development Guidelines/3rd party bundle">How to add 3rd party bundle</a>
</li></ul>
<a name="Version_number"></a><h3> <span class="mw-headline"> Version number </span></h3>
<p>Until further notice all SMILA bundles have the version number 0.5.0.
</p>
<a name="XML_schemas.2C_namespace_convention.2C_and_versioning"></a><h3> <span class="mw-headline"> XML schemas, namespace convention, and versioning </span></h3>
<p>This subject is still very open to discussion right now, but I suggest to do the following:
</p>
<ol><li> when defining a schema a name space must be defined also
<ol><li> the URL of the namespace shall be like so: http://org.eclipse.eilf/&lt;rest of bundle as path&gt;/&lt;version&gt;##- &lt;rest of bundle as path&gt; means that the '.' are converted to '/'. In case the bundle defines more than one schema then use the either packages or other properly identifying names (plz discuss this) to further qualify the name space.
</li></ol>
</li></ol>
<ul><li> &lt;version&gt;
<dl><dd>As we continue to develop the application, schemas will change over time. there are basically two options here: either encode the version in the *:name space or have an extra well defined attribute that needs to be added to the XML messages to tell which schema version it conforms to. Doing *:this with an attribute seem to be much more error prone (likely to be forgotten) and less xml-natural. (subject needs further discussion).
</dd><dd>Further it is not clear how and when we will version a particular schema as those under development might be still very volatile. So the current *:idea is to version a schema on a milestone and releases.
</dd><dd>Another idea is to integrate versioning in the daily build process where the version number may be constructed from
</dd></dl>
<ul><li>Date / time stamp
</li><li>Build number
</li><li>Revision number
</li></ul>
</li></ul>
<p>Example: http://org.eclipse.eilf/processing/bpel/xml/Record/0.7
</p>
<a name="Naming_conventions_for_launch_files_.28.launch.29"></a><h3> <span class="mw-headline"> Naming conventions for launch files (.launch) </span></h3>
<p>It is a good thing to share your launches and many do so already which helps greatly to run tests quickly from within Eclipse. However, in order that at least I don't get confused, we need to define a naming scheme for the <tt>.launch</tt> files!
</p><p><b> Preliminary convention: </b> <tt>&lt;bundle name&gt;[_config name].launch</tt>
</p><p>The <tt>[config name]</tt> part is optional and needed when several <tt>.launch</tt> files exist for the same bundle but with different settings.
</p>
<a name="Generated_source_code_goes_into_code.2Fgen_source_folder_.28like_Jaxb.29"></a><h3> <span class="mw-headline"> Generated source code goes into code/gen source folder (like Jaxb) </span></h3>
<p>All generated source code (eg. JAXB) goes into the distinct source code folder code/gen.
Where possible all generated classes should also have their own package.
Reasons:
</p>
<ul><li> Separate generated source code from handwritten code
</li><li> Easier filtering for Checkstyle
</li></ul>
<p>(see <a href="Development_Guidelines/Setup_for_JAXB_code_generation.html" title="SMILA/Development Guidelines/Setup for JAXB code generation">Setup for JAXB code generation</a> and <a href="Development_Guidelines/How_to_implement_a_Crawler.html" class="mw-redirect" title="SMILA/Development Guidelines/How to implement a Crawler">How to implement a crawler</a> for details specific to creating crawler configurations.)
</p>
<a name="Sources_of_third_party_bundles"></a><h3> <span class="mw-headline"> Sources of third party bundles </span></h3>
<p>If you have to implement third party bundles into the SMILA project, please insert the sources into the <tt>3rdPartySources</tt> folder, not into the new bundle folder.
Each third party bundle should have an own folder suffixed by the corresponding version number, e.g. <tt>3rdPartySources\org.apache.tomcat-6.0.16\apache-tomcat-6.0.16-src.zip</tt>.
</p>
<a name="Logging_guidelines"></a><h3> <span class="mw-headline"> Logging guidelines </span></h3>
<p>In SMILA apache commons logging is used with log4j. The log4j.properties are located in SMILA.application. Here are some guidelines how and when logging should be used:
</p>
<ul><li> avoid static references to Log if possible
</li></ul>
<div dir="ltr" style="text-align: left;"><pre class="source-java"><span class="kw1">private</span> <span class="kw1">final</span> Log _log = LogFactory.<span class="me1">getLog</span><span class="br0">&#40;</span>MyClass.<span class="kw1">class</span><span class="br0">&#41;</span>;</pre></div>
<ul><li> always check log level before logging, e.g.
</li></ul>
<div dir="ltr" style="text-align: left;"><pre class="source-java"><span class="kw1">if</span> <span class="br0">&#40;</span>_log.<span class="me1">isErrorEnabled</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
_log.<span class="me1">error</span><span class="br0">&#40;</span><span class="st0">&quot;Your error message&quot;</span>, e<span class="br0">&#41;</span>;
<span class="br0">&#125;</span></pre></div>
<ul><li> do <b>not</b> log exceptions before throwing new exceptions, e.g.
</li></ul>
<div dir="ltr" style="text-align: left;"><pre class="source-java">...
<span class="kw1">if</span><span class="br0">&#40;</span> paramXY == <span class="kw2">null</span> <span class="br0">&#41;</span> <span class="br0">&#123;</span>
<span class="kw1">if</span> <span class="br0">&#40;</span>_log.<span class="me1">isErrorEnabled</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
_log.<span class="me1">error</span><span class="br0">&#40;</span><span class="st0">&quot;paramXY is not set&quot;</span><span class="br0">&#41;</span>;
<span class="br0">&#125;</span>
<span class="kw1">throw</span> <span class="kw1">new</span> <span class="kw3">NullPointerException</span><span class="br0">&#40;</span><span class="st0">&quot;paramXY is not set&quot;</span><span class="br0">&#41;</span>;
<span class="br0">&#125;</span></pre></div>
<p><b>Rationale:</b><br />
<a href="http://wiki.eclipse.org/User:T.menzel.brox.de" class="mw-redirect" title="User:T.menzel.brox.de">User:T.menzel.brox.de</a> <br />
I advise against this as it only causes the same message to be repeated at least twice, namely when the exception is created and then when the exception is logged itself.
IMO it is sufficient to have a verbose error msg and this then is reported along with the stack trace when the exception is logged.
if the exception is handled then this message is even confusing b/c u have ERROR log entry but wonder: what happened then?
if u deem the condition so extraordinary and dangerous we could log it as WARN, but since we don't log the eception here it should not be level ERROR.
</p><p>Even worse than this is sometimes the habit to log an exception before (re)throwing or wrapping it, which I have seen often (in general, not this project in particular).
this then has the effect that u have the same exception logged several times which makes the log very verbose and confusing. as u think u have lot of problems/exception when it fact it is only that one case.
</p><p><a href="http://wiki.eclipse.org/index.php?title=User:Svoigt.brox.de&amp;action=edit" class="new" title="User:Svoigt.brox.de">User:svoigt.brox.de</a> <br />
Log and throw makes only sense in a client-server architecture.
We have no clients except Jconsole and the JmxAgent, and these clients use JMX for the commmuncation,
thus Exceptions are not "forwarded".
</p><p>I think we should use the Rule:
Never log and throw.
Because the "process" that catches the exception is responsible for logging.
</p><p>see: <a href="http://dev.eclipse.org/mhonarc/lists/smila-dev/msg00249.html" class="external text" title="http://dev.eclipse.org/mhonarc/lists/smila-dev/msg00249.html" rel="nofollow">Mail thread</a>
</p>
<a name="When_to_use_what_log_level_and_what_information_to_provide.3F"></a><h4> <span class="mw-headline"> When to use what log level and what information to provide? </span></h4>
<table class="wikitable">
<tr>
<th> FATAL
</th><td> designates very severe error events that will presumably lead the application to abort.
</td></tr>
<tr>
<th> ERROR
</th><td> designates error events that might still allow the application to continue running.
</td></tr>
<tr>
<th> WARN
</th><td> designates potentially harmful situations.
</td></tr>
<tr>
<th> INFO
</th><td> for the "high level" information. For example - interesting runtime events (startup/shutdown).
</td></tr>
<tr>
<th> DEBUG
</th><td> only for the software developer interesting messages (detailed information on the flow through the system).
</td></tr>
</table>
<p>A good resource on how to use the levels in regard to the <i>Enterprise</i> context offers <a href="http://commons.apache.org/logging/guide.html#JCL%20Best%20Practices" class="external text" title="http://commons.apache.org/logging/guide.html#JCL%20Best%20Practices" rel="nofollow">JCL Best Practices</a>.
</p><p>Read here further about <a href="Specifications/UsefulLogMessages.html" class="external text" title="http://wiki.eclipse.org/SMILA/Specifications/UsefulLogMessages" rel="nofollow">Useful Log Messages</a> for Smila.
</p>
<a name="Used_technologies"></a><h2> <span class="mw-headline"> Used technologies </span></h2>
<a name="OSGi_related_information"></a><h3> <span class="mw-headline"> OSGi related information </span></h3>
<ul><li> <a href="Development_Guidelines/Declarative_Services.html" class="mw-redirect" title="SMILA/Development Guidelines/Declarative Services">Declarative services</a>
</li></ul>
<!--
NewPP limit report
Preprocessor node count: 102/1000000
Post-expand include size: 1582/2097152 bytes
Template argument size: 1052/2097152 bytes
#ifexist count: 0/100
-->
<!-- Saved in parser cache with key wikidb:pcache:idhash:15197-0!1!0!!en!2!edit=0 and timestamp 20120203101335 -->
<div class="printfooter">
Retrieved from "<a href="Development_Guidelines.1.html">http://wiki.eclipse.org/SMILA/Development_Guidelines</a>"</div>
<div id="catlinks"><p class='catlinks'><a href="http://wiki.eclipse.org/Special:Categories" title="Special:Categories">Category</a>: <span dir='ltr'><a href="http://wiki.eclipse.org/Category:SMILA" title="Category:SMILA">SMILA</a></span></p></div> <!-- end content -->
<div class="visualClear"></div>
</div>
</div>
</div>
<!-- Yoink of toolbox for phoenix moved up -->
</div>
</div>
<div id="clearFooter"/>
<div id="footer" >
<ul id="footernav">
<li class="first"><a href="http://www.eclipse.org/">Home</a></li>
<li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
<li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
<li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
<li><a href="http://www.eclipse.org/org/foundation/contact.php">Contact</a></li>
<li><a href="http://wiki.eclipse.org/Eclipsepedia:About" title="Eclipsepedia:About">About Eclipsepedia</a></li>
</ul>
<span id="copyright">Copyright &copy; 2012 The Eclipse Foundation. All Rights Reserved</span>
<p id="footercredit">This page was last modified 12:56, 24 January 2012 by <a href="http://wiki.eclipse.org/index.php?title=User:Juergen.schumacher.attensity.com&amp;action=edit" class="new" title="User:Juergen.schumacher.attensity.com">Juergen Schumacher</a>. Based on work by <a href="http://wiki.eclipse.org/User:Andreas.schank.attensity.com" title="User:Andreas.schank.attensity.com">A. Schank</a>, <a href="http://wiki.eclipse.org/User:Andreas.Weber.empolis.com" title="User:Andreas.Weber.empolis.com">Andreas Weber</a> and <a href="http://wiki.eclipse.org/User:Tmenzel.brox.de" title="User:Tmenzel.brox.de">thomas menzel</a> and <a href="http://wiki.eclipse.org/index.php?title=SMILA/Development_Guidelines&amp;action=credits" title="SMILA/Development Guidelines">others</a>.</p>
<p id="footerviews">This page has been accessed 7,677 times.</p>
</div>
<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">
var pageTracker = _gat._getTracker("UA-910670-4");
pageTracker._trackPageview();
</script>
<!-- <div class="visualClear"></div> -->
<script type="text/javascript">if (window.runOnloadHook) runOnloadHook();</script>
</div>
<!-- Served in 0.194 secs. --></body></html>