$ mvn eclipse:clean
$ mvn eclipse:eclipse -DdownloadSources=true -DdownloadJavadocs=true

Synapse comes packaged as a war, if you are using Maven, you should be able to use an overlay to modify the default configuration to suit your needs. On the note of configuration, this page documents one way of protecting your web service against a DOS attack, and that is by using a Throttle Mediator and Concurrency Control (in Synapse parlance).

In my case, I’m using a cloud based platform as a service provider, so low level firewall work is not going to work for me. Instead a proxy such as Synapse, routing HTTP based SOAP requests, seems to be suitable.

I hope to update this post once I have tested and deployed it all, which may take some time, since the web service is far from finished. Its good to know about Synapse though, as now I can stop thinking about security for a while and an intentional (or unintentional) DOS attack. Not sure if I could restrict load of a per client basis with Synapse, but at least global throttling is better than nothing.

If I can add some context to labelling the presentation as excellent. In essence it represents what I regard as best practices. Setting up the mentioned infrastructure takes time, but WILL save time and money in the long run. Here are some other reasons why I advocate the use of the practices outlined in the presentation:

• I’ve had the misfortune of a three month stint as a human continuous integration / deployment “Jenkins” in the early days of a large scale enterprise project, this has left me scarred and obsessed with automated deployment and subsequent testing.
• I’ve seen Liquibase replicated many times, at considerable expense.
• If you don’t set it all up early in a project, you will pay for it with wasted time, one way or the other.

There where no doubt thousands of systems that had glitches associated with 29 February today, and covering it up is most likely standard procedure, and who could blame the companies in question.

In any case, one of the biggest crashes of the day, that made the news, seems to be a health care payment system processing 150 000 transactions per day, the best line is this, and I hope SVN will never show this I’m this someone:

A knowledgeable source said the outage arose because “someone forgot to add the 29th of February” to the system.

Well, it seems its called the Leap year bug, and here are some more occurances:

• Licensing system bug report
• “Known issue” in Excel that won’t be fixed
• The Daily WTF: DATE_NOT_FOUND

$grep -rin 'methodname' .

wcgrep -l methodname

Looks like I’m not the only one using $grep -rin. In any case, there is a new, clever kid on the block, freshly installed in /usr/bin: wcgrep -l methodname

It is smart enough not to search Subversion’s text-base files, something that has plagued me, and perhaps you too. For an entertaining post on the topic, read this post on justinsomnia.org, published six years ago, ouch, that rubs some serious salt into the wound.

You can find the wcgrep script HERE.

A Spring Container In The Real World

Ala JavaSpecialists’ newsletter, this post comes to you from the beautiful Kuils River region of greater Cape Town, also known as the Kuils Riviera. Here you are reminded that to some “life is not a beach”, in particular when passing by the local township where dismal poverty and a hand to mouth existance reigns.

On that note, lets dive straight into the subject matter of this post, performing the most basic validation in your Spring beans to quickly detect stupid mistakes.

Now, as a Spring user you have a number of options when it comes to configuring dependencies you wish to have injected into a given bean. You can use autowiring, which itself has further options, such as autowiring by type or name, or you can use xml configuration with explicit bean references. Regardless of what you use, it pays to use the Spring container’s initialization callback mechanism to avoid or easily detect basic mistakes that can easily eat up hours of development time. This entails validating your dependencies, at the very least in terms of whether they are null or not, in a consistent fashion in any given project.

Lets first get onto an example of such a basic mistake, in which a suspected wiring configuration error, which turned out to be a programmer error, cost precious time, and then move onto what do to, consistently, to avoid future similar wasteage.

BEFORE

Herewith a class under test, note the @Autowired bean propertyService.

public class ConfigServiceImpl implements ConfigService {

    @Autowired
    @Qualifier("propertyServiceBean")
    protected PropertyService propertyService;

    // NO INIT METHOD

...
}

Here is the stupid mistake.

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {"/com/mayloom/activiti/config/spring-context.xml"})
public class ConfigServiceTest {

