In the previous post on ‘Bye bye XMLGregorianCalendar‘ I wrote about how you can influence the (un)marshalling of xml to java objects by adding an XmlAdapter to the classpath and an XmlJavaTypeAdapter annotation to a field in the java class. This technique works fine when you are actually writing the java classes your self, but: We don’t do that very often.  One of the main features of XML is that it can be validated against a schema, a contact which defines the valid options and structures with the XML. Most of the times, when we work with XML, there is a schema availabe, either as an standard defined for an industry / product or as part of the contract of a webservice. We can leverage the XSD (XML Schema Definition) to generate Java objects, which represent the elements in XML.

As a part of JAXB, the Java SDK provides ‘xjc’, a Binding Compiler also known as an Xml-to-Java-Compiler. When running the xjc command you need to specify the location of the schema and it will generate a set of appropriate java classes for you. By default, the XJC binding compiler strictly enforces the rules outlined in the Compatibility chapter of the JAXB Specification, which will result in you having fields of the type javax.xml.datatype.XMLGregorianCalendar in your classes.

We don’t want that: We want to use DateTime of JodaTime as the type for our date fields.

By using the “-extension” switch of the xjc command, you are able to influence the process of java generation by activating custom JAXB Vendor Extensions. There are common extensions publically available, but none of those helps with replacing the XMLGregorianCalendar by properly annotated DateTime fields. Therefor you should write your own extension as an xjc plugin.

Writing a custom XJC Plugin.

So we are going to implement our own JodatimeJaxbPlugin, which will change the type of all date fields to DateTime and add the proper XmlJavaTypeAdapter-annotation to those fields. Implementing such an plugin is quite easy, since you just have to extend the com.sun.tools.xjc.Plugin and implement 3 abstract methods.

1. String getOptionName(), which specifies by which command line argument value this plugin will be triggered. The default conventions is to start your option name with a capital ‘X’ to mark it as custom. For the JodatimeJaxbPlugin we use: ‘XuseJodatime’
2. String getUsage(), which should return a description of this add-on.
3. boolean run(Outline outline, Options opt, ErrorHandler errorHandler). The XJC compiler will do it’s internal stuff and then invoke this method to allow the plugin to tweak some of the generated code. The generated code is provided as the ‘outline’ of the generated classes.

The generated code by the XJC compiler is being represented in a com.sun.codemodel.JCodeModel, which allows access to the outlines of generated classes and fields. Our implementation of the plugin iterates over all generated classes, finds the fields within those classes of the type XMLGregorianCalendar and replaces those fields by an appropriate DateTime variant. The JCodeModel API doesn’t allow us to change the type of a generated fields, so we need to remove the old fields and add them again with the proper type. In that process we do want to preserve all metadata (Annotations) of the original fields and of course the getters and setters for those fields should be replaced as well, since the return type and parameter type will changes.

In order make the plugin available to the xjc compiler it has to be on the classpath and it needs to use the ServiceLoader API to register the plugin. Adding a simple text file in META-INF/service-directory with the name ‘com.sun.tools.xjc.Plugin’ and writing the fully qualified class name in that file is sufficient to register the plugin.

Running xjb from maven with the plugin

In order to trigger the custom plugin when the XJC compiler is being run from maven, you need to pass along the options to enable the extension and add the plugin to the classpath. The following sample snippet shows how to configure the maven-jabx-plugin for a custom plugin.

<plugin>
  <groupId>org.jvnet.jaxb2.maven2</groupId>
  <artifactId>maven-jaxb2-plugin</artifactId>
  <version>0.8.1</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <extension>true</extension>
    <schemaDirectory>src/main/resources/xsd</schemaDirectory>
    <args>
      <arg>-XuseJodatime</arg>
    </args>
    <plugins>
      <plugin>
        <groupId>nl.iprofs.util.ws.jaxb</groupId>
        <artifactId>jodatime-jabx-plugin</artifactId>
        <version>1.0.0</version>
      </plugin>
     </plugins>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>nl.iprofs.util.ws.jaxb</groupId>
      <artifactId>jodatime-jabx-plugin</artifactId>
      <version>1.0.0</version>
      <scope>runtime</scope>
    </dependency>
  </dependencies>
</plugin>

In our project we’ve recently moved from JDK 1.5 to JDK 1.6 and while local builds worked fine, the build server (running on Linux) started complaining:

“Unmappable character for encoding UTF-8”

Also when starting the build (using maven) we say warnings on the file encoding.

