Category: Software Engineering

A brown-paper package.

How To Release Your Open Source Project to Maven Central

 Once you have created and fine-tuned your current programming project, you usually want to share it with all those developers out there who might have a need for your solution. For Java-based projects, Apache Maven provides a good distribution channel for this. With Maven, you can release your project to Maven Central, which is a global repository for open source Java projects that can also be accessed by build tools other than Maven itself. Since I have not found an easy-to-follow guide on how to do this in the web, I try to document the needed steps in this post.

Step #1: Sign Up at Sonatype

Sonatype is a company that provides all sorts of support and tools for “component lifecycle management” as they call it. Essential for us, they provide the access point to making a project available in the Maven Central Repository. You have to create an account at the following sites (for free, of course!):

Step #2: Create your project in JIRA

Log in to the JIRA system at https://issues.sonatype.org/ with the username and password you chose in step 1 and create an issue of type “New Project”. Most input fields are self-explanatory. In any case, here’s what you have to put into those fields:

  • Project: select “Community Support – Open Source”
  • Issue Type: select “New Project”
  • Summary: name of your project
  • Description: to make things easier on the Sonatype guys, drop a line about what your project is about
  • Attachment: don’t add an attachment
  • Group Id: your desired Maven group id (your namespace). This must be a backwards URL like org.wickedsource (which is the namespace I use for my projects). If you’re not familiar with Maven, read this article on how to choose your Maven coordinates.
  • Project URL: URL to your project homepage. You should have a homepage for your project, even if it is just the frontpage of your github or googlecode repository.
  • SCM URL: URL to your source code management system like github or googlecode
  • Username: your JIRA user name
  • Already Synced to Central: choose “No”
  • Epic Link: leave empty

Some of the fields may probably be left empty and they will still create a repository for you, but it makes it easier if you provide all information. The Sonatype guys will usually respond within a couple hours, but it may take longer – be patient.

Step #3: Create a Key Pair

It is required for any artifacts you release to be signed. The easiest way to do this is by using GNU Privacy Guard (I use the Windows version of GPG). If you don’t have a key pair to be used in signatures yet, follow this article on how to generate a key pair and distributing your public key. You will have to choose a passphrase when generating a key pair. This passphrase will be needed later. If you have more than one key pair, make sure you define one of them as the default key pair in GPG.

Step #4: Create and Sign your Artifacts automatically with Maven

Once you have installed GPG and created a key pair you can use the following maven command to sign all your artifacts automatically:
[gist file=mvn-install.sh]6653895[/gist]
Calling the javadoc and source plugins is necessary to create javadoc and source JAR files along with your actual JAR artifact. Providing javadoc and sources is a requirement for releasing open source projects to Maven Central. The gpg plugin takes care of signing all those JARs with your previously generated default GPG private key.

Caveat: the gpg Maven plugin has to be coaxed into actually signing your javadoc and source JAR files by adding the following configuration to your pom.xml:

[gist file=pom-plugins.xml]6653895[/gist]

Step #5: Deploy your Artifacts to your Staging Repository

If your request for a new Project in the Sonatype JIRA was successful, you will get an answer something like the following:

Configuration has been prepared, now you can:

please comment on this ticket when you promoted your first release, thanks

This basically means that they have provided a staging repository for you where you can upload your artifacts (automatically or manually). From this staging repository you can then manually trigger a release to Maven Central.

The important information is the URL to the staging repository. Add this URL to your pom.xml like this:
[gist file=pom-distributionManagement.xml]6653895[/gist]
Additionally, create a file called “settings.xml” with the following content:
[gist file=settings.xml]6653895[/gist]
Username and password should be the ones you chose when creating your account at https://oss.sonatype.org. Since the file settings.xml contains your credentials and thus sensitive data, it should only be kept locally and not be committed into any SCM system! The id (“sonatype” in the example above) is used by Maven to create the connection between your credentials and the repository id in your pom.xml.

