What to do when ANT SCP task hangs unexpectedly & automating Javadoc

I had this issue with a project earlier within an ANT build script I have for Team Concert. In this project I generate JavaDoc with the ANT task <javadoc> and then I use <scp> to move the generated HTML, CSS, and other artifacts over to the target documentation server.

The scp task is a secure copy task. This is a unix/linux function that can copy files to/from hosts over secure shell (SSH). To use this function, you have to pull down another library, the Java Secure Channel (jsch), and place this in the ANT_HOME/lib directory.
If you are running this on Team Concert build engine, the directory is under JAZZHOME/buildsystem/buildengine/eclipse/plugins/org.apache.ant_1.7.0

This particular issue manifests itself  in that the build engine will never finish the build. It simply appears to 'hang'. The problem is with the combination of ANT 1.7 and Jsch 1.3 and above. RTC 2.0.x uses ANT 1.7. I had downloaded the latest release of Jsch. After hours of troubleshooting, I was searching and discovered this little gem on the internet. It appears that Jsch requires a buffer flush, which ANT 1.7 and below never sends.

Pulling down and replacing with  Jsch-0.1.29.jar solved the problem. Now, as part of our automated build, we put Javadoc on a central server with every build and are putting as much of our real  system documentation in the source code as we can. This makes for truly up to the second, accurate documentation. On some days that documentation may change and be updated a couple of dozen times, but it always matches what is on our integration servers.

Labels: , ,