Search This Blog

Wednesday, October 27, 2010

JavaDoc CVS Tag Replacements ($Id:, $Revision:, $Date:, $Author:)

Usage of CVS Keywords in JavaDocs

In my Java code I use the following tag in all my class level JavaDocs:

   * Some text describing what this class is for...bla bla bla...
   * @author: mkopka - Marty Kopka - 20101010 - 17:45:23pm
   * @version $Id: $ 
  public class Fubar {   ... snip .. class definition follows in here

...and then when I commit the code into CVS the $Id: $ tag gets converted into:

    * @version $Id:,v 1.1 2010/10/10 17:50:44 mkopka Exp $

Which is all well and good and Ive encouraged all my teams to follow this style as it gets you some bonus information for free basically. You dont need to do anything except put in the initial "Id" tag and then dont touch it from that point on. I'll get updated every commit from that point on and you get the name of the user committing the file, the time and date that they did so and the version in CVS of the current file commit. All good information to have, especially given that you dont have to update it yourself.

So what am I going to complain about...well nothing actually. I was just going to point out that the string that's substituted into the "Id" tag is actually made of of a number of small parts comprising the larger string. Should you not want all that information (although why you wouldn't I dont know)...but if you dont you can just pick and choose the bits that are good for you. As an example the code below shows the equivalence of the "Id" tag but made up of sub-component like tags.

    * @version $Revision: $ $Date: $ $Author: $ $State: $

Which will then give: 
    * @version $Revision: $ $Date: 2010/10/10 17:50:44 $ $Author: mkopka $ $State: Exp $