Now you can call the following Maven command to create, sign and deploy your artifacts:
[gist file=mvn-deploy.sh]6653895[/gist]
At some point during the build, you should see that your artifacts are being uploaded to the Sonatype server. The upload may take some while even if your artifacts are rather small, probably because the upload to the Sonatype server is throttled.

Step #6: Promote your Repository

After the Maven build has finished successfully, log in to https://oss.sonatype.org and click the link “Staging Repositories” in the left-side navigation. In the opening tab, select your repository (you can use the “filter by profile” search box in the top right to find your group id). Click on the “close” button to close your repository. This triggers some validation checks on the files you uploaded. You can see if those validations were successful by clicking on the “Activity”-tab in the bottom part of the screen and selecting the “close” node. If there were any errors, fix the errors and deploy again. A documentation of the validations that will be performed when closing a repository can be found here.

Once all validations were successful, you can now promote the repository by clicking the “release” button. This means that you want the contents you uploaded into this repository to be released to Maven Central. After this has been done you should receive an email with the subject “Nexus: Promotion completed” and you should add a comment to the JIRA issue you created and wait for them to activate the sync to Maven Central. This may again take one or two working days. After this, your project has been successfully released to Maven Central and you can upload and then release repositories at any time without having to wait so long (repositories that have been successfully promoted once before will automatically be synced to Maven Central about every two hours from now on).

To check if your project is finally available at Maven Central, you can simply go to http://search.maven.org and search for your group id.

Caveat: I have noticed that sometimes the signature validation failed when I closed a repository on the Sonatype Nexus Server. After repeating the Maven deploy command from step #5 (sometimes a couple times) the signature was validated successfully. I have not yet found out the reason for this, since the uploaded signature files are valid if checked manually with GPG.

Resources

Much of the above information comes from this article in the Sonatype wiki. In the guide above, I added my own experience with releasing Maven artifacts so it should be easier for first-time users to follow.

5 Steps Towards an Accessible Web Form

Forms are the single most important element for user interaction in a web application. Without forms, a user can neither enter a search term on Google nor post comments on Facebook. So why is it that in many applications forms are so badly designed that they are barely usable by the common user and not usable at all for users that depend on tools like a screen reader? This article describes why accessible web forms are a benefit for every user and shows 5 easy steps to make a web form accessible. Impatient? Go straight to the slides or the github repository with the examples.

Why Accessible Forms?

When the term “accessiblity” is used in the context of a web application it usually conveys the meaning that users with some kind of disability like blindness are able to use the application. For me, the term “accessibilty” also includes the common users of an application. An application in general and a form in particular can be inaccessible even for a user who can see and use a mouse if it is badly designed. Take this form from badforms.com, for example (yes, there is a website dedicated to exposing badly designed forms!). The values of the input fields are also used as their labels. If you tab into the field, the label simply disappears and you have bad luck if you forgot what the label was. Is this form accessible? Certainly not. It’s not even accessible for a user without disability! In more conventional terms: the form has bad usablity.

Since forms are a very important part of every web application, they should have good usability. Otherwise, the users will complain and the application’s acceptance will suffer. It’s not hard to make a form usable for all users, disability or not. The 5 easy steps described below go a long way towards making a form usable and accessible for everyone.

Step 0: The Example Form

The example used in this article is a money transfer form inspired by the online banking web application of my bank. It doesn’t have a pretty CSS design, but that’s not the point of this article. The form has some flaws from a usability and accessibility point of view which will be addressed in the following steps.

Step 1: Add <fieldset>s

The HTML <fieldset> element is an easy way to give structure to your form. Its only purpose is to provide a grouping mechanism for a set of input fields that belong together. A fieldset in HTML looks like this:

<fieldset>
   <legend>Recipient</legend>
     <!-- put all input fields concerning the recipient of the money transfer here... -->
</fieldset>