[INFO] [resources:resources {execution: default-resources}] [WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 3 resources
[INFO] [compiler:compile {execution: default-compile}] [WARNING] File encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent!
[INFO] Compiling 7 source files to /data/jenkins/workspace/trunk/email-service/target/classes
[INFO] [resources:testResources {execution: default-testResources}] [WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 2 resources


As it turns out, we had source files in our code base that were generated by a marshalling framework (like Jaxb, XmlBeans and JibX do) and these generated source file were stored in the platform encoding of our development machines (cp1252, because development machine run windows here).

We never ran into trouble before because of two reasons:

1. Character encodings are often a super or sub set of each other. As long as you stick to the ‘standard’ western European characters, changes are that you are fine (so ‘public class Myclass {‘ will work).
2. On JDK 1.5 character encoding differences are marked as a warning, not an error. The compiler reads a character that is doesn’t understand and simply continue in good faith. On JDK 1.6 however this same situation results in an error.

The generated code contained a comment block (generated from comments in the original XSD) with this text:

  /*
   * ...
   * to the front end application. When no user is available (e.g. call
   * from within a batch proces) the userNameActor `System’ must be used.
   */

The problem lies in the `System’ bit, the back tick character at the start is not common and encoded differently than the normal single quote at the end. Strangely enough both the Java 5 as well as the Java 6 compiler should have handle the input fine (comments are ignored any way), but the compiler stops after the character encoding error on JDK 1.6.

When using maven this problem can easily be resolved by either changing the character encoding of the offending file or changing the source encoding in your pom.xml:

<properties>
<project.build.sourceEncoding>cp1252</project.build.sourceEncoding>
<project.reporting.outputEncoding>cp1252</project.reporting.outputEncoding>
<compileSource>1.6</compileSource>
<compileTarget>1.6</compileTarget>
</properties>

Adding these general properties to the root pom of your project will force the compiler to use the given encoding instead of the platform default one.

Always character encode your source!

TDD helps us to ensure we’ve covered everything in our system by tests. Sure thing if you never write more production code than to satisfy a failing test, you’ve always covered all your production code by tests.

But how do we write a good suite of tests? How do we ensure that our tests help us maintaining the system? And remember, in agile development maintenance starts after the first successful compilation.

Purpose of tests

To know how to create a good suite of tests, we first must understand our expectations of these tests. What is the primary reason we need a good suite of tests?

The primary reason is not to prove that our code works. There are many ways to prove this, including an army of QA staff. Sure, it’s unprofessional to not know if all your code works, but it’s not the primary reason for our suite of tests. Why do we need this suite of tests? What do we expect from it?

The primary reason for a suite of tests is to allows us to re-factor! The suite of tests eliminates the fear of changing the code. With a good suite of tests we can re-factor the code while having continuous feedback if we broke something.

Good tests

A good unit test is Fast, Independent, Repeatable, Self-Validating, and Timely. For details on this F.I.R.S.T. acronym, read Clean Code by Uncle Bob, Robert C. Martin. Seriously, if you haven’t read it yet, order a copy now and come back after to finish reading this post.

Tests that follow this acronym, support refactoring the production code quite well. But there’s more to create a sustainable suite of good tests. Not only is a unit test independent of other unit tests, it also validates something that no other test validates. In order words, a single feature of the system (under test) is unit tested once.

Furthermore, tests must be stable, meaning that things that things that commonly change should not be asserted. E.g. asserting text on a screen leads to fragile tests; whenever the text is changed, the test fails. It’s better not to assert this text, but stub it or only assert that some text is printed.

Design feedback

Tests not given feedback about the behavior of the system, they also provide feedback about its design. Let me clarify this with an example.

    @Test public void shouldGetWeekOfYear() {
        int weekOfYear = Calendar.getInstance().get(Calendar.WEEK_OF_YEAR);
        assertThat(getWeekOfYear(), equalTo(weekOfYear));
    }

    @Test public void shouldGetWeekOfYear() throws Exception {
        assertThat(getWeekOfYear(date(2012, APRIL, 30)), equalTo(18));
    }

Don’t fix the symptom

But wait a minute. It’s nice and all that the test now is more expressive, and that this specific function is left with only one responsibility. But now it became responsibility of the caller to determine the current date. How’s that better than having a low-level function to do two things?

Indeed. Our test helped finding a much more serious design problem: the concept of date/time is not properly separated in this particular system. Now that we’ve got this design flaw clear, we can fix it.

By the way, I’m not suggesting that you create your own date and time abstractions, but access to the current date/time is a separate concern that must not be spread throughout the system. We can introduce a Clock that gets the current date/time, and use this clock to pass the current date into the getWeekOfYear(..) function.

Conclusion

When you have trouble creating the scenario for a function to be tested, listen to this feedback from your test, take the time to understand what exactly is wrong, and fix it. This way tests help you from early on to separate concerns by constantly providing feedback about the system design.

Because tests given you loads of design feedback, writing tests after the fact is not really useful. If you get this feedback after you wrote the production code, you either have to rework the production code, or worse, ignore the design feedback. Writing tests after the fact therefore makes tests more likely to fail even on minor changes to the system, and thus they support but our primary purpose of tests: the ability to re-factor!

I had to leave pretty early in the morning to be on time. Through the carpooling webpage I had procured me a passenger whose payment was to keep me awake, so the two-hour drive was a bit safer (thanks, Mark!). The traffic was not too bad and we arrived nicely on time for registration and my first coffee. After that the opening plenary began. The day was hosted by Nicole Belilos and Rob Westgeest, who also announced that this year was the 10th anniversary and something special would be upcoming for the full XP days. We’re looking forward to it!

FedEx Days: Awakening Intrinsic Motivation
This first presentation was done by Rob van Lanen and Rini van Solingen of iSense. They opted for a flexible content by letting the attendees dot-vote on the possible subjects upon entering the room. Luckily everybody wanted to know what it was, and that was explained quite nicely by Rob. He also gave very good pointers on how to organise one. Mainly: facilitate it; let it organise itself, but also some of the necessary preparations and follow-up, and some pitfalls that you have to watch out for, like management wanting to interfere with the chosen subjects.
All attendees received a paper copy of Rob’s whitepaper about FedEx days. It was a good session, that included everything I wanted to know about FedEx days.

Experience the power of visualization
This session was done by Gero Vermaas and Sander van den Berg. It was based on the book The back of the napkin by Dan Roam. The presenters first drew the model of the 4 steps of visual thinking (look, see, imagine, show) and then gave us the assignment to visualise a solution to the financial crisis. My colleague and I got no further than the first step, but we drew something and we realised that of the four elements of the first step, we only consciously addressed the first (orientation), and the rest (position, identity, direction) came automatically. Which was of course interesting to note.
After that we came to understand the working of the Map-Reduce pattern by living it; we played out the algorithm with people. This was an even more powerful visualisation as it used more senses than just our eyesight. This book definitely rose up on my wish-list, it will also be a nice book to read while on vacation.

Agile Coaching Dojo
After an excellent lunch and the afternoon opening plenary I joined the Agile coaching Dojo. This was presented by Nick Oostvogels and Bart Biernaux. They first explained the types of coaching followed by a preparation for an exercise: Personal Coaching, in which you have to listen closely, be sure to maintain trust, ask Powerful Questions, lend support to the seeker and guide him/her towards concrete actions.
The excercise was very good: we made groups of four people, of which one Seeker, one Coach and two Observers. Every group had one person that was experienced in coaching, and the rest was of varying ability. We all took turns and so I was able to coach twice and get lots of good feedback. It was also very nice to see an experienced coach in action. Calmness & Inventivity are words that now come to my mind when I think of coaching, in addition to ‘Show the path, do not walk the path’. All in all one of my favourites of the day.
[slides]

The last timeslot had three sessions that all seemed very interesting to me, but you have to make choices, and so I chose
Training from the back of the Room
This session, presented by Jef Cumps & Kris Philippaerts, was based (unsurprisingly) on the book Training from the back of the roomby Sharon Bowman. This was yet another great session where the teachers really used the techniques to teach the techniques. Training from the back of the room is about the four C’s:

• Connect (learners connect with each other, the subject, their learning goals and the goals of the session),
• Concepts (facts learners need to learn, the group collaboratively usually already knows some 80% of it),
• Concrete examples (learners should practice with the subjects) and
• Conclusions (summarize, celebrate, next steps after the training).

At one point it got very meta, it even got meta meta when one group was teaching the other groups the concept of Concepts using Concepts as a tool. It almost made my brain explode… but all in all a whole lot of fun! Plus another book to rise on my wish-list.
[slides]

The beers afterwards were a very welcome release of all energies built up over the day, but somehow I remained with my own group, so after two drinks we started our journey back to Amsterdam and Haarlem. The end of a very insightful and fun day!

This article deals with the best known one: an image with a series of characters and an input field to which the user must fill the characters of the image. First I describe how to do this, using the captcha component that is shipped with Wicket. After that I describe how to add the well known recaptcha.

Standard Wicket Captcha

First the Panel with the captcha that can be inserted to your form.

The java code is also fairly simple: A class extending Panel, having a text field with a validator and an image for the the capthca.

public class CaptchaPanel extends Panel {
  public CaptchaPanel(String id, int nrChars, boolean inError) {
    super(id);

    RandomString randomString = new RandomString(nrChars);
    String random = randomString.nextString();
    TextField textField = new TextField("imagePassword");
    textField.setRequired(true);
    textField.add(StringValidator.maximumLength(nrChars));
    if(inError){
      textField.add(new AttributeModifier("class", "error"));
    }
    Image image = new NonCachingImage("image", 
                                      new CaptchaImageResource(random));
    textField.add(new CaptchaValidator(random));
    add(image);
    add(textField);    
    }
}

Finally the validator, again a fairly simple class that performs a String comparison.

public class CaptchaValidator extends AbstractValidator {

  private String randomString;

  public CaptchaValidator(String randomString) {
    this.randomString = randomString;
  }

  protected void onValidate(IValidatable validatable) {
    if (!randomString.equals(validatable.getValue())) {
      error(validatable, "CaptchaValidators.invalidcaptcha");
    }
  }
}

The image below gives an example of the Wicket captcha:

Recaptcha

This all works well. A little too well to be honest. The captcha is too hard to read. This can could be solved by using recaptcha. Recaptcha is used widely across the internet, and as an added bonus comes with audio, so that visually impaired visitors can also use the captcha. Integrating this to your application requires a little more effort. (To read more about recaptcha follow this: link)

Again first the html:

<wicket:panel>
  <div/>
  <div  wicket:id="imagePassword"></div>
  <div/>  
</wicket:panel>

Then the Java code: again a Panel. In this case the validation is done by a the validate method, so no validator class. The recaptcha classes com from recaptcha4j.

public class RecaptchaPanel extends Panel {

  @SpringBean
  private ClientSettings clientSettings;

  public RecaptchaPanel(String id, final int tabIndex) {
    super(id);
    final String privateCaptchaKey = clientSettings.getPrivateCaptchaKey();
    String publicCaptchaKey = clientSettings.getPublicCaptchaKey();

    final ReCaptcha recaptcha = ReCaptchaFactory.newReCaptcha(publicCaptchaKey, 
                                privateCaptchaKey, false);
    add(new FormComponent("imagePassword") {

      public void onComponentTagBody(final MarkupStream markupStream, 
                                     final ComponentTag openTag) {
        Properties properties = new Properties();
        properties.put("theme", "clean");
        properties.put("tabindex", ""+tabIndex);
        replaceComponentTagBody(markupStream, openTag, 
                                recaptcha.createRecaptchaHtml(null, 
                                                              properties));
      }

      public void validate() {
        WebRequest request = 
              (WebRequest) RequestCycle.get().getRequest();
        HttpServletRequest servletRequest = 
            HttpServletRequest) getRequest().getContainerRequest();

        String remoteAddr = servletRequest.getRemoteAddr();
        ReCaptchaImpl reCaptcha = new ReCaptchaImpl();
        reCaptcha.setPrivateKey(privateCaptchaKey);

        String challenge = 
              request.getRequestParameters()
                     .getParameterValue("recaptcha_challenge_field")
                     .toString();
        String response = 
              request.getRequestParameters()
                     .getParameterValue("recaptcha_response_field")
                     .toString();
        ReCaptchaResponse reCaptchaResponse = 
              reCaptcha.checkAnswer(remoteAddr, challenge, response);

        if (!reCaptchaResponse.isValid()) {
          error("Invalid captcha");
        }
      }
    });
  }
}

To make the it work you’ll have to request a private and a public key for your site from google. To do this follow the instructions at this page:
https://www.google.com/recaptcha/admin/list

The default recapthca is displayed with colors in yellow and red and the styling instructions are in the rendered HTML. In most cases this will not match the rest of the site. Although styling options are limited, above mentioned solution supports some alternative themes. I choose clean, a mainly white theme. The other themes are: red(=default), white, blackglass and custom. The latter is for implementing your own custom theme, but that is outside the scope of this posting.

The image below gives an example of Recapthca styled as clean:

Conclusion

For implementing capthca’s in wicket multiple options are available. The one that is shipped with Wicket is relatively simple to implement and gives almost full control of the styling. Recaptcha, now serviced by Google, is friendlier to the visitors of your application, but requires more programming effort and is a lot harder to match the looks of your application.

Weinre to the rescue

First thing I was looking for in a tool is one that can be used with any kind of mobile device regardless the operating system it uses. It also has to be easy to install and configure and in usability. Last but not least: it should work like the Firebug or Web Inspector and supports the following:

• inspect / edit / delete html and css
• localstorage / WebSQL inspector
• add new events to timeline
• a console to run JavaScript code in the web page

The tool I eventually found is Weinre – WEb INspector REmote. The basic idea is that you run a server to which you connect with your mobile device and the web browser.

How does it work?

The browser will be used to debug web pages on the mobile device (while the server is the mediator). As the site has loads of information I will give you just information you’ll need to get started.

Basically you’ll need (as shown in the diagram):

• the server
• the inspector / debug client (browser)
• the target to debug (mobile device)

In order to implement this setup, you only need to do these two steps:

• (configure and) start the server.
• add a JavaScript reference in the page(s) of the web application (referencing a JavaScript file on the server) to be deployed to the mobile device.

The next paragraph will show you how to accomplish this.

Setting up your debugging environment

Server

Regarding the server you want to connect to, you have two choices:

• Use the debugging server of PhoneGap (http://debug.phonegap.com)
• Run your own local server (download link).

When your want to run the server locally then download the jar file and start it with the following command (in this case using port 8081)* :

java -jar weinre.jar -httpPort 8081 -boundHost -all-

* Per default localhost is used. In this case the server is only reachable from the machine itself. This is overridden with the boundHost argument. In this case it will accept requests from any interface on the current machine. Run java -jar weinre.jar -help for more details.

Debug target

The web page to be debugged on the mobile device has to include a simple JavaScript reference in the head par of the html (index.html in case the app is based on the PhoneGap framework):

// <![CDATA[
src="http://localhost:8081/target/target-script-min.js#anonymous">
// ]]>

The part after the hash is the GUID (unique ids), to make sure that the client does connect to the right target (as no security mechanism is in place).
A local server uses per default the anonymous GUID, so no change is needed.
In case you want to use the PhoneGap debug server, open the phonegap debug web page and enter a GUID of your choosing.
In your mobile app page use the reference as shown above and replace the anonymous GUID with the one you have entered on the PhoneGap debug page.

Debug client (inspector)

The browser that connects to the server to debug the website .
Currently browsers which are supported Google Chrome 8.x and Apple Safari 5.x.

Run the server, client & app and start debugging!

Now that everything is in place, start-up the server if you are running it locally:

java -jar weinre.jar -httpPort 8081 -boundHost -all-

Open the browser and open the root url to the server:

• http://localhost:8081/client/#anonymous (for localhost)
• http://debug.phonegap.com/client/#(using phonegap debug site)

The top of the screen will show you if a target device is connected. Once connected, you’re ready to go and do some cool mobile debugging!

Installing and configuring the Android SDK

The Android SDK contains tools and sample code for developing Android apps.

Install the Android SDK

To install the SDK follow the next three steps:

• Download the sdk zip file from here: http://developer.android.com/sdk/index.html and unzip the file.
• Create a new environment variable ANDROID_SDK pointing to the root of the exploded zip directory (used by maven) and extend your environment variable PATH by adding ANDROID_SDK/tools and ANDROID_SDK/platform-tools (in order to find the SDK executables).
• Test if all SDK commands can be run from anywhere in your OS console/shell. Open a new console and try if the following command works: adb version.

Configure the Android SDK

In order to use the SDK you need to configure it. This can be done by:

• Run the following command (plain and simple:) in the console: android
• Check the complete folder Tools and from the Android version(s) you want to support expand the folder and check the SDK Platform.
• Click on the ‘install packages’ button.

Create, build, deploy and run a basic android application

To quickly setup a basic maven project, the maven Maven-Android-Archetypes will be used.
Navigate to the folder where you want the create the project and set up the project by running the command below.
Do notice that the value for the platform option must match the API version of the SDK you have installed (in this case 15).
You can change the groupid and artifactid if you like before running it. While running just hit enter two times to complete the creation of the project.

mvn archetype:generate \
-DarchetypeArtifactId=android-quickstart \
-DarchetypeGroupId=de.akquinet.android.archetypes \
-DarchetypeVersion=1.0.7 \
-DgroupId=your.company \
-DartifactId=my-android-application \
-Dplatform=15

Change your dir location to the root of  ‘my-android-application’ folder.
The project is ready to be build and to be deployed to your mobile device*. The install argument will create an .apk deployment in the target directory. The android:deploy argument will use the android SDK to actually deploy this .apk to your device. Connect it via usb and run the following command:

mvn clean install android:deploy

There you go. The app is installed! Check your device. It should contain a new app called ‘my-android-application’ . When running it, it will show you a plain nice hello message.

* If you should not have a device running the Android OS, you can alternatively configure and run the Android emulator. See the section Android emulator and SDK tools on how configure it. The installation / deployment step mentioned above will be the same for an emulator.

Integration of Android SDK into your IDE

If you want to integrate the Android SDK with one of the following IDEs then install the mentioned plugin:

• Netbeans  -  NBAndroid
• Eclipse – ADT (Android development tools)
• IntelliJ – IntelliJ IDEA Ultimate edition version 10.5 or higher supports Android development by default

Android emulator and SDK tools

Running the Android emulator

When you do not have a mobile device or just want to run the Android emulator, you have to create an Android Virtual Device (AVD)..
In order to do this follow these steps:

• Run the android command again.
• If the Android API is 14 or higher (4.0 and up) then install from the same Android version, select the ARM EABI 7a System Image (check box below the SDK) and install it.*
• Run android list targets to list all available Android targets.
• android create avd -n -t (name is the logical name of AVD to be created, id is the target id of one of the Android targets from the previous step).

Now that you have created an AVD lets run it the emulator. Do know that API 14 and up may take some time to load.

• emulator -avd <avd-name>

Other interesting SDK commands

Show running devices (mobile devices as well as emulators): adb devices
Install an apk deployment (-s is optional): adb install
Remove app from device: adb uninstall
Run adb help for more information.

*If you don’t execute this step for these APIs then you will get the following error when you try to create an AVD:
Valid ABIs: no ABIs.
Error: This platform has more than one ABI. Please specify one using –abi.

More info on Android app development

To get more info on Android development a lot of resources are available. A good starting point would be developer.android.com in particular the dev guide section and the tutorial resource section. In addition I recommend the following resources:

• Android Development Community
• Shiva3D

Amongst others these books contain more on Android as well:

• Professional Android Application Development – Reto Meier
• Unlocking Android – W. Frank Ableson, Charlie Collins, and Robi Sen
• Hello, Android  – Ed Burnette

How to show code quality – Joost Visser

The session started out well with an open discussion, trying to find out what quality is. According to Joost there are two kinds of quality: funtionality and technical quality. Whereas functional quality (the code does what was specified) is relatively easy to point out, technical quality is less tangible. This lead to a discussion on what makes code beautiful. Some aspects that were pointed out are easy to understand, performance, loosely coupled code, code split according to responsibilities, and compliance to coding standards, to name a few.

Sadly, it seemed to me that this discussion took a bit too long for the allotted time, as afterwards the presentation didn’t quite live up to the standards that had been set in the first half. The second half went on to talk about quality certificates, while I had been expecting to be shown some tools or other useful tips on how to show code quality to management and clients. One final important statement I took away was that quality measurements merely indicate symptoms, and that after they are done you have to spend time analysing what the actual problem is.

To infinity… and beyond (no seriously!) – Felienne Hermans

Felienne warned us in advance that this session would not have any practical applicability for us, as it would be highly theoretical mathematics. She told us about Brazilian tribes that had no numbers larger than three, and how they put numbers (explained to them with a number of dots) on a logarithmic scale, instead of the regular linear one. Which turns out to be what young children do too. Then she showed us Zenos theorems, and Galileos paradox. She explained Hilberts hotel and showed us how there are just as many numbers in between 0 and 1 as there are between -∞ and ∞.

But what boggled me the most was that as there can be nothing in between 0,999… (followed by an infinite amount of nines) and 1 they must be equal. I tried arguing that the same would be valid for 0,999…98 and 0,999…99, but she explained that defining an end to the number makes it a different case. I’m not sure I quite understand, but it was a lovely demonstration of maths.

Extreme startup – Willem van den Ende

My final session of the day was a programming session for which I’d specifically brought my laptop. Alas, I didn’t quite have my IDE ready yet, having only gotten the laptop a few days earlier, so I didn’t have the proper tools installed yet. So it took me quite some time to get ready (which was not something my team mates could help me with). The idea was that you had to build a HTTP request handler and that the requests would contain questions that you would have to reply to.

There were nine participants and we teamed up in groups of three. The team I was in consisted of three ladies, so naturally I opted to call us Team Duchess (as we were programming in Java). To Willems great despair, all teams used Windows. It took ages to find out that my laptop was having trouble with a firewall. But then we finally got it working. We had nearly run out of time, but we did get to answer about four different questions. If we’d had more time, we probably would have won. As it was, we joined the market so late, we didn’t have a chance anymore. It was a really great workshop that showed how code quality is often set aside in favor of deadlines.

I skipped the fourth session, as I was quite tired already. I would have gone to join in the coding kata otherwise, but that’s something you need a clear head for. All in all I had a lovely day.

There are various ways to handle these kinds of situations:

• Sometimes you won’t even notice the bugs being present, when you don’t use that section of the library.
• When you do notice a bug, you can upgrade to newer version of the library in which the bug was already fixed.
• You might create a work-around in your code.
• Or you could patch the third-party library.

Sometimes the patch already is present in the trunk of the project, but no newer release is made yet. Encouraging a release-early, release-ofter strategy sometimes work to get a stable release without the bug being present, but it’s good to have alternatives. Most likely you aren’t a committer on the project of the library, so you become dependend on other developers, which could create problems for your deadlines.

This procedure in this post will describe a way to create a stable patched released version of the third party library in your own software repository.

In this post I will use the recaptcha4j library as the example of the software to patch. The only available released version of that library is net.tanesha.recaptcha4j:recaptcha4j:0.0.7. The code in this library still references the server URL’s on https://api-secure.recaptcha.net instead of the newer https://www.google.com/recaptcha/api. Since the names in the SSL certificates won’t match various browsers will show warnings or won’t work at all on the old URL’s. So the task at hand is to create a patched version of the library, which will use the new URL’s.

One way of doing this is copying the entire project into your own source code management tool, make the changes and release software. I prefer to keep the original software as seperate as possible from my own changes. So my way of doing this is:

1. Create a maven project for the patched version.
2. Extracting the original classes out of the third party library during a maven build cycle.
3. Replace the classes, which need to be patched by custom versions.
4. Create a new jar-file containing the combination of original and patched classes.

Note: Of course I use some naming convention to prevent version conflict between the original software and the patched version.

Create a maven project for the patched version.

Of course you need a project location in your own source code management tool and create the default maven project structure with a pom.xml.

To identify the patched version of the library I use the groupId and artifactId of the original library, so everybody will still recognize dependency on the third party library. Within the version of I add an extra version-digit plus a describtion of the patched.
In our example it would become:

  <groupId>net.tanesha.recaptcha4j</groupId>
  <artifactId>recaptcha4j</artifactId>
  <version>0.0.7.1-iprofs-https-patched-SNAPSHOT</version>

Within this pom I add a dependency to the original ‘broken’ version of the third party library. This will add all classes and dependencies to the classpath of my project enabling my IDE to use those classes during the build.

  <dependency>
    <groupId>net.tanesha.recaptcha4j</groupId>
    <artifactId>recaptcha4j</artifactId>
    <version>${original.recaptcha4j.version}</version>
    <type>jar</type>
  </dependency>

Extracting the original classes

During the build I use the maven-dependency-plugin to extract the classes from the original version to the target build location. This will ensure all classes will become part of the new patched jar-file. You need to exclude all broken classes from extraction, because your patched versions will not become part of the jar-file if the originals are already present in the target location.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <executions>
    <execution>
      <id>unpack</id>
      <phase>generate-sources</phase>
	<goals>
	  <goal>unpack</goal>
	</goals>
	<configuration>
	  <artifactItems>
	    <artifactItem>
		<groupId>net.tanesha.recaptcha4j</groupId>
		<artifactId>recaptcha4j</artifactId>
		<version>${original.recaptcha4j.version}</version>
		<type>jar</type>
		<overWrite>true</overWrite>
		<outputDirectory>${project.build.directory}/classes</outputDirectory>
		<excludes>
		  **/ReCaptchaImpl.class,**/ReCaptchaFactory.class
		</excludes>
	    </artifactItem>
	  </artifactItems>
	</configuration>
     </execution>
   </executions>
 </plugin>

Replace the classes, which need to be patched by custom versions.

Within my project I create the same package structure and classes for all classes, which need to be patched.
Extracting them from a source jar is a very good way to get started or copy them from the libraries version control system.
In my example it would be net.tanesha.recaptcha.ReCaptchaImpl.

Create the patched jar-file.

For this step you don’t need to do anything special. If you properly excluded the patched classes the maven build process will extract and compile all classes to the proper locations and the maven-jar-plugin will build your patched jar-file. Using your normal maven release process you are now able to create a patched stable release version and deploy it into your own software repository.

Tricky situations.

After using this procedure to create a patched version of the recaptha library and redeploying the software I still noticed that references to the old server URL’s were being used. The cause of this weird behaviour was a compiler optimalization called ‘Constant folding‘. ’Constant folding’ is the proces of replacing all references to or calculations of constants values by the final constant value in the byte code of the compiled classes.

Within the recaptcha library the ReCaptchaFactory references the constants defined in the ReCaptchaImpl. In the original class file for the ReCapthcaFactory the values still were the server URL’s which we needed to patch in the first place. Therefor the exclusions in the dependency extraction does contain that Factory as well.

Recommendations.

Contribute back to the original project.

If you went through all this trouble to fix a bug in an open source library, it is recommended that you create a patch of your changes and submit those to the open source project. Many project welcome such contributions and you get to make the world a better place for everybody.

Monitor releases for the original project.

Subscribe to the release mailing list of the original project and monitor their future releases. As soon as the provided a release, which incorporated your patch, switch to using the normal orginal library again.

HISTORY

In the mid-1980s, the GNU project created for each of hist software packages a free software license. The first free license in history, the GCC General Public License, was applied to the GNU Compiler Collection and was initially published in 1987. The first BSD license dates to 1989 and was amongst the first free software licenses. In 1989, the first version of the GNU General Public License (GPL) was published, but within 2 years an updated Version 2 of the GPL (GPLv2) was released. GPLv2 went on to become the most widely used free software license. With the rise of the Internet to the public in the mid-90s and until the mid-00s, a new trend started where companies and projects wrote their own licenses, or adapting others’ licenses to insert their own name. From that point on also the complexity of licenses increased significantly due to incompatibilities. For instance, the GNU GPL version 2 license, has been brought to court, first in Germany and later in the USA. In the German case the judge did not explicitly discuss the validity of the GPL’s clauses but accepted that the GPL had to be adhered to “If the GPL were not agreed upon by the parties, defendant would notwithstanding lack the necessary rights to copy, distribute, and make the software ‘netfilter/iptables’ publicly available”, because the defendant did not comply with the GPL, it had to stop using the GPL-ed software. The US case (MySQL vs Progress) was settled before a verdict was arrived at, but at an initial hearing the judge “saw no reason” that the GPL would not be enforceable. After this, different groups promoting and defending specific software licenses started to exist.

SOME MAINSTREAM LICENSES

The following section provides a summary of well-known licenses and how they could be used effectively in commercial software.

NOTE: The following statements are guidelines, but for usage of software with a specific license is advised to search legal council as, for instance, this might also change per country’s law.

GPL [1]

The GNU General Public License (GNU GPL or simply GPL) is the most widely used free software license, originally written by Richard Stallman for the GNU Project. GPL is based on the copyleft license that derived works van only be distributed under the same license terms. Anyone using a software library with a GPL license must effectively assign the same GPL license to its final software product.
With the concept ‘copyleft’ an author surrenders some but not all rights under copyright law. Instead of allowing a work to fall completely into the public domain (where no ownership of copyright is claimed), copyleft allows an author to impose some restrictions on those who want to engage in activities that would more usually be reserved by the copyright holder. Under copyleft, derived works may be produced provided they are released under the compatible copyleft scheme.

BSD license [2]

The original BSD license was used for the Berkeley Software Distribution (BSD), a Unix-like operating system after which it is named. The license was initially written by the Regents of the University of California, because BSD was first written at the University of California, Berkeley.
The BSD license are a family of permissive free software licenses and software libraries with the BSD license allows proprietary use. Such a software library can be incorporated without enforcing the newly created software to be release under the same BSD license as GPL would have done. Therefore, works based on the software may be released under a proprietary license or as closed source software.

MIT License [3]

The MIT License is a permissive free software license originating at the Massachusetts Institute of Technology (MIT). The license allows reuse within proprietary software provided all copies of the licensed software include a copy of the MIT License terms. The resulting software that incorporates a library with a MIT license  retains its proprietary nature even though it incorporates software under the MIT License. In short, all derived works require that the copyrights of the incorporated software is attributed, but may have a different license.
A well-know derived license is the XFree86 project that was the X-Windows system for Unix like operating systems.

Lesser GPL [4]

The GNU Lesser General Public License (LGPL) is created by the Free Software Foundation as a compromise between the strong-copyleft GNU General Public License (GPL) and permissive licenses such as the BSD licenses and the MIT License. The main difference between GPL and LPGL is that the latter allows software linked against LGPL software to be any other type of software license, but any derivative work of the LPGL-ed software falls under the LGPL license. Essentially, if you use the LGPL software you have the freedom to choose the license, but if you are modifying the software itself those changes must be published under LGPL.

Apache License [5]

The apache License is a free software license created by the Apache Software Foundation. This type of license allows users of the software the freedom to use the software for any purpose, to distribute it, to modify it, and to distribute modified versions of the software, under the terms of the license. But the Apache License does not require modified versions of the software to be distributed using the same license (in contrast to copyleft licenses), but in every licensed file, any original copyright, patent, trademark, and attribution notices in redistributed code must be preserved. In case a licensed file has been changed also a statement must be added that it is changed compared to the original licensed file.

Multi-License

This approach to licensing is used by commercial companies that like to have their product offered as open source. That way and most commonly done, commercial companies offer under an open source license the software to be used for free as long it is not for commercial usage. As soon the user would like to use the software commercially a different commercial license is applicable.

SUMMARY

When choosing open source software as components for your application it is important to realize the eventual use of the application. Is it commercially used or distributed are the main questions that impact the choice. Almost any software that is used commercially is better not to implement with GPL licensed software as you application is that also GPL and should be distributed as open source. Various other licenses, such as BSD, MIT, Apache or the LGPL license, have little impact on your choice of license of the new application and allow commercial usage.

References:

[1] http://en.wikipedia.org/wiki/GNU_General_Public_License
[2] http://en.wikipedia.org/wiki/BSD_licenses
[3] http://en.wikipedia.org/wiki/MIT_License
[4] http://en.wikipedia.org/wiki/LGPL_license
[5] http://en.wikipedia.org/wiki/Apache_license