# SBLIM CIM Client for Java Development Guidelines

## Contact

If you have any questions about the SBLIM CIM Client for Java you may contact the development team lead at blaschke@us.ibm.com.

## Releases

Planned releases appear in the middle of the last month of every quarter (middle of March, June, September and December). It might occur that we publish a release out of schedule on request of one of our exploiters as well.
A release is a code level that has been intensively tested and is supported. Releases are the only origins for maintenance branches.

## CVS

The sources can be found at "sblim.cvs.sourceforge.net/cvsroot/sblim/jsr48-client". Refer to SourceForge regarding CVS access rules and permissions.

All patches are committed to the "Experimental" branch first. The code in this branch is the most active, but it hasn't undergone a community review and is therefore unapproved.
Once a patch has been approved in the community review it will be merged into the "HEAD" branch. When a new release is published it represents the content of the "HEAD" branch at the release date. Of course, all releases have a corresponding version tag in CVS.

## Bug Tracker

The Bug Tracker process step are as follows

1. Somebody (a.k.a. the bug owner) files a bug in Bug Tracker.
2. A developer reads the problem description and assigns the bug.
3. A developer either accepts the bug (resolution->Accepted)
   - Proceed with step 4
   or denies it (resolution-> Duplicate, Invalid, Rejected, Wont Fix or Works For Me).
   - A reasonable justification will be posted to the comments. Once the bug owner agrees we proceed with step 8.
4. A developer creates a patch. The patch will be attached to Bug Tracker and committed into the Experimental branch (resolution->Fixed).
5. The community review is initiated. A corresponding comment is added to Bug Tracker.
6. The community review is completed and successful. A corresponding comment is added to Bug Tracker and the patch is merged into the HEAD branch. The bug status is changed to Pending. If the community review was unsuccessful we go back to step 4.
7. The patch is picked up by the next release.
8. The bug is closed (status->Closed).

## Patches

Patches are created relative to the latest release. We usually use the "create patch" action from Eclipse.

## Code Conventions

### File Encoding

The workspace default encoding should be set to "UTF-8" on all platforms. For *.properties-files we keep the Eclipse default of "ISO-8859-1".

### File Headers

Each source file contains a file header stating copyright, authorship and change history. For Java sources the header looks like this:

    /**
     * (C) Copyright IBM Corp. 2006, 2010
     *
     * THIS FILE IS PROVIDED UNDER THE TERMS OF THE ECLIPSE PUBLIC LICENSE
     * ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS FILE
     * CONSTITUTES RECIPIENTS ACCEPTANCE OF THE AGREEMENT.
     *
     * You can obtain a current copy of the Eclipse Public License from
     * http://www.opensource.org/licenses/eclipse-1.0.php
     *
     * @author : Alexander Wolf-Reber, IBM, a.wolf-reber@de.ibm.com
     *
     * Change History
     * Flag       Date        Prog         Description
     * -------------------------------------------------------------------------------
     * 1565892    2006-09-27  lupusalex    Make SBLIM client JSR48 compliant
     */

In .xml & .html files the header looks like this:

    <!--
     * (C) Copyright IBM Corp. 2006, 2010
     *
     * THIS FILE IS PROVIDED UNDER THE TERMS OF THE ECLIPSE PUBLIC LICENSE
     * ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS FILE
     * CONSTITUTES RECIPIENTS ACCEPTANCE OF THE AGREEMENT.
     *
     * You can obtain a current copy of the Eclipse Public License from
     * http://www.opensource.org/licenses/eclipse-1.0.php
     *
     * @author : Alexander Wolf-Reber, IBM, a.wolf-reber@de.ibm.com
     *
     * Change History
     * Flag       Date        Prog         Description
     * -------------------------------------------------------------------------------
     * 1565892    2006-09-27  lupusalex    Make SBLIM client JSR48 compliant
    -->

Insert your name and IBM email after the "@author" tag and replace "Date" and "Prog" with todays date and your CVS account name. We use bug 1565892 for the initial development of the JSR48 client.

### Formatting

The code is formatted using the Eclipse code formatter. Use the formatter settings stored in the "EclipseJavaCodeFormatter.xml". All code should be formatted before committing to CVS.

### Naming Conventions

We use the following naming conventions in our code (not all sources have been migrated to these conventions yet):

entity | naming | sample
--- | --- | ---
class, interface | mixed-case, first letter uppercase | class HttpClient
method | mixed-case, first letter lowercase | HttpClient getClient()
parameter | mixed-case, prefix 'p' | void setClient(HttpClient pClient)
local variable | mixed-case, first letter lowercase | int loopCounter
field | mixed-case, prefix 'i' | String iName
static field | mixed-case, prefix 'c' | static String cName
static final field | uppercase | static final String NAME = "SBLIM"

Access to members is not qualified with "this." the prefixing usually does a good job avoiding hidden members.

### Javadoc

Javadoc is mandatory for all public APIs of a class. This includes the class comment, methods comments and public member comments. It's mandatory as well for packages. See existing "package.html" files as example for package level javadoc.

### Miscellaneous

We aim at warning-free code. The project settings in CVS include a high warning level, do not mangle with them. All warnings have to be resolved, including unused imports or missing javadoc before any code is committed. There are a few warnings that can be ignored for good reason, e.g. a precautionary throws declaration where the declared exception is not actually thrown by the current implementation. But the cases are rare.

All code is REQUIRED to compile on IBM/SUN Java 1.5.x/1.6.x. Therefore Java 1.6 constructs are not allowed.

Use of default or protected visibility is discouraged. Fields should be private, provide getters and setters for public or subclass access. External and internal classes/interfaces should be clearly separated by using "*.internal" packages.

The public content of the javax.* classes is defined by JSR48. It is prohibited by license terms to add, change or omit any visible (public or protected) entities (classes, interfaces, fields, methods, parameters).