So what’s the benefit of having fieldsets? By default, you get a visual clue that some input fields belong together – giving structure to your form (you can make the fieldset invisible using CSS, though). What’s more, a screen reader reading the form to a user will now always read the <legend> of the surrounding <fieldset> to the user when he tabs into a input field. Instead of labelling the first input field in the example “Recipient (Name or Company)” you can now simply label it “Name or Company”, since it is clear that it belongs to the recipient. It just looks (and in case of a screen reader: sounds) clearer this way.

Step 2: Add <label>s

HTML provides the <label> element for defining labels for other HTML elements. This is insanely easy to do…all the more astonishing that it’s not used in important web applications (like my online banking):

<label for="recipientName">Name or company*</label>
<input id="recipientName" type="text" name="recipientName" />

Every input field should have a label of some kind. Otherwise, how is a user supposed to know what to enter in that input field? The <label> element simply adds some semantics to the label that makes it possible for tools like screen readers to find the label for an input field and read it to the user. Screen readers are intelligent enough though, that when they don’t find a <label> they will simply read the text in front of the input field. However, using <label>s gives you the flexibility of not having to put the label right in front of the input field.

You may notice that in the example form I also added <label>s to the “transfer reason” input fields which didn’t have any kind of label before.

Step 3: Add Field Hints

Some input fields require more information than just a label to help the user fill it out correctly. A good example for this are input fields in which the user is supposed to enter only digits. How is the user to know he is to enter digits if it doesn’t say so? Most users know from the context that a bank code consists of digits…some users don’t know this (for example when they are confronted with money transfer for the first time). Knowing they are supposed to enter only digits helps them to enter the correct information. Hints can be added to an input field like this:

<input id="recipientBankCode" type="text"
  name="recipientBankCode" aria-describedby="bankCodeHint" />
<span id="bankCodeHint">Please enter digits only.</span>

Just add some text right behind the input field to tell the user what is expected. To support screen readers, add the attribute “aria-describedby”. This tells them where to find the hint for a certain input field so they can read it to the user when he tabs into the input field.

The WAI-ARIA standard provides many more attributes like “aria-describedby” that add certain semantics helping screen readers to decide what to read to the user. However, simply using “aria-describedby” for an input field already goes a long way towards accessibility.

Step 4: Add “Required” Semantics

For some input fields the user is required to provide input, for others he is not. It’s an unwritten law to mark required input fields with an asterisk (*). It’s actually fine to do this – assuming it is documented in a prominent spot that your form uses this convention. Otherwise, users that don’t know what the asterisk means are lost. However, there’s a more elegant way to mark an input field as required:

<input type="text" name="recipientName"
  required="true" aria-required="true" />

The “required” and “aria-required” attributes actually do the same thing: they make screen readers read to the user that this field is required. What’s more, most modern browsers will also know that the given field is required and will show a message like “this field is required” if the user tries to submit the form without entering a value. It doesn’t hurt to use both attributes – this way even software that only knows one of the attributes will be able to tell the user that the field is required.

Step 5: Add Even More Semantics

With HTML5 came a bunch of new attributes with which you can add certain semantics to your input fields. Where there were only input fields of type “text” before, you can now add input fields of several types like number, date and email. We can now change the HTML of our “amount field” to the following, for example:

 <input
     id="amount"
     type="number"
     min="0"
     step="0.01"
     name="amount"
     aria-describedby="amountHint"
     required="true"
     aria-required="true" />
  <span id="amountHint">Amount in Euro.</span>

Note that the “type” of the input field has changed to “number” and we also added a minimum value and a step size that tell the browser and screen reader that you cannot enter a negative value and that the smalles amount size is one cent. If the browser supports the number type, the browser will show an error message on submit if the user enters characters that are not digits or decimal delimiters. Sadly, the screen reader I tested with (JAWS) did not read the “min” and “step” attributes to me. It still read “Transfer Details. Amount. Amount in Euro”, so actually nothing changed here from Step 4. However, we added more semantics that can hopefully be evaluated from future generations of screen readers.

Caveat: Limited Accessibility of Automatic Browser Validations