There's also no reason why theory... you couldn't use these various substitutions inside your code itself (although it would take until a CVS commit before you got any info in it first time around. But I can see a case where a version number for example may be usefully stored in a String and later displayed in the application. Or, seeing as how there is also the possibility to use other tags to substitute in a branch name (amongst other info) you could use that along with version info to provide info to the client. I.e.: something like this I can see as a a possibility:

    String versionAndBranch = "Branch: $: $ Version: $Revision: $";
    ... snip ... and then at some later date we can use the String above for logging, debugging, display to the client etc.
    System.out.println("We are using source code from: " + versionAndBranch);

Now as mentioned, the example above would be empty until you committed the file, but that's not a great problem as normally you would commit the code prior to a production deploy (so the issue would only be in your local development environment). For further info on this I found the following link:

Listing of CVS Keywords

Besides the substitution tags that I listed above there are a number of others that are also available (11 in fact ... or perhaps 12 if you include CVSHeaders from the latest version ... but not all versions have CVSHeaders so be aware of this prior to using it as your version of CVS may not support it). The following listing gives a list of all of the different substitutions available (which I pilfered from an number of different sites and cobbled the info below together. See the end for a listing of http://'s that I used to compile this).

Keyword Explanation
$Author: $The user responsible for a change. $Author: markd $
$Date: $Date and time of the change, in GMT. $Date: 1999/12/23 21:59:22 $
$Header: $A collection of information: full path to the RCS file, revision number, date/time of last change (GMT), author, state, and locker. (lockers are a rare occurance in CVS)

$Header: /cvsweb/cvs-guide/keyword.html,v 1.3 1999/12/23 21:59:22 markd Exp $
$Id: $Like $Header: $, but without the path to the RCS file. $Id: keyword.html,v 1.3 1999/12/23 21:59:22 markd Exp $
$Log: $
Inserts the cvs log message. This behaves differently than other tags in that it just inserts new information after the keyword. It doesn't replace the keyword or modify existing text.

$Log: keyword.html,v $
Revision 1.3 1999/12/23 21:59:22 markd
dummy change to bump up revision.

Revision 1.2 1999/12/23 21:59:15 markd
dummy change to bump up revision.

Revision 1.1 1999/12/23 21:58:35 markd
initial revision

Note: See the following link for an explanation of possible issues with the use of the $Log: $ tag.
$Locker: $The user who has a lock on this revision (usually nobody) $Locker: markd $
$Name: $If a sticky tag is in effect, this is the name of that tag. Otherwise blank. $Name: guide_release_1 $
$RCSfile: $Name of the RCS file in the repository $RCSfile: keyword.html,v $
$Revision: $Revision number $Revision: 1.3 $
$Source: $Full path to the RCS ",v" file in the repository $Source: /cvsweb/cvs-guide/keyword.html,v $
$State: $State of this revision. $State: Exp $
$CVSHeader: $
A standard header (similar to $Header: $, but with the CVS root stripped off). It contains the relative pathname of the RCS file to the CVS root, the revision number, the date (UTC), the author, the state, and the locker (if locked). Files will normally never be locked when you use CVS.

Note: This keyword has only been recently introduced to CVS and may cause problems with existing installations if $CVSHeader: $ is already in the files for a different purpose. This keyword may be excluded using the KeywordExpand=eCVSHeader in the `CVSROOT/config' file. See Configuring Keyword Expansion for more details.

Bibliography / List of Further Info Links

Monday, October 4, 2010

New Software Release - Firefox-4.0Beta4/5 & 6 + Glassfish 3+ Timeline

Just a quick update to discuss Firefox Beta Releases 4 to 6 (current as at 20101004) and an update of the Glassfish Server Time line for Releases.

Firefox 4 Beta 4, 5, & 6

I had a previous post linked here that discusses previous Firefox Betea's. Since that time Beta 4, 5 and 6 have been released.  The links below provide info on Time Lines, Features and Bug Lists for the Beta's.

Glassfish Time Lines

 The following link provided me with the information about the next set of Glassfish 3 up to v4 releases. The v3.2 and v4.0 releases have Java EE 7 functionality in them and that is primarily what Ill be looking forward to. The v3.0.1 release has come out at this stage (i.e.: 20101004) already and Im using it and this provided some of the initial bug fixes that come from a new major release version (i.e. when they went from v2.x to v3.0 that x.0 release always has a bunch of bugs and the first 100 day patch release is where the stability IMHO comes in...although GFv3.0 was not really that bad and only had a few minor issues).

Glassfish 3.0.1 - 2010 - Glassfish 100 Day Releases (i.e.: v3.0.x implies v3.0.1)
  • Branding, Patches
  • Multi-Lingual release
  • Adds Value-Added Features To Oracle GlassFish Server
  • Base Interop w/ Oracle Middle ware Products

Glassfish 3.1 - 2010
  • Centralized Administration / Clusters
  • High Availability / State Replication
  • Value Added Features, Like Coherence Support

Glassfish 3.2 - 2011
  • Improved Cluster/HA Administration
  • Better Integration w/ Oracle Identity Management
  • Virtualisation Support
  • Some Java EE 6 Specification Updates, Some Java EE 7 EA

Glassfish 4 - 2012
  • Common Server Platform - Shared Best Of Breed With Weblogic
  • Java EE 7

Friday, October 1, 2010

javac -Xlint And Its Many Friends

-Xlint and its variations - so many to choose from! 1st -Xlint:unchecked

Or should I just use them all? Pick and choose? Just the one I'm interested in? What to do? What to do?  Like many I came across Xlint(*1) when hitting the following message in one of my Ant builds a while back:

[javac] Note: Some input files use unchecked or unsafe operations.
[javac] Note: Recompile with -Xlint:unchecked for details.  

Huh....I thought to myself....there shouldnt be any errors with my last change. Well looking closer this is just a warning not Ant reporting on a compilation failure.OK. But why does it appear. There doesn't seem to be any location information reporting to me what causes it like a good 'ole stack trace does.  So like countless others I looked up how to use this -Xlint:unchecked thingy and stuck it into my Ant build and re-ran my ant script build.xml......and was promptly swamped by 100's of lines of warning messages (all pretty much saying the same thing) complaining about my absolute poor lack of etiquette in the use (or lack thereof) of generics throughout my (what I thought up until then was) pristine code.  Turns out it wasn't and I was seriously thinking of taking the pesky compile option out since its 'only a warning anyways' and hence thereby effectively getting rid of all that nasty mess and clutter in my build output. 

Now, okay....I didn't go down that path of just sweeping things back under the rug when they happen to fall out ... and furthermore these days things aren't quite that bad and when I write new code generics are used properly and by default as required throughout the code so this really is more of an issue when converting legacy code or upgrading from Java 1.4 to 5/6+ etc. When I do come across these issues I promptly modify the code to resolve them, thereby not only removing a pesky warning from my pristine build output, clearing up my Netbeans GUI of warnings and .... well .... also as a tiny little almost insignificant side note ..... making the code more robust and providing a higher-level of compile time type safety checking (which is really what generics are all about aren't they!!).

-Xlint, naked without its ':unchecked' param!

So now you know all about -Xlint:unchecked for type-checking issues related to generics. It is however possible to simply use just:


....without the :unchecked option. A little naked the poor tool feels now. This effectively says to the compiler use the lint tool (via the -X property) and just call it without any parameters. This has the effect of calling lint and using all of its checks rather than, like in our case above for :unchecked, using just the generic checks/warnings (by passing through the 'unchecked' parameter to the lint tool.

-Xlint and all of :unchecked's many, many friends!

So then, what checks are possible? When calling -Xlint what is it that we are actually doing (besides popping up a huuuuuge amount of warnings in most cases).  Well, calling -Xlint is effectively the same as passing in several parameters to the lint tool. What are these parameters....well Ive listed them below as to what it is that you can add to the -Xlint call as arguments to determine what checks the javac compiler should make when compiling the code and what warnings it should then report back on.


Thats a lot of options. Here is some info about them from the javac compiler options page:

Enable all recommended warnings. In this release, all available warnings are recommended.
Disable all warnings not mandated by the Java Language Specification.
Disable warning name, where name is one of the warning names supported for -Xlint:name, below.
Give more detail for unchecked conversion warnings that are mandated by the Java Language Specification.
Warn about nonexistent path (classpath, sourcepath, etc) directories.
Warn about missing serialVersionUID definitions on serializable classes.
Warn about finally clauses that cannot complete normally.
Check switch blocks for fall-through cases and provide a warning message for any that are found. Fall-through cases are cases in a switch block, other than the last case in the block, whose code does not include a break statement, allowing code execution to "fall through" from that case to the next case. For example, the code following the case 1 label in this switch block does not end with a break statement:
switch (x) {
case 1:
       //  No  break;  statement here.
case 2:
If the -Xlint:fallthrough flag were used when compiling this code, the compiler would emit a warning about "possible fall-through into case," along with the line number of the case in question.

-Xlint:{all,cast,deprecation,divzero,empty,unchecked,fallthrough,path,serial,finally,overrides}-cast,-deprecation,-divzero,-empty,-unchecked,-fallthrough,-path,-serial,-finally,-overrides,none}Enable or disable specific warnings


*1 - Well not see thinking back....Ill admit that lint I remember vaguely from my C Programming days back at university (in the dawn of the age in the mists of time back somewhere during the time period range in 1995 - 1999/2000).

Ubuntu / Kubuntu 10.04 (LTS ) Arrived in the Mail...snail mail that is!

Yeehaa I Got Mail...Its Not Spam....its....its...real...woooo...SNAIL MAIL!

Walked out to the letter box on the way to catching the bus to work this morning and found a padded envelope inside. My heart skipped a beat and surged with excitement..... Whatever could this be....had to be some cool free stuff...either more free cat food for my new kitten (I dont have a new kitten but taking advantage of the cat food tho for Bullets my 4 year old kitty) or perhaps another tube of free toothpaste ( does actually pull through and provide some actual 'free' things as their name suggests they should do...even tho 3/4 of their offers are actually competitions, surveys or other non-free stuff).

No....turns out this padded envelope from the mysterious corners of the world (I forget right now where it was from but it was far ....other hemisphere far even....) was actually my long awaited version of 3 DVD's with Lucid Lynx, 10.04 (LTS) Ubuntu/Kubuntu/Ubuntu - server/64bit - version. Its finally arrived!!! W00t!!!

Just in time for me to go to the Ubuntu website and read all about the 10.10 beta release that's about to come out (or just has :-) ) . Well I suppose that's what I get for not just downloading it and wanting it snail mail delivered in today's times....but you gotta admit....there's something just so exciting at getting 'real' mail in a padded envelope no less. Whats you say....not excited you say....pah..."bah Humbug" I say to you!!!! I enjoyed it!!! So there!!!

Well now all I have to do is get around to actually installing it (or at the very least running of the CD/DVD and trying it out). Dual boot would be nice, VMWare images with each of Ubuntu 8.xx, 9.yy, 10.zz versions installed inside my Windows 7 would be great and vice-versa with Windows 7 installed inside a VMWare image in my dual boot setup of Ubuntu 10.04. (It is LTS - Long Term Support-ed after all ... that was sarcasm by the way ... hard to tell on these blog things :-) )

Links to Ubuntu Downloads/Releases/Feature Info/Reviews.