Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "SMILA/Development Guidelines"

(Official JVM)
(45 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 +
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).
 +
 +
== How-to manuals ==
 +
Find a list of How-To manuals at [[SMILA/HowTo|SMILA How-to manuals]].
 +
 
== Development requirements ==
 
== Development requirements ==
  
=== Official JVM ===
+
=== Official JVM ===
Official JVM for this project is Java5.
+
  
=== OSGi Runtime ===
+
The officially JVM needed for this project is > Java 1.6.0_04. (see [http://dev.eclipse.org/mhonarc/lists/smila-dev/msg00682.html Mail])
the OSGi impl. of Equinox of eclipse 3.3 or later and the corresponding OSGi Spec(s)
+
  
== Development conventions ==
+
=== OSGi runtime  ===
  
=== Project Setup ===
+
The OSGi implementation of Equinox of Eclipse 3.5 (Galileo) or later and the corresponding OSGi specification(s).
The project folder setup is defined for this project at
+
Currently SMILA is by default targeted to Eclipse 3.7.x.
[[SMILA/Development_Guidelines/Brox Java Project Setup|Brox Java Project Setup]]
+
 
  
 +
== Development conventions ==
  
=== Introduction to make.xml ===
+
=== Description of make.xml ===
see: [[SMILA/Development_Guidelines/Introduction to make.xml|Introduction to make.xml]]
+
For a description of the build file <tt>make.xml</tt> refer to [[SMILA/Development_Guidelines/Introduction to make.xml|Introduction to make.xml]].
  
=== Continuous Integration ===
+
=== Continuous integration ===
  
Everyone should be aware of the following workflow with bamboo.
+
Everyone should be aware of the following workflow with Bamboo:
  
Bamboo should improve the source code quality but it should not be used as a (junit)-test-server.
+
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:
 
Therefore each developer should check his code before committing it to subversion regarding:
* Compilation Errors
+
* Compilation errors
* Checkstyle (see Brox Coding Conventions)
+
* Checkstyle (see [[#Checkstyle|Checkstyle]])
* Tests: Run a local build with the build.xml to test all existing junit-tests.
+
* Tests: Run a local build with the <tt>build.xml</tt> to test all existing JUnit tests.
*:(see [[SMILA/Development_Guidelines|Development Guidelines]] for the setup)
+
*:(see [[SMILA/Development_Guidelines/Howto_build_a_SMILA-Distribution|How to build a SMILA distribution]] for the setup)
*:Be aware that running tests in eclipse doesn't mean that they run with the pdebbuild.
+
*:Be aware that running tests in Eclipse doesn't mean that they run with the pdebbuild.
* Build-Process: Check if your Bundles and your Test-Bundle is fully integrated in the whole Build-Process
+
* Build process: Check if your bundles and your test bundle is fully integrated in the whole build process
 
*:(see [[SMILA/Development_Guidelines/How to integrate new bundle into build process|How to integrate new bundle into build process]] and [[SMILA/Development_Guidelines/How to integrate test bundle into build process|How to integrate test bundle into build process]])
 
*:(see [[SMILA/Development_Guidelines/How to integrate new bundle into build process|How to integrate new bundle into build process]] and [[SMILA/Development_Guidelines/How to integrate test bundle into build process|How to integrate test bundle into build process]])
  
We have added a feature to the build.xml: The failed junit-tests are reported at the end of the build output.
+
We have added a feature to the <tt>build.xml</tt>: The failed JUnit tests are reported at the end of the build output.
  
Furthermore the full junit-reports are generate under eclipse.build/reports/junit/ and the
+
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 eclipse.build/reports_errors_txt/.
+
error messages from the JUnit reports are stored under <tt>eclipse.build/reports_errors_txt/</tt>.
  
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.
+
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.
  
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.
+
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.
  
=== File Header & Copyright Notice ===
+
=== File header & copyright notice ===
see [[SMILA/Project Guidelines|Project Guidelines]]
+
For guidelines on file header and copyright notices see [[SMILA/Project Guidelines|Project Guidelines]].
  
 +
=== Eclipse code formatter profile ===
  
=== Eclipse code formatter profile. ===
+
The Eclipse code formatter file is available in trunk at <tt>SMILA.builder/eclipse-formatter/Eclipse-formatter-Brox-3.2-3.3.xml</tt>.
  
Eclipse code formatter file is available in trunk at EILF.builder/eclipse-formatter/Eclipse-formatter-Brox-3.2-3.3.xml
+
You can also download the latest versions of Eclipse-formatter-Brox-3.2-3.3 and brox_checks here: [[Media:Brox-eclipse-files.zip|Brox-Eclipse-Files]]
  
To import Eclipse code formatter profile, download profile configuration file, select Window > Preferences in Eclipse and select Java > Code Style > Formatter preference page.
+
To import the Eclipse code formatter profile:
Click on Import button and select formatter file.
+
# Download the profile configuration file.
 +
# Select ''Window > Preferences'' in Eclipse and switch to the ''Java > Code Style > Formatter'' preferences page.
 +
# Click the ''Import'' button and select the downloaded formatter file.
 +
 
 +
{{Note|formatter vs. save actions|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.}}
  
 
=== Checkstyle ===
 
=== Checkstyle ===
  
Each Eclipse project (Bundles) should follow the Brox Coding Conventions.
+
Each Eclipse project (bundles) should follow the SMILA Coding Conventions.  
  
File containing checkstyle rules is avaliable in trunk at EILF.builder/checkstyle/brox_checks.xml
+
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).
  
'''Eclipse checkstyle plugin.'''
+
'''Eclipse checkstyle plugin'''
  
The eclipse-cs Checkstyle plugin integrates the source code analyzer Checkstyle into Eclipse IDE.
+
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 ''Problems'' 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: [http://eclipse-cs.sourceforge.net/update/]. Instructions about how to set up the Checkstyle plugin for your project can be obtained from [http://eclipse-cs.sourceforge.net/basic_setup_project.html].  
With the Checkstyle Eclipse plugin your code is constantly inspected for problems. Within the Eclipse workbench you are notified of problems via the Eclipse Problems 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: http://eclipse-cs.sourceforge.net/update/
+
Instructions about how to set up the Checkstyle plugin for your project can be obtained from http://eclipse-cs.sourceforge.net/basic_setup_project.html
+
To use plugin for all projects, select Window > Preferences menu in Eclipse, select Checkstyle preference page and. Click on the New button, select External Configuration File as Type and point to the location of the file brox_checks.xml
+
  
Checkstyle Configuration Profile should be named (while importing): "Brox Coding Conventions 1.06"
+
'''Setup checkstyle configuration'''
  
The complete manual and other information about the plugin may be obtained from http://eclipse-cs.sourceforge.net/
+
# Click ''Window > Preferences'' in Eclipse.
 +
# Select the ''Checkstyle'' preference page and click the ''New'' button.
 +
# Select ''External Configuration File'' as ''Type'' and point to the location of the file
 +
#: ''(if using checkstyle 4.x)''  <tt>SMILA.Builder/checkstyle/smila_checkstyle.xml</tt>.
 +
#: ''(if using checkstyle 5.x - recommended)''  <tt>SMILA.Builder/checkstyle/smila_checkstyle-5.xml</tt>.
 +
# This Checkstyle configuration profile should be named (while importing): <strong>"SMILA Checkstyle"</strong> and it should be set as ''default''.
 +
# Select ''External Configuration File'' as ''Type'' and point to the location of the file
 +
#: ''(if using checkstyle 4.x)''  <tt>SMILA.Builder/checkstyle/smila-test_checkstyle.xml</tt>.
 +
#: ''(if using checkstyle 5.x - recommended)'' <tt>SMILA.Builder/checkstyle/smila-test_checkstyle-5.xml</tt>.
 +
# This Checkstyle configuration profile should be named (while importing): <strong>"SMILA Test Checkstyle"</strong>.
  
 +
'''Warnings'''
  
=== Creation of Bundles ===
+
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:
Description at [[SMILA/Development_Guidelines/Create a bundle (plug-in)|Create a bundle (plug-in)]]
+
:* [http://checkstyle.sourceforge.net/config_metrics.html  CyclomaticComplexity]
 +
:* [http://checkstyle.sourceforge.net/config_metrics.html  NPathComplexity ]
  
How to integrate new bundle into build process see: [[SMILA/Development_Guidelines/How to integrate new bundle into build process|How to integrate new bundle into build process]]
+
'''Reduce javadoc overhead'''
  
How to integrate test bundle into build process see: [[SMILA/Development_Guidelines/How to integrate test bundle into build process|How to integrate test bundle into build process]]
+
Instead of writing member variable comments as
 +
<source lang="java">
 +
/**
 +
* switch to true to add newlines for better readability, but poorer performance.
 +
*/
 +
private final boolean _printPretty;
 +
</source>
  
=== Version number ===
+
it's more readable and clearer to write such javadoc comments as one line:
until further notice all own created bundles are V0.5
+
<source lang="java">
 +
/** switch to true to add newlines for better readability, but poorer performance. */
 +
private final boolean _printPretty;
 +
</source>
  
 +
=== Creation of bundles ===
 +
For information on creating and integrating bundles refer to the following pages:
 +
 +
* [[SMILA/Development_Guidelines/Create a bundle (plug-in)|Create a bundle (plug-in)]]
 +
* [[SMILA/Development_Guidelines/How to integrate new bundle into build process|How to integrate a new bundle into the build process]]
 +
* [[SMILA/Development_Guidelines/How to integrate test bundle into build process|How to integrate a test bundle into the build process]]
 +
* [[SMILA/Development_Guidelines/3rd party bundle|How to add 3rd party bundle]]
 +
 +
=== Version number ===
 +
Until further notice all SMILA bundles have the version number 0.5.0.
  
=== XML Schemas, Namespace Convention and Versioning ===
+
=== XML schemas, namespace convention, and versioning ===
This subject is still very open to discussion right now, but i suggest to do the following:
+
This subject is still very open to discussion right now, but I suggest to do the following:
 
# when defining a schema a name space must be defined also
 
# when defining a schema a name space must be defined also
 
## the URL of the namespace shall be like so: <nowiki>http://org.eclipse.eilf/<rest of bundle as path>/<version>##- <rest of bundle as path></nowiki> 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.
 
## the URL of the namespace shall be like so: <nowiki>http://org.eclipse.eilf/<rest of bundle as path>/<version>##- <rest of bundle as path></nowiki> 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.
Line 89: Line 124:
 
*: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.
 
*: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.
 
*:Another idea is to integrate versioning in the daily build process where the version number may be constructed from
 
*:Another idea is to integrate versioning in the daily build process where the version number may be constructed from
**date / time stamp
+
**Date / time stamp
**build number
+
**Build number
**revision number
+
**Revision number
  
 
Example: <nowiki>http://org.eclipse.eilf/processing/bpel/xml/Record/0.7</nowiki>
 
Example: <nowiki>http://org.eclipse.eilf/processing/bpel/xml/Record/0.7</nowiki>
  
=== Launch Files Naming Convention (.launch) ===
+
=== Naming conventions for launch files (.launch) ===
  
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 .launches!
+
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!
  
''' Preliminary Convention: ''' <bundle name>[_config name].launch
+
''' Preliminary convention: ''' <tt><bundle name>[_config name].launch</tt>
  
The [config name] part is optional and needed when several .launches exist for the same bundle with diff. settings.
+
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.
  
=== Generated Source Code goes into code/gen source folder (like Jaxb) ===
+
=== Generated source code goes into code/gen source folder (like Jaxb) ===
  
All generated source code (eg. JAXB) goes into the distinct source code folder code/gen.
+
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.
 
Where possible all generated classes should also have their own package.
 
Reasons:
 
Reasons:
* separate generated source code from handwritten
+
* Separate generated source code from handwritten code
* easier filtering for checkstyle
+
* Easier filtering for Checkstyle
(see previous Description in [[SMILA/Documentation/How_to_implement_a_Crawler|How to implement a Crawler]])
+
(see [[SMILA/Development_Guidelines/Setup for JAXB code generation|Setup for JAXB code generation]] and [[SMILA/Development_Guidelines/How_to_implement_a_Crawler|How to implement a crawler]] for details specific to creating crawler configurations.)
  
 
=== Sources of third party bundles ===
 
=== Sources of third party bundles ===
  
If you have to implement third party bundles into the smila project, please insert the sources into the "3rdPartySources"-folder, not into the new bundle folder.  
+
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, that is extended with versionnumber, e.g. 3rdPartySources\org.apache.tomcat-6.0.16\apache-tomcat-6.0.16-src.zip
+
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>.
  
== Used Technologies ==
+
=== Logging guidelines ===
  
=== OSGi related information ===
+
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:
 +
* avoid static references to Log if possible
 +
<source lang="Java">
 +
private final Log _log = LogFactory.getLog(MyClass.class);
 +
</source>
 +
* always check log level before logging, e.g.
 +
<source lang="Java">
 +
if (_log.isErrorEnabled()) {
 +
    _log.error("Your error message", e);
 +
}
 +
</source>
  
* [[SMILA/Development Guidelines/Declarative Services|Declarative Services]]
+
* do '''not''' log exceptions before throwing new exceptions, e.g.
 +
<source lang="Java">
 +
...
 +
if( paramXY == null ) {
 +
    if (_log.isErrorEnabled()) {
 +
        _log.error("paramXY is not set");
 +
    }
 +
    throw new NullPointerException("paramXY is not set");
 +
}
 +
</source>
  
=== Tuscany related information ===
+
'''Rationale:'''<br>
* [[SMILA/Development Guidelines/Tuscany Integration|Tuscany Integration]]
+
[[User:T.menzel.brox.de]] <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.
  
=== Launch configurations for OSGi wih SCA ===
+
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 information is outdated. It will be updated when Tuscany integration is stable'''
+
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.
[[User:Daniel.stucky.empolis.com|Daniel Stucky]]: I had some trouble selecting the right Bundles that were required to execute my sample application (org.eclipse.eilf.framework.test). Don't use the "Add required Bundles" button in the launch configuration dialog. It adds additional bundles that are not needed and starts all bundles with the same start level. I selected the required bundles manually (through try and error) and assigned the following start levels:
+
# all org.eclipse bundles (except for the eilf bundles)
+
# all org.apache.tuscany bundles
+
# all other third party bundles
+
# (default) all org.eclipse.eilf bundles
+
# the bundle with the test application (org.eclipse.eilf.framework.test)
+
  
I don't know if all these start levels are required, at least I got it working with these settings. Setting all to default does NOT work !!!
+
[[User:svoigt.brox.de]] <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".
  
 +
I think we should use the Rule:
 +
Never log and throw.
 +
Because the "process" that catches the exception is responsible for logging.
  
 +
see: [http://dev.eclipse.org/mhonarc/lists/smila-dev/msg00249.html Mail thread]
  
== How To ==
+
==== When to use what log level and what information to provide? ====
=== set up dev environment ===
+
{| class="wikitable"
see [[SMILA/Development Guidelines/Howto set up dev environment|Howto set up dev environment]]
+
|-
 +
! FATAL
 +
| designates very severe error events that will presumably lead the application to abort.
 +
|-
 +
! ERROR
 +
| designates error events that might still allow the application to continue running.
 +
|-
 +
! WARN
 +
| designates potentially harmful situations.
 +
|-
 +
! INFO
 +
| for the "high level" information. For example - interesting runtime events (startup/shutdown).
 +
|-
 +
! DEBUG
 +
| only for the software developer interesting messages (detailed information on the flow through the system).
 +
|-
 +
|}
  
=== set up test environment ===
+
A good resource on how to use the levels in regard to the ''Enterprise'' context offers [http://commons.apache.org/logging/guide.html#JCL%20Best%20Practices JCL Best Practices].
see [[SMILA/Development Guidelines/Howto set up test environment|Howto set up test environment]]
+
 
 +
Read here further about [http://wiki.eclipse.org/SMILA/Specifications/UsefulLogMessages Useful Log Messages] for Smila.
 +
 
 +
== Used technologies ==
 +
 
 +
=== OSGi related information ===
  
=== run/manage connectivity framework ===
+
* [[SMILA/Development Guidelines/Declarative Services|Declarative services]]
From this moment there is an ability to start EILF/SMILA as separate application:
+
# Update from SVN and refresh
+
# execute build and unzip eclipse.build/Application/ EILF-win32.win32.x86.zip to any folder
+
# Create folder "c:\data" and place some txt/htm files (for filesystem crawler)
+
# launch application by eclipse.exe -console or launch.cmd
+
# Run jconsole, and connect to local
+
# Open EILF/org.eclipse.econnectivity... branch in the jconsole
+
# Open MBeans/Operations tab
+
# Start FileSystem crawler by "startCrawl()" operation with passing "file" parameter
+
# Start Web crawler by "startCrawl()" operation with passing "web" parameter.
+
# Look at the Eclipse console log and enjoy ;)
+
  
 
[[Category:SMILA]]
 
[[Category:SMILA]]

Revision as of 08:56, 24 January 2012

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).

How-to manuals

Find a list of How-To manuals at SMILA How-to manuals.

Development requirements

Official JVM

The officially JVM needed for this project is > Java 1.6.0_04. (see Mail)

OSGi runtime

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.  

Development conventions

Description of make.xml

For a description of the build file make.xml refer to Introduction to make.xml.

Continuous integration

Everyone should be aware of the following workflow with Bamboo:

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:

We have added a feature to the build.xml: The failed JUnit tests are reported at the end of the build output.

Furthermore the full JUnit reports are generate under eclipse.build/reports/junit/ and the error messages from the JUnit reports are stored under eclipse.build/reports_errors_txt/.

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.

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.

File header & copyright notice

For guidelines on file header and copyright notices see Project Guidelines.

Eclipse code formatter profile

The Eclipse code formatter file is available in trunk at SMILA.builder/eclipse-formatter/Eclipse-formatter-Brox-3.2-3.3.xml.

You can also download the latest versions of Eclipse-formatter-Brox-3.2-3.3 and brox_checks here: Brox-Eclipse-Files

To import the Eclipse code formatter profile:

  1. Download the profile configuration file.
  2. Select Window > Preferences in Eclipse and switch to the Java > Code Style > Formatter preferences page.
  3. Click the Import button and select the downloaded formatter file.
Note.png
formatter vs. save actions
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.


Checkstyle

Each Eclipse project (bundles) should follow the SMILA Coding Conventions.

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).

Eclipse checkstyle plugin

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 Problems 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: [1]. Instructions about how to set up the Checkstyle plugin for your project can be obtained from [2].

Setup checkstyle configuration

  1. Click Window > Preferences in Eclipse.
  2. Select the Checkstyle preference page and click the New button.
  3. Select External Configuration File as Type and point to the location of the file
    (if using checkstyle 4.x) SMILA.Builder/checkstyle/smila_checkstyle.xml.
    (if using checkstyle 5.x - recommended) SMILA.Builder/checkstyle/smila_checkstyle-5.xml.
  4. This Checkstyle configuration profile should be named (while importing): "SMILA Checkstyle" and it should be set as default.
  5. Select External Configuration File as Type and point to the location of the file
    (if using checkstyle 4.x) SMILA.Builder/checkstyle/smila-test_checkstyle.xml.
    (if using checkstyle 5.x - recommended) SMILA.Builder/checkstyle/smila-test_checkstyle-5.xml.
  6. This Checkstyle configuration profile should be named (while importing): "SMILA Test Checkstyle".

Warnings

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:

Reduce javadoc overhead

Instead of writing member variable comments as

 /** 
 * switch to true to add newlines for better readability, but poorer performance. 
 */
 private final boolean _printPretty;

it's more readable and clearer to write such javadoc comments as one line:

 /** switch to true to add newlines for better readability, but poorer performance. */
 private final boolean _printPretty;

Creation of bundles

For information on creating and integrating bundles refer to the following pages:

Version number

Until further notice all SMILA bundles have the version number 0.5.0.

XML schemas, namespace convention, and versioning

This subject is still very open to discussion right now, but I suggest to do the following:

  1. when defining a schema a name space must be defined also
    1. the URL of the namespace shall be like so: http://org.eclipse.eilf/<rest of bundle as path>/<version>##- <rest of bundle as path> 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.
  • <version>
    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).
    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.
    Another idea is to integrate versioning in the daily build process where the version number may be constructed from
    • Date / time stamp
    • Build number
    • Revision number

Example: http://org.eclipse.eilf/processing/bpel/xml/Record/0.7

Naming conventions for launch files (.launch)

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 .launch files!

Preliminary convention: <bundle name>[_config name].launch

The [config name] part is optional and needed when several .launch files exist for the same bundle but with different settings.

Generated source code goes into code/gen source folder (like Jaxb)

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:

  • Separate generated source code from handwritten code
  • Easier filtering for Checkstyle

(see Setup for JAXB code generation and How to implement a crawler for details specific to creating crawler configurations.)

Sources of third party bundles

If you have to implement third party bundles into the SMILA project, please insert the sources into the 3rdPartySources folder, not into the new bundle folder. Each third party bundle should have an own folder suffixed by the corresponding version number, e.g. 3rdPartySources\org.apache.tomcat-6.0.16\apache-tomcat-6.0.16-src.zip.

Logging guidelines

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:

  • avoid static references to Log if possible
private final Log _log = LogFactory.getLog(MyClass.class);
  • always check log level before logging, e.g.
if (_log.isErrorEnabled()) {
    _log.error("Your error message", e);
}
  • do not log exceptions before throwing new exceptions, e.g.
...
if( paramXY == null ) {
    if (_log.isErrorEnabled()) {
        _log.error("paramXY is not set");
    }
    throw new NullPointerException("paramXY is not set");
}

Rationale:
User:T.menzel.brox.de
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.

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.

User:svoigt.brox.de
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".

I think we should use the Rule: Never log and throw. Because the "process" that catches the exception is responsible for logging.

see: Mail thread

When to use what log level and what information to provide?

FATAL designates very severe error events that will presumably lead the application to abort.
ERROR designates error events that might still allow the application to continue running.
WARN designates potentially harmful situations.
INFO for the "high level" information. For example - interesting runtime events (startup/shutdown).
DEBUG only for the software developer interesting messages (detailed information on the flow through the system).

A good resource on how to use the levels in regard to the Enterprise context offers JCL Best Practices.

Read here further about Useful Log Messages for Smila.

Used technologies

OSGi related information

Copyright © Eclipse Foundation, Inc. All Rights Reserved.