With steps 4 and 5 we added semantics to some input fields that cause modern browsers to display error messages when the form is submitted and the user has entered something that does not abide by those semantics (i.e. he entered characters when he was supposed to enter digits). This is a very nice feature for visual users. However, my tests with the JAWS screen reader and Chrome showed that these error messages are not read to a user relying on audio. Thus, when he submits the form, he gets no feedback whatsoever and may even think that the form was submitted successfully. Obviously, the browser and/or screen reader developers need to fix this. Perhaps this is only true for Chrome. However, I will look further into this and try to find a solution if the problem also occurs with other browsers.

Conclusion

The above 5 steps showed how to increase the usability and accessibility of an HTML form by minimally enriching the HTML markup. This is hardly a lot of work and will even fit in the tightest project schedule. As it is with everything in software projects (and projects in general): if you take care of the usability and accessibility of your forms right from the start it’s a lot cheaper than adding it at a later point in time.

Steps 4 and 5 should be used with the caveat in mind that they may result in automatic input validations by the browser which are not picked up by screen readers (at least not in the combination of JAWS and Chrome that I tested with). However, instead of abandoning semantics altogether, there must be a solution using javascript (coming up shortly).

Slides

I recently held a talk about this topic. Feel free to have a look at the slides. They’re available at slideshare.

Resources

Is Endurance a Good Quality in Software Projects?

The ability to endure hardship without complaining is often considered a positive feat associated with “endurance” or “stamina”. However, endurance seems to be a double-edged sword (not only) in software projects. An appeal to speak up in software projects instead of just enduring the status quo.

The Enduring End User

Everyone who has been involved in a long-running or a maintenance software project knows this type of end user. He has been working with the software day in day out for years and knows all the pitfalls and bugs. He also knows workarounds for most of the pitfalls. Those workarounds take more time than originally intended, but he doesn’t mind. He knows that the working day is over at 5 pm. So he endures.

While the Enduring End User is not happy about all the bugs in the software he works with every day, the Outspoken End User literally hates them. As soon as someone tells him about some new workaround to be used to dodge a new bug, he grabs the phone and calls the project manager to express his disappointment in the software and submits a request to fix the bug. If no one reports the bug, how will it be fixed, after all?

The Enduring Developer

The software developer finds himself in the middle of things when working on a software project. The end user confronts him with new requirements regularly. The project manager assigns tasks and wants to know when they are done. There is no real software development process established in the project, so the developer manages all the incoming requests as fits best. He wants to perform good, so he finishes his tasks quickly. He is not always happy with what he delivers but it is like this in all software projects, after all. So he endures.

Meet the Outspoken Developer: he speaks up when he realizes that he cannot complete his tasks in acceptable time and quality. He says “no” if the project manager wants to assign him additional tasks. He alerts the project team to the missing development process. He alerts them again when nothing happens after the first time. He may not always finish his tasks in the time expected by the project plan, but he will deliver better quality.

The Enduring Project Manager

The project manager has the task of negotiating between customer (end user in many cases) and project team. Both parties are annoying at times. Especially if they just don’t shut up and keep pointing out things that could be done better within the project. But he knows how to deal with those rebellious sentiments within the project. They just have to be endured until forgotten.

The Outspoken Project Manager, on the other hand, adresses the proposals of other team members and stakeholders. He talks them through and by discussing them finds a solution that the project benefits from in the end.

Endurance? Yes, but…

The above descriptions can certainly be transferred to many more roles in projects (and not only software projects) and they are certainly a little exaggerated. However, be aware that it is easy to fall into a mode of just enduring a project instead of actively participating in it since actively participating means to step on someone’s toes now and then… .

Nevertheless,endurance is necessary: How often do we delve in foreign code trying to find a solution to some wicked bug we just can’t get our head around? In a situation like this you have to keep calm and endure the time-consuming process of finding and fixing the bug. The important thing is to not just move on after this tedious bug fix. Ask yourself what the cause was that brought you into that situation. What can be done better? If you know something, speak up and talk to people about how to make it better. Perhaps even set up a white board where proposals like this can be posted and discussed in the team.

