Bye bye XMLGregorianCalendar (part 2)
Change generated java classes with an XJC plugin.
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.
- 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’
- String getUsage(), which should return a description of this add-on.
- 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>
Character Encode your source
When writing source code in your project, you’re always simply writing text and when you’re writing text you are saving this text on your disk in a certain encoding. This is a subtle field in which mistakes are easy and can lead to interesting side effects.
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” Read more…
The art of testing
In a few other posts on this blog I talked about the importance of unit testing and Test-Driven Development (TDD).
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. Read more…
Mini XPDay 2012 – a full and interesting day
On April 23rd, the Mini XPDay 2012 was held in conference center Kapellerput, in Heeze (NL). I went there to (re)connect with some people, and learn more about Agility and myself. It was a good day with interesting sessions in a lot of different areas.
Captcha’s in Wicket
In this post I’ll describe how to add a captcha to your web application with Wicket. A captcha is a a type of challenge-response test used to ensure that the response is generated by a person. Adding one thwarts bots sending a large amount of filled in forms to be stored.
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. Read more…
Debugging web pages on mobile devices
As a web developer I often use front-end debugging tools like Firebug (Firefox) or Webkit Inpector (Chrome) to inspect or edit html & css and to run JavaScript (for example JQuery). Regular web pages shown by the browser can be inspected using such tooling as soon as the page is loaded.
With mobile devices however this principle is not (directly) possible. Of course you can run debug tooling opening the html as a file on your pc, deploy the application to a mobile device keeping your fingers crossed hoping it will run ok. It will be frustrating to see that web pages show and act different on a mobile device compared to the content being shown in a web browser on a pc. In this case the device is a black box and most of the times you have no clue what is causing the layout and behavior problem.
Searching the internet I have found a way to actually debug web pages on the mobile device using the browser of the pc. This article will show you on how to set this up, so that you can debug mobile web apps.
Quickstart Android 4.0 mobile app development
Devnology Community Day Review
This year I had finally convinced my partner to join me for the Devnology community day, convincing him that there would be several other C# programmers there. So we set out early, braving the slippery roads (which didn’t turn out all that bad). We arrived just after the building was supposed to be open. Which would have been great if it wasn’t for the fact that it was in fact still closed. There was quite a crowd standing before the gates already. But as it was -15 degrees Celcius, we decided to stay in the car under the emergency blankets we had brought. After about forty minutes, somebody with a key showed up and we went inside. I didn’t take off my coat until after I’d finished my first cup of tea. And so the day started about fifteen minutes late.
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.
Patching open-source java software with Maven
As soon as you start using third party libraries in your project, you also introduce all the bugs in those libraries into your project.
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:
- Create a maven project for the patched version.
- Extracting the original classes out of the third party library during a maven build cycle.
- Replace the classes, which need to be patched by custom versions.
- 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.
Software licenses and commercial use
Many developers already use a lot of open-source software in their development process. They mostly use libraries offered as open-source by developer groups, but some companies even offer their complete product as open-source. This all looks as one can use it for free and with any form of integration. However, most of those software package come with a software license similar as almost commercial software does. Only open-source software is by many considered ‘free’, but what is a free software license? A free software license grants recipients extensive rights to modify and redistribute, which would otherwise be prohibited by copyright law.
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
Recent Comments