   @Autowired
   private ConfigService configService;

   @Test
   public void updateConfiguration() {

      ConfigService configService = new ConfigServiceImpl(); // This line must be removed

      Properties props = configService.getProperties();

The mistake is the programmer is autowiring the configService yet also instatiating it. The latter renders Autowiring of dependencies in configService as useless, the entire line must be removed. It could be that this was a class that was later turned into a Spring bean, so just an oversight.

This the the result of the mistake, or at least a snippet of the surefire report showing the offending NullPointerException.

-------------------------------------------------------------------------------
Test set: com.mayloom.config.ConfigServiceTest
-------------------------------------------------------------------------------
Tests run: 1, Failures: 0, Errors: 1, Skipped: 0, Time elapsed: 0.282 sec <<< FAILURE!
updateConfiguration(com.mayloom.config.ConfigServiceTest)  Time elapsed: 0.266 sec  <<< ERROR!
java.lang.NullPointerException
	at com.mayloom.config.ConfigServiceImpl.getProperties(ConfigServiceImpl.java:72)

Now, if you had been making various Spring configuration changes in your project, and you see the above, one could start thinking that a wiring configuration error is the cause and waste hours reconfiguring and basically looking in the wrong place, even though the mistake made is quite obvious to us now.

AFTER

To quickly rule out wiring errors as a cause, in this case, and in general, all one has to do is to check that wired dependencies are not null as shown in the Default initialization and destroy methods section of the Spring manual.

So, we would end up with the pertitent section of our spring configuration looking as as shown below, with the default-init-method being what we want to include.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
           http://www.springframework.org/schema/context
		   http://www.springframework.org/schema/context/spring-context-3.0.xsd" default-init-method="init">

Next, we’ll update ConfigServiceImpl as shown below.

public class ConfigServiceImpl implements ConfigService {
	
  @Autowired
  @Qualifier("propertyServiceBean")
  protected PropertyService propertyService;
	
  // this is (unsurprisingly) the initialization callback method
  public void init() {
    	log.info("==================== ConfigServiceImpl =========================");
        if (this.propertyService == null) {
            throw new IllegalStateException("The [propertyService] property must be set.");
        }
    }

Thats pretty much it, no advanced concurrency lesson here, no generics to marvel at, but it may save you time.

Brute Force Fix

To get onto the fix first. All I needed to do was to configure the nproc settings for the user in question (it happened to be jenkins) upwards in /etc/security/limits.conf

Playing

Before getting onto the most obvious fix, I went off on a tangent and refreshed my memory on the effects of the heap size, permanent generation size, thread stack  size and other related topics (the bash based thread count script is a work in progress). A simple program to help you determine how many threads you can create can be found below if you are also keen on experimentation.

public class RunOutOfMemory {

/**
* Results
*
* ==== Environment: 32bit Win 7, 2GB RAM, Java 7 ====
*
* Reducing the default maximum thread stack size allows more of the process' virtual
* memory address space to be used by the Java heap and vice-versa.
*
* Note, when it comes to virtual memory usage consumed by the jvm process, we are
* not including the heap and permanent generation allocation.
*
* Test: 1. ALL VM arguments at default values: OutOfMemory with 3974 threads =
*                                                       1238 MB (320k / thread)
* 	2. -Xss1m, rest VM arguments at default values: OutOfMemory with 1211 threads
*                                                                           = 1211 MB
* 	3. -Xss2m, rest VM arguments at default values: OutOfMemory with 533 threads
*                                                                           = 1066 MB
*       4. -Xss128k, rest VM arguments at default values: OutOfMemory with 10358 threads
*                                                                           = 1294 MB
*
* "On Windows, the default thread stack size is read from the binary (java.exe). As of
* Java SE 6, this value is 320k in the 32-bit VM and 1024k in the 64-bit VM." oracle.com
*
* ==== Linux ====
*
* NOTE: Pay close attention to your limits configured in /etc/security/limits.conf You
* may want to adjust the nproc setting for your process upwards if you are seeing a
* "cannot create native thread" message
*/
		public static void main(String[] pArgs) {

			try {
				// keep spawning new threads forever
				while (true) {
					// thread begins execution, JVM calls run method of this new thread
					new TestThread().start();
				}
			} catch (java.lang.OutOfMemoryError e ) {

				// when out of memory error is reached, print out the number of
				// successful threads spawned and exit
				System.out.println(TestThread.CREATE_COUNT);
				System.exit(-1);
			}
		}

		static class TestThread extends Thread {

			private static int CREATE_COUNT = 0;

			public TestThread() {
				CREATE_COUNT++;
			}

			// make the thread wait for eternity after being spawned
			public void run() {
				this.suspend();
			}
		}
}

I came across the Vaio Y Series in the aftermath of a botched laptop upgrade. It all started in an effort to enhance the battery life of the old chunky beast, without too much thought I  recently went out and bought a 64GB Kingston SSDNow V100, downloaded the freshly released Ubuntu 11.11 ISO and went to work. Sadly the laptop was in such a sad state that it didn’t work out, so I went out and bought a 32 bit Sony Vaio Y Series laptop (VPCYB35AG) which  had fairly decent reviews in terms of battery life, and I absolutely loved the size and 11.6 inch HD screen.

I started by backing up the Windows 7 Starter edition OS onto a 16GB flash drive, and then swapped drives, the reason for the backup to flash drive, in addition to the OS already on the 320GB drive that came with the laptop, was incase there wasn’t sufficient driver support for the Vaio and I had to use Windows 7. I wanted to avoid the latter since I don’t regard Windows as a suitable development environment for server-side development, which is what I specialize in. Kudos to Sony when it comes to their recovery process, I tested Windows 7 recovery on the SSD, just to be sure that it would work, and it was all effortless.

In any case, having tested the laptop without linux, I got round to creating a bootable Fedora 16 USB key and installed onto the SDD. The first attempt failed, I do not know why, so I just repeated the process. Second time round it worked just fine.

The first challenge was getting used to Gnome 3 and also inconsistent boot behaviour that may be related to the next generation InsydeH20 UEFI BIOS and GRUB2. On the inconsistent boot behaviour, that may have been caused by me leaving on the “boot from external device” option in InsydeH20, I am uncertain. With regards to Gnome 3, so far I’m just getting used to it, and I like it, in any case, I am not too concerned with such details right now, its driver support that I’m concerned with, I just want the laptop to work in terms of the basics. Overall, right now I’d say I’m enjoying the experience, and given that all I’ve done to date is to “yum update”, the existing driver support is sufficient to get to work. So I’m generally happy. I’ll update this post in a couple of weeks time, once the laptop has seen more use.

Update 28 Nov 2011

Installed the latest official ATI Catalyst driver (11.11), and Gnome 3 immediately reverted to “fallback mode”, which in terms of usability seems a fairly serious regression. Rather the vent online, contacted AMD via their web form for support, this is the request:

Hi there,

I have purchased a Sony Vaio VPCYB35AG with an AMD E-450 APU (by the way your web form only gives an option for the E-350) and installed Fedora 16 with comes with Gnome 3.

I then installed the Catalyst ATI driver (ati-driver-installer-11-11-x86.x86_64.run). Rather than improving matters, it made it worse and so I researched what might be going wrong.

In any case, as far as I can tell (please see http://ati.cchtml.com/show_bug.cgi?id=99), AMD is aware of a Graphical corruption issues pertaining to the gnome-shell, but has not done anything about it.

Please can you let me know whether AMD is attending to this issue. I am sure there are thousands of affected linux users.

Regards,
Nico

As a parting comment, I wish I could just pay Sony, or whoever else, to give me a glitch free system. In any case, lets see what AMD says.

Update 3 Dec 2011

Given that I had little confidence in getting a satisfactory response from AMD, I reloaded Windows 7 and have been using it for the last few days. I’m now back to 4.5 hours battery life, instead of the 2.5 on Fedora 16. So, this brings, sadly, an end to my attempt to get any linux distribution going on my Vaio.

I did receive the following response from AMD 2 Dec 2011, which does not inspire confidence, as it does not help me. I would have been willing to pay for a working driver.

We do not officially support GNOME3, since none of our supported distributions use it by default. Unbuntu 11.10 is the first one to ship with this product, but it does not use Gnome3 by default.

Our OpenGL team is currently aware of the issue, plans may be in place to support it later on but there is no official word as of yet.

 a naive belief in the emancipatory nature of online communication that rests on a stubborn refusal to acknowledge its downside

and Internet-centrism

a philosophy of action that informs how decisions, including those that deal with democracy promotion, are made and how long-term strategies are crafted.

Even if you have no interest in liberating the world and promoting democratization, Morozov’s concepts of cyber-utopianism and Internet-centrism are equally applicable to business and personal dealings and worth reading for this reason alone. In addition, Morozov raises valid concerns regarding the dominance and power of US service providers, especially since they are not immune to US government interference and can act with impunity when it comes to a large portion of the worlds population’s sensitive personal data.

Finally, Morozov warns against the “digital visionaries” that are seemingly ever present nowadays in all spheres of life, with entire consultancies based on, and by definition biased towards, the virtues of tweeting, Facebooking and advertising online. Such online social visionaries bring back memories of the Dot-com bubble, except this time its the Dot-social bubble. A memorable quote in this regard:

..most digital visionaries see the Web as a Swiss army knife ready for any job at hand. They rarely alert us to the information black-holes creates by the Internet, from the sprawling surveillance apparatus facilitated by the public nature of social neworking to the persistence of myth making and propaganda, which is much easier to produce and distribute in a world where every fringe movement blogs, tweets, and Facebooks.

Personally, I would give the book 9/10 and recommend it as a worthy read along-side with Naomi Klein’s The Shock Doctrine and No Logo.

This post consists of a briefly outlined set of Java Exception rules, or best practices, with an accompanying look at rule compliance using specific transient network and database layer Exceptions.

The rules are based on the relevant rules from Joshua Bloch’s lauded and highly recommended Effective Java, 2nd Edition. Bloch is arguably the authority on the subject, and his legacy includes being listed as author of the Sun JDK Throwable implementation (see @author in the source code).

RULE BOOK

The author has violated these rules hundreds if not thousands of times over the last decade. As a mitigating factor it can be argued that the rules in themselves represent exception utopia, and so, it is highly unlikely that they will all be consistently followed in any given code base, or put differently, that even with the best of intentions any software engineer will follow all of them due to say project timeline pressures.

Such pressure may however be a symptom of not asserting one’s own standards when a unit of work or project commences, to alleviate pressure one can always clearly communicate one’s own non negotiable engineering standards at the start of a project.

Rule 1: Never use exceptions for ordinary control flow

import java.util.ArrayList;
import java.util.Iterator;

/**
* Do not, use Exceptions for flow control, this is an example of what not to do.
*
* @author nico
*/
public class DontUseExceptionsForFlowControl {

 public static void main(String[] args) {

   ArrayList list = new ArrayList();

   list.add("hello world");

   // Let's to the wrong thing, and jump out of this loop with an iterator related
   // Exception...

   Iterator iter = list.iterator();

   while(true) {

     try {

       System.out.println(iter.next());

     } catch (java.util.NoSuchElementException e) {

        // Using Exception for flow control, so can safely ignore this one.
        // TODO Stop using Exceptions for flow control.
     }

   }

  }

}

Using Exceptions for ordinary control flow violates the Principle of Least Astonishment which states “the result of performing some operation should be obvious, consistent, and predictable, based upon the name of the operation and other clues”.

Rule 2: Never write APIs that force others to use Exceptions for ordinary control flow

/**
* Database layer API, implementation detail agnostic.
*/
public interface EmailDatabaseHelper {

 // TODO refactor, this forces the user to catch checked exception EmailDoesNotExistException, with an email
 // address not existing being in no way exceptional, and hence in ordinary control flow
 public void doesEmailExist(String email) throws EmailDoesNotExistException;
}

Rule 3: Use runtime exceptions for programmer errors and checked exceptions where recovery is possible

Note that this rule does not state, as you may expect, that you must use unchecked exceptions for programmer errors, since that casts too wide a net. Unchecked throwables include runtime exceptions and errors, with the latter conventionally reserved for JVM error reporting under conditions where continued execution is impossible.

Rule 4: When uncertain as to whether a condition is recoverable or not, use an unchecked exception

The reasoning behind this is simple, if you do not know how an API user will recover from the checked exception, do not place the burden on the API user in terms of trying to figure out how, and potentially wasting time concluding that its not possible.

Rule 5: Only use checked exceptions if the API user can take action to recover from the said exception

If the only course of action, that you could take, when confronted with your own checked exception, is a variation of the below example then chances are good that you should not be using a checked exception. The checked exception adds no value, so, either attempt to refactor as per Rule 6, or use an unchecked exception.

} catch (CheckedExceptionWithNoUsefulActionPossible e) {
  logger.error("an error occurred");
  e.printStackTrace();
  System.exit(1); // or stopping the current thread
}

Rule 6: Refactor, where possible, checked exceptions that violate rule 5 into a state-checking method and unchecked exception

Before.

try {
  ball.kick(HARD);
} catch (BallCannotBeKickedException e) {
  // recover from exceptional conditions
}

After. State-checking method and unchecked exception has been introduced.

// ball will not be accessed concurrently, and so the calling sequence is safe
if (ball.isKickeable()) {
  ball.kick(HARD);
} else {
  // recover from exceptional condition
}

Rule 7: Clearly document if the unrecoverability of an unchecked exception is likely to be transient in nature

Certain conditions are unrecoverable at a particular instant but not permanently, and a prime example is an exception related to a lock being held on a database table on which say an update is being attempted. Methods that throw unchecked exceptions where the exception relates to a condition that may be transient in nature should document this fact, that is that the condition may be transient, and suggest a retry in the Javadoc comment associated with the unchecked exception.

Rule 8: Use the standard Java platform library unchecked exceptions where appropriate, do not re-invent the wheel

Reuse the standard Java platform library unchecked exceptions whereever possible, whilst honouring their documented semantics. A prime example is IllegalArgumentException. See the subclasses of RuntimeException for further candidates.

Rule 9: When dealing with lower-level exceptions inappropriate to the higher-level abstraction, perform either exception translation or exception chaining

Exception translation.

try {
     // lower level method invocation e.g. JPA call
} catch(LowerLevelMethodInvocationException e) {
     // now translate the lower level exception into an exception that matches
     // the higher level abstraction in our current context
     throw new HigherLevelException(...);
}

Exception chaining with chaining-aware contructor.

class HigherLevelAbstractionException extends Exception {
    HigherLevelAbstractionException(Throwable cause) {
         super(cause);
    }
}
try {
     // lower level method invocation e.g. JPA call
} catch(LowerLevelMethodInvocationException e) {
     // now translate the lower level exception into an exception that matches
     // the higher level abstraction in our current context
     throw new HigherLevelAbstractionException(e); // use chaining-aware constructor
}

Rule 10: You MUST document all exceptions, checked and unchecked, thrown by your methods

Excuse the all-caps and repetition will all exceptions being defined, but proper documentation is in no way negotiable and is every software engineers professional responsibility. The Javadoc @throws tag must be used to document both checked and unchecked exceptions in terms of the conditions under which they will be thrown. The only difference between checked and unchecked exceptions is that you must only define checked exceptions with the throws keyword, do not include unchecked exceptions here.

Rule 11: Force including the values of all parameters and fields that comprise the cause of an exception in its detail message

Support personnel or fellow programmers, when faced with a stack trace in say a log file, require pertinent data in order to ascertain exactly what caused an exception. Without the values of all parameters and fields that comprised the exception, it may be impossible to reproduce an exception.

In terms of forcing including pertinent parameter and field data in the detail message of exception, simply do not provide a constructor that has a string parameter as detail message, rather force the user to specify the said data in the constructor.

Consider the following checked exception, which has accessor methods since as per Rule 5 such exceptions should be used for recoverable exceptions.

/**
* @author Nico
*/
public class ServiceOperationException extends Exception {

private String suppliedApiKey;

/**
* Construct an ServiceOperationException.
*
* @param suppliedApiKey    the API key supplied to the service user upon successful registration
*/
public ServiceOperationException(String suppliedApiKey) {

// detail message
super("Supplied API Key: " + suppliedApiKey);

// capture for recovery purposes
this.suppliedApiKey = suppliedApiKey;
}

public String getSuppliedApiKey() {
return suppliedApiKey;
}

public void setSuppliedApiKey(String suppliedApiKey) {
this.suppliedApiKey = suppliedApiKey;
}
}

Rule 12: Ensure that your methods are failure atomic and if not document this fact in your API

Methods that are failure atomic leave an object in the state it was prior to the method invocation in the event of failure. Either ensure parameters have their validity checked before proceeding to to the actual work (and modification) in a method invoked on a mutable object, or ensure the relevant class is modified to be immutable.

Rule 13: Never ignore exceptions

From time to time you may see empty catch blocks, and in the worst case, catch blocks that catch java.lang.Exception (as listed in Tim McCune’s Exception-Handling Antipatterns) or java.lang.Throwable. This is a cardinal sin, and should never be done. At the very least, the exception should be logged (that is the entire stack trace should be logged) with an appropriate log level. In some cases, it may be justifiable to take no action, but in such cases, comments must justify why no action is taken.

RULE COMPLIANCE – RECOVERABLE TRANSIENT CONDITIONS

Some exceptions are associated with conditions that are possibly but not necessarily transient in nature, and so, when faced with them, the appropriate course of action is to automatically retry the operation. The Spring Batch Retry mechanism is geared for exactly such exceptions.

In terms of the rules, Rule 3, 4, 5, 6 and 7 are applicable, given our definition of the conditions being transient, but not with absolute certainty. In other words, given the lack of certainty as to whether the condition is recoverable, an unchecked exception should be used, as per Rule 3, 4 and Rule 5. If we choose not adhere to this rule, and feel the condition is indeed recoverable, and use a checked exception, as per Rule 5, then as per Rule 6 one should refactor into an unchecked exception with an accompanying state-checking method.

So, in short, we should use:

• unchecked exception (if uncertain if recoverable) or if unrecoverability is a certainty

• checked exception if recoverable

• even better, unchecked exception with a state-checking method if recoverable

Database Layer

Consider the following exceptions, that one may see with a Spring / JPA / Hibernate stack:

1. UnexpectedRollbackException (Spring)
2. OptimisticLockException (JPA)
3. LockAcquisitionException (Hibernate)

The decision to make all of these unchecked exceptions complies with the rules, given that within the context of a single transaction, the underlying condition is not recoverable. Within the context of retries, and so multiple transactions, the condition may indeed be recoverable due to the transient nature of the underlying conditions (a lock on a table will most likely not be permanently held). So, methods that throw these exceptions should firstly document that they throw these exceptions with @throws Javasdoc (as per Rule 10) and then also document the fact that the user may wish to attempt retries (as per Rule 7).

Network Layer

Another example of an exception that may point to a transient condition is a SocketException, especially when considering its subclasses, BindException, ConnectException, NoRouteToHostException and PortUnreachableException. These exceptions are all checked exceptions, and this is incorrect since at the instant an associated method was called, recovery would not necessarily be possible, that is, recovery is not a certainty, so Rule 3 is violated. Rather, as per Rule 4, the exceptions should be unchecked and the transient nature of the exceptions should be documented as per Rule 7.

Key References

1. Chapter 9 of Joshua Bloch’s (the author of java.lang.Throwable) Effective Java, Second Edition. If you don’t own a copy, buy one, you won’t regret it.
2. Tim McCune’s Exception-Handling Antipatterns