5 Things to Consider when Load Testing

Load tests are used to assure that an application is able to cope with real life. Usually, real life looks different from any load test scenario, but such a test can nonetheless help to gain some insights. No matter which tool is used to execute the load tests, here are some things to think about while planning and executing load tests.

Run load tests early

Don’t wait until a couple weeks before the release of your software before running the load tests. Run them as soon as the software has reached a relatively stable state where developing and maintaining (!) a load test is not overly expensive. Run them occasionally. It will help to get a feel for the software. Run them in earnest a couple weeks before the release on the real server infrastructure your software is going to be deployed on. Issues with your software should have been flushed out by your earlier tests, so all issues you will find will have to do with the infrastructure.

Reconsider the parameters for your load test

Load tests are usually run in parallel. Multiple threads running on multiple servers, each of them sending requests to stress your software. Most load test tools like JMeter allow to parameterize your load tests. Think about the parameters you will have. Each thread will probably need a username and password. Don’t just let all threads use the same user. What effect will it have if the same user is logged in multiple times at once? What effect do the other parameters have?

Test your load test

Like everything else, a load test has to be tested in itself. Does it work correctly? Is the load test client thread-safe? It should be, since it will probably be executed in multiple threads simultaneously. Start testing it against you local development server before moving on to other server environments. Let it run against the target environment as early as possible, since the target environment may not be available for load testing all the time. Let it run with multiple threads before day zero to flush out any concurrency issues.

Automate load test rollout

Tools like JMeter allow running load tests from multiple clients. Installing and configuring JMeter on each of those clients can be very time consuming. You run a test, you notice something is wrong, you correct it, you roll out JMeter on all clients again. Do yourself a favor and automate the rollout process the first time you have to do it. Otherwise you will curse yourself after the third time doing it by hand. Consider using a public cloud infrastructure with automatic deployment.

Don’t plan too much

Don’t plan a strict series of test runs with all parameters like number of concurrent threads and a time schedule planned out. Most certainly, you won’t be able to follow that plan anyway. Start your load test with a few concurrent threads and slowly add to them. Write down results like average response time and other insights like server or database load for each series. After having run a couple series you will be able to draw some conclusions which help with choosing what kind of series to start next.

Quick Hack: Replace a separator with newline

Most programmers will know the situation: you want to analyze the console output of some program but program spits the interesting section all in a single line. You want to separate the single strings and put them each in a separate line. How do you do it?

Using a Unix Console

In Unix, this is relatively easy using the sed tool (using “;” as separator):

sed -e "s/;/\\n/g" myfile.txt

But Windows doesn’t provide a built-in tool for things like that, and shell emulators like cygwin are not available on all computers.

Using Ultraedit

However, if you have access to Ultraedit, you can simply to a Search & Replace. Search for your separator (“;”) and replace it with “^p”. Voila, you just created a readable list of your output.

Optimistic vs. Pessimistic Version Control

Version control is a vital element in every software project, since every project member responsible for software development or configuration management has to use it. Thus, the choice of the right tool should be well considered. With this choice comes the choice of a collaboration paradigm: optimistic version control or pessimistic locking of the resources contained in the project repository. Both paradigms offer a solution to resolving or avoiding conflicts when two developers want to access the same resource at the same time.

Optimistic Version Control

Optimistic version control is the default setting in prominent tools like CVS or Subversion. A conflict is created and resolved the following way:

  • Persons A and B get resource X from the repository
  • Person A checks his changes into the repository
  • Person B tries to check in his changes and is alerted of a conflict
  • Person B merges his changes into the version of X checked in by Person A

Pessimistic Locking

Pessimistic version control avoids conflicts altogether by locking resources.

  • Person A gets resource X from the repository, locking it
  • Person B tries to get resource X from the repository but cannot, since it is locked
  • Person A checks in his changes into the repository, unlocking resource X
  • Person B can now get resource X from the repository an do his changes

This technique is pessimistic in that it expects the worst, which in this case is persons A and B editing resource X at the same time.

