Lessons learned webservices project

At a recent project we used the following tools & frameworks:

• Java 6


• Spring 3.0


• Hibernate 3.2.7


• JMS


• JBoss ESB 4.5/5.1


• SOAP 1.1


• JAXB


• JAX-WS


• Apache CXF


• Maven2


• Jetty 6.1


• Oracle 10g


• Eclipse Mylyn


• SVN


• JUnit


• Bamboo


• Jira


• Crucible


• Nexus

Below are a couple of lessons learned which I remembered to write down:

JUnit

• To skip a testclass (e.g Util.java) during a test in a maven project: put @Ignore above it.

Java

• Throw checked exceptions in case of functionality errors. To not have to return those errors as return-values of the methods and making them checked, makes the interface clearer.

SOAP

• Should you use the service response for functional errors, and SOAP fault only for technical errors?
  Nothing in the SOAP 1.1 spec says you should do that or are not allowed to put functional errors in the <detail>.
  Makes sense to me to do that: otherwise you can get errors in the response AND in the soap fault. More complex to handle in the client...
  Less of an issue if you say when there are SOAP faults we just give up, only if there's a response we try to see what's going on.
  


• Apparent best practice: no underscores in xml/xsd/wsdl for element nor attributes, for better readability

ESB

• JBoss ESB 4.5 JMS queue had loads of problems with high load and would sometimes just completely drop the queue. We moved to JBoss ESB 5.1 with ActiveMQ, that proved much more stable.

Transactional atomic file manipulation and file locking
Bunch of interesting articles related to this:

• http://stackoverflow.com/questions/595631/how-to-atomically-rename-a-file-in-java-even-if-the-dest-file-already-exists


• http://commons.apache.org/transaction/


• http://www.infoq.com/news/2008/01/file-systems-transactions


• http://www.coderanch.com/t/495417/java/java/Distributed-Tx-Transactional-File-Access


• https://xadisk.dev.java.net/


• Lower-level stuff: http://java.sys-con.com/node/37798


• EJB/XA example: http://matthewneale.net/category/software-development/

Related to file locking:

• See reply 3: http://forums.sun.com/thread.jspa?threadID=5284898


• Another example: http://www.java2s.com/Code/Java/File-Input-Output/DemonstratesfilelockingandsimplefilereadandwriteoperationsusingjavaniochannelsFileChannel.htm


• "But if you can change/write the writing program: You have to change the design. App1 should write to "temporary" files, and when it's done, close and rename them to a naming convention that App2 will recognize as being "finished files, ready for processing"."


• Lock service, platform independent: http://www.devx.com/Java/Article/7870/1954. But requires all access via this service, so external FTP programs for example don't see the lock & the java program won't see a lock so read it.

Maven

• With Maven you can also have it put the sources + javadocs in the repository.
  Running 'mvn eclipse:eclipse' after that, and refresh the project in Eclipse, within Eclipse you can then see the javadocs and debug the sources.
  Just make sure you set <downloadSources> and <downloadJavadocs> to true.
  

Misc

• If you have an action that can't be made transactional (e.g a file move), do that as last thing in your steps. More precisely: start a (e.g database) transaction, move the file. If that move succeeds, update status that move was successful. If that move fails, rollback the transaction, and thus is the status of that file still in "to move".