Provides classes and interfaces for a wide range of programs.

Purpose

This Java code was written to provide a general purpose library of components that can be reused across other Java projects.

Performance

Some of the classes emphasize performance. They assume that RAM is plentiful and fast, and do things like allocate large buffers or something. Therefore, this library may be less suitable for applications like embedded programming unless modified.

Unit tests

This library uses the following convention: every class to be unit tested has an inner class named UnitTest that consists solely of test code for the enclosing class.

These classes are to be executed by JUnit 4. Therefore, test methods of UnitTest are always annotated with @Test, setUp/tearDown methods are annotated with @Before/@After etc.

Major exception: all the gui classes must be executed manually because they do not lend themselves to the standard JUnit assertion tests.

Eliminating all the test code from the shipping product is trivially achieved by filtering all *$UnitTest.class files from the jar file.

See the bb.util.JUnitExecutor class for ways to automatically test large bodies of code.

Unless noted otherwise, every UnitTest class should be assumed to not be multithread safe.

Justification

A common, but crude, practice is to put test code into a main method of the class. Unfortunately, this approach has serious drawbacks:

  1. test code is not cleanly separated from working code
  2. one consequence is that test code cannot be excluded from the shipping product
  3. if the main method is also needed for a true program entry point, then extra logic is required to determine whether to execute in test or real mode

An improved, but suboptimal, practice (that is unfortunately recommended by the JUnit FAQ), is to put the test code into a shadow external class (e.g. HelloWorld would have a HelloWorldTest counterpart). These test shadow classes are typically placed in a separate root directory from the working code (e.g. test versus src as the directory root). Unfortunately, this approach too has serious drawbacks:

  1. non-public members of the target class are difficult or impossible to access
  2. if the test directory root is used, the src directory tree must be recreated
  3. even worse than the initial setup, the test directory structure must be kept in sync with the src directory, which is a major problem if package refactoring is done

In contrast, the UnitTest inner class approach eliminates all the above problems and introduces no known serious issues. Therefore, it is the optimal approach.

Hmm, Paul Summermatter pointed out to me the following things that he thought were issues with using the inner class approach:
	1) the parent class gets the JUnit import statements which are not really related to it
		my eval: extremely minor issue
	2) he said that he saw problems with obfuscators when use this approach
		my eval: sounds like a bug in the obfuscator, not the approach...
	3) there is the possibility that some stupid programmer will put references in the parent class to stuff in the inner class,
	which will then break your production releases if you strip out the test inner class files
		my eval: this could be a legitimate concern with certain large teams
	4) he likes having separate files as it unclutters stuff in his opinion
		my eval: this is very subjective; I prefer it all in one...

Acknowledgement

The idea of using a UnitTest inner class approach like this was first suggested by Allen Holub in his book Taming Java Threads