Why Pessimism is bad

In my opinion, pessimistic version control is just a measure of some manager to let the poor developers feel who’s the boss. The term “pessimistic” alone should be enough to think about another solution (try explaining to someone not involved in software development why we are pessimistic about version control…).

The main reason for my opinion is the fact that while resources are locked by someone, no one else can work on these resources, effectively blocking the progress of everyone else, who just now needed to change something. Plus, if I want to change a resource someone else is currently blocking, I have to call this someone and tell him to drop me a note when he’s finished, which is organizational overhead. For resources that are changed often (like configuration files or central source files) this can be a severe problem!

I often hear the argument “But when a resource is locked, we don’t have to merge anymore. And merging is evil, because it is much work and error prone”. It is not. There are tools to help the developer to merge files. These tools are proven. In most cases you only have to look at the tools’ output an confirm it. Merging files only gets nasty when a file has completely changed…which is rarely the case.

Another argument for pessimistic locking is this: “In large teams, many people are working on the same repository. Thus, optimistic version control would result in a lot of merging”. Besides the previous argument that merging is neither difficult nor dangerous, a large team should work on a large project. What is the chance that 2 out of 20 developers try to access the same resource (out of 20 000) at the same time?

Additionally to the above argumentation for optimistic version control I have had some rather bad experiences with pessimistic version control. Someone always forgets to check his sources back into the repository. Very frustrating if this someone is not reachable by phone because he’s sick or on vacation. Furthermore, not all tools boasting the locking feature really work. In my case, the locking mechanism didn’t always work and you had to merge anyways. Or the tool let the developer choose whether to lock or not. This made it possible for Person B to check in his changes while Person A had the resource locked…automatically creating a branch without letting the developer know this. I don’t want to know what changes were lost due to this bug… . Very ugly, indeed.

So…why not let the developers actually work instead of letting them twiddle their thumbs while waiting for someone to release a lock?

Code Smell: Constants Interfaces

As I am currently refactoring the code of an application created by an insurance company, I will document some code smells I encountered. This way, I will be reminded if I am ever tempted to create such code myself. I’ll begin with constants interfaces, which are a legacy of pre-Enum days and lazy coders.

Constants Interfaces

Constants Interfaces are created in order to save the lazy coder some key strokes. A constants interface is an interface defining nothing but constants and looks like this:

public interface MyConstants {
  public static final String MY_CONSTANT_1 = "foo";
  public static final String MY_CONSTANT_2 = "bar";
  // ...
}

This interface can then be “implemented” by other classes  that need access to the constants. The constants can be used without the prefix “MyConstants.”.

public class MyClass implements MyConstants{
public void doSomething(){
    System.out.println(MY_CONSTANT_1 + MY_CONSTANT_2);
  }
}

Why is this bad? There are several reasons (some of which may be subject to flavor-discussions).

The Code Smell

First of all, interfaces were designed to describe the behavior of a component (i.e. its methods). Thus, an unbiased programmer expects an interface to describe behavior and will be irritated if he only finds constants.

Second, the use of such an interface encourages the habit of simply implementing the interface, even if only one or two of perhaps 50 constants are used. Thus, 48 constants are visible in the implementing class but are not used, which violates encapsulation. Furthermore, if the implementing class is part of a class hierarchy, all subclasses will also have direct access to the constants defined through the interface. In my current refactoring assignment the constants of a single interface were visible in >100 classes of a rather unflexible class hierarchy (which should also be subject to refactoring). Worse: some classes high up in that hierarchy implemented more than one constants interface, making all constants visible in sublasses.

Third, though admittedly a weak argument, using a constant with its class prefix (MyConstants.MY_CONSTANT_1) is more self-documenting than using the constant name alone. Assuming, of course, that the class and constants names are well chosen. If the class prefix is always used, the single advantage of constants interfaces is lost.

Better Solutions

In conclusion, interfaces defining nothing but constants are bad practice and should be avoided. If such interfaces are already present, they should be refactored into either enums or final classes with a private constructor.