Maintaining and refactoring C++

Last week was my last day working with C++ (for a while). It’s been quite fun to revisit both the programming language and source code which kicked of my development career over 12 years ago, and I have enjoyed the experience a lot. There is also a few things to note so I put together a short list of things I found interesting during this short maintainance assignment.

Introducing a source control system

The code was originally written in 1999 and the executable files have been running in production ever since. Today the programs are owned by a group in the enterprise operations team. Their focus is to keep the systems up and running and they have little interest in the development process. There was no source control system available when I originally developed the code so,  before making any changes to the existing source, I was determined to correct that fact. A few months ago I taught myself Git and have never looked back since. Git is an excellent tool and this was an appropriate opportunity to introduce Git as suitable source control system for this code base. Being the sole maintainance developer of these programs I was happy just to add Git to aid my own productivity and give me the ability to safely abort a change should the need arise (and it did), but it will also pay off in the long run.

Updating to new IDE

Once a source control system was in place, the next step was to pick out the correct file candidates from each project to be checked in to the repository. I didn’t want every project file source controlled and this was a good occasion to get a bit more familiar with some of the lesser known project files used by the IDE, and also how to configure Git to filter file names/paths. Originally, the projects were all developed using Microsoft Visual C++ version 6 so the first step was to get them updated to a newer C++ IDE, which just happened to be Visual Studio 2008. Once the project files I needed were identified, these were checked in to the repository and tagged as the base version. Safe and ready to go!

Automatically updating the projects from Visual C++ 6.0 projects to Visual Studio 2008 solutions went ahead problem free – the IDE handled it all. My job was then to rid myself of the unnecessary project files only used by the old IDE. The (newer) Visual Studio C++ compiler has grown a lot “smarter” so a few syntax bugs had to be ironed out before the old code would build. There were also warnings due to calls to C++ standard library functions that now were deemed unsafe. In most cases a safer alternative was suggested.

Visual Studio 2008 is not unfamiliar to me, and those following this blog will know that I have used it for C# development, but never for C++. I was surprised how it lagged it’s C# cousin in functionality. Among other things there is little or no support for MSBuild and the IDE has no refactoring functionality. The latter was a real let down since refactoring C++ proved to be notoriously more difficult than any other modern language I have encountered. However, a few things made the update worth it: a better compiler and some IDE features like folders for structuring the source files. Visual Studio 2008 also has line numbering which I’m pretty sure was missing in the Visual C++ 6 source code editor.

Documentation and getting familiar with the source code

By chance, it just so happened that I came across Doxygen when googling for free C++ tools. Since Doxygen can be used for C#, Java and Python (untried, but according to the documentation) I thought it would be worth the time to take a closer look at this tool and that proved to be a wise decision. Doxygen is brilliant! I have not used it for the other languages it supports, but I plan to for my next project.  It’s syntax may remind you of JavaDoc, but with the correct dependencies installed it can create useful illustrations for viewing code and dependencies. Also, when creating the documentation you can configure it to include the source code in the documentation. For me the output was html and I actually found it easier to browse through the generated Doxygen documentation with my web browser than the source code itself using the IDE! Also useful is the fact that Doxygen can tell you which functions a particular function calls, and which functions your function calls. This proved to be useful when looking for things to refactor while attempting to simplify the code.

Beautiful code

I had never really had the need for a beautifier before, but this time I wanted to make the source easier to read, and also replace tabs with spaces and a few other things. I found a beautifier named UniversalIndentGUI which also works with more than one programming language, which I think is a plus. I fed all the source files to it and out popped “beautifully formatted” C++ source code. Voilà!

Unit testing and mocking framework

In Java development, unit testing is part of everyday life and has been for quite some time. However, where JUnit is the defacto standard for unit testing for Java, there is no similar single tool which has widespread adoption for C++ development. There are many tools available, but I had a hard time picking the one which I thought had the most potential and most active user community. In the end my choice fell on Google Test which proved to be a useful tool. Along with Google Mock, a mocking framework for C++, they provide functionality for unit testing and creating mock objects.

I spent a lot of the project time trying to refactor the code to use these tools. Unfortunately the code was riddled with references to a third part library, Lotus Domino C++ API, which I could not get working with GTest. Therefore a lot of the work was trying to narrow the usage of this library to only certain parts of the code. Although this was always in my plans, I never got quite that far and ran out of time, which was a shame. Refactoring can be time-consuming…

Project improvements

I added a simple readme file and change log to each project and moved any comments referring to a changes from the source code to the change log. I hope this will prove useful to any future developers for getting a head start and saving them from starting off with the source itself. With a simple attribute, Doxygen let me include the contents of each of the files in to the generated Doxygen documentation, which I though was a nice touch.

Lasting impressions

As I said earlier, I will miss working with C++. That said, I feel I can better appreciate the syntax improvements of languages such as C#, Java and Python. I think these languages better facilitate the creation of object-oriented code without syntax getting in the way, so to speak. C++ does make you work harder, but supplies more power in return (if you need it!). It is useful to keep in mind that trying to write C++ code in a Java or C# style may well provide you with unwanted memory leaks. In C++ you use the new and delete operators to create object instances on the heap, whereas Java and C# provide garbage collection to handle the deletion of objects no longer being referenced, as you probably know. Take this example, a Java method for fetching a bucket of water could look something like this:

public Bucket createBucketOfWater() {
    Bucket b = new BucketImpl();
    b.fill();
    return b;
}

Inside the method a new instance of a Bucket class is created and initialised. The memory used for this object will be reclaimed by garbage collection once the myBucket reference to the object is invalidated. The caller does need to think of this – it happens automatically.

// someObjectInstance creates and initialises the Bucket class, the garbage collector handles the memory when the myBucket reference goes out of scope
Bucket myBucket = someObjectInstance.createBucketOfWater();
myBucket.DoSomething();

Doing something similar in C++ may not be a good idea. You may end up with something like:

// create a new Bucket of water, return a pointer to the memory on the heap
Bucket* CreateBucketOfWater() {
    Bucket* b = new BucketImpl();
    b->FillWithWater();
    return b;
}

This code works, but will burden the caller to delete the memory used for the Bucket when done. If, for some reason, the caller should forget, the memory will be lost once the pointer variable is invalidated. We then have a memory leak.

// create a new Bucket of water, return a pointer to the memory on the heap
Bucket* b = CreateBucketOfWater();
b->DoSomething();

// must remember to delete memory on heap
delete b;

A useful rule of thumb to remember is that objects should be created and deleted by the same part of the code, not spread around. In other words a function or method should not create an object on the heap and then leave it up to the caller to tidy up when done. So how do we avoid this scenario? A more suitable C++ approach could be something like this:

// function body not relevant
void FillBucketWithWater(Bucket*);
// create a Bucket instance and pass an object pointer to the method, remember to delete the memory when done
Bucket* b = new WaterBucket();
FillBucketWithWater(b);
b->DoSomething();
delete b;

So to conclude, where in Java you would ask the method for a bucket of water, in C++ you would supply your own bucket and then use another method to fill it with water! When you are done with the bucket you are responsible for deleting it since you created it.

However, although this is a clear division of responsibilities, it does make me wonder how to properly create a factory method without burdening the caller to delete any created heap objects that the factory creates.

Long time, no see?

Introduction
So what gives? It’s been seven months since my last posting. Have I really been all that busy that I couldn’t find the time to create a new posting?

Well, I guess it’s partly true. I have been busy, but I’m sure I could have found the time if the motivation was there. Rest assured that my guilty conscience has been forever weighing me down for not following up my ‘promising introduction’ to the bloging world. However, I think it’s fair to say that the main reason for my absence can be best described as “self inflicted censorship” – if we can call it that. I’ve been a little uncertain of what to write that would be of interest to others, and also try to avoid pissing off the people I work with. I’ve also been a little rundown at work at times so my eagerness to share my views has not been at it’s peek. Now, a few months the wiser, I guess I’ve gained a little perspective so the picture has become a clearer.

What’s been going on?
A lot has happened during the past seven months. The department I am working for at work has grown substantially from just two people (my boss and I) to around eleven and I guess I’ve been a part of that. My new boss sets targets and does her very best to reach them. Although she is a few years my junior, I’ve learned a lot from her, and for the most part I think she is great to work with. I like her positive attitude and have found it contagious at times. I also take a personal interest in management, good management that is, so I do a little reading on the subject on the side, and have been able to share my views with her on occasion. She is keen to keep everyone in the department happy and find us work that we find interesting. It’s truly great to have a boss that cares and can relate to what I’m doing. With her coming from a Java development background herself helps tremendously and means there has been a lot more focus on Java and Open source technology than earlier. As you may have guessed, that suits me fine, and I feel I have grown a lot, both on a personal and professional level. Compared to where I was a year ago, things are looking good, although the business markets have taken a turn for the worst during the last few months, so who knows what may happen in future? Fingers crossed.

Focus change
Everyone at my present workplace seems to think I live and breath for Java, but I’ve noticed that my main interest actually lies more towards web development based on open source technology than Java development. I haven’t really been following the Java scene actively for quite some time and feel I have fallen behind on the latest API’s and frameworks. At present Java just happens to be the vehicle I use to extract content for web development. My main goal is usually the end result which usually portrays itself in the form of a web application or customer website.

For most of my career I’ve been working behind the scenes on the backend systems, but for a long time I’ve had an interest in web frontend technology. However, it seems that web frontend technology still isn’t taken all that seriously. HTML, CSS and JavaScript are considered technologies that you are expected to pick up as you go along and not really use a lot of time learning. To a certain extent this is true, but I still can’t help but find it odd that this is the case in 2008 considering just how much web development goes on in the world today. Your traditional senior programmer speaks in the language of design patterns and architecture, and although I can appreciate good backend architecture, I sometimes find the frontend a bit more fulfilling and challenging. Maybe because it’s easier to explain to to family and friends what I do for a living? Easier for them to visualize, I guess. 🙂

So, needless to say and according to my current interests, the last few months have been dedicated to working on web applications, creating company web sites and the like. At times it’s been great fun and I’ve learned a lot, especially about CSS which was something I always seemed to down prioritize and found “hard” to get comfortable with. I’m not sure what I really mean when I say “hard”, but for some reason I never really got in to it – mostly down to the fact that I had read a lot about it, but never really practiced it. I could never remember all the property names and their values, which is kind of half the point, I guess. This has now changed and within the last half year I have become more fluent in CSS and have grown to like it, and appreciated it’s power. I’ve also noticed just how bad it can get when more junior developers mess it all up, or don’t think in advance. The resulting CSS becomes a nightmare. I feel there is a great deal to be done on this frontier, but a lot of senior developers don’t want to touch it. Not challenging enough, I presume, which is a shame.

Projects
Just before the summer I got assigned to a project as a backend programmer. We were given the task of creating a company web site for a larger Norwegian gas company. The customer’s technology of choice was IBM’s Web Content Management (WCM). WCM, if you are unfamiliar, is a Java portlet based product that sits on top of WebSphere Portal Server. Although I had worked with both WebSphere Portal Server and WebSphere Application Server in the past, this was a different ball game.
We were two developers assigned to the project and luckily for me the other developer was fluent in CSS and other frontend technologies. He was a couple of years my junior, but I learned a lot from him. We both struggled with WCM at first and had to overcome a relatively high learning curve trying to find a good structure and extract our content before styling, but the end result was very good. The site looks beautiful today and the customer is happy. This was a relatively new experience for me in many ways. I don’t mean to offend anyone, but this was one of the first projects I was a part of where I actually felt I learned something of interest from someone else. Looking back, it was a great experience to follow a project from beginning to end and be part of the entire process. I’m not saying everything went smooth and we had our problems along the way, but in retrospect we did a good job. It’s just a shame the the technology, WCM in this case, is not much in use in my neck of the woods. However, HTML, CSS and jQuery parts, on the other hand, are. I also learned a bit about a few other web related things, like browser compatibility and became somewhat bemused that the tools for frontend technology development are still relatively poor. Was there really life before Firefox and Firebug?

The second project I was part of was to help refactor and expand a Java web application that is part of a company service desk for employee support. Although the technology in question was once again something odd, SAP EP using Java and SAP HTMLB in this case, I was happy to be able to introduce jQuery as a frontend alternative to help create some good looking stuff on the frontend. I was also happy to refactor some of the code, which was in dire need of some attention. Parts of it still is, I’m afraid. Old style JSP code with scriptlets etc. really do suck.

The third and final project I’ve been working on this autumn (and now nearly completed) is based on the open source Java portal, Liferay. Liferay has been a kind of baby of mine for the last 12 to 15 months. A colleague introduced me to it and ever since it seems I have been associated with the product, or at least that’s what everyone thinks at the company. In this project we created a web site for a customer to help their end users recycle materials and goods. We created a great deal of Java portlets in the process using Java, JSP and JSTL. We had to use a few of the new features of JSR-286 to get things working. In this project I also introduced jQuery into my frontend code which most certainly made some code a lot easier to both read and maintain. My CSS skills came in handy as well.

Conclusion
So there you have it and that’s it for now. A brief summary of what I’ve been up to for the past few months. Hopefully, I’ll have more for you soon, but don’t be surprised if it has more to with web development than backend programming, since that’s where my interests are at present. I’ve been reading a lot lately so expect a few book reviews soon. 🙂

Take care!

My meeting with a celebrity

Last week, a colleage and myself were fortunate to participate at a one day GSE Nordic WebSphere User Group conference held at Bouvet’s offices in Oslo. One of the conference speakers was Stefan Hepper from IBM Germany. Stefan works as the WebSphere Portal Programming Model Architect and leads the programming model part of IBM’s flagship portal product, IBM WebSphere Portal Server. However, more importantly (at least to me), he had the honorable task of working as specification lead for the JSR-168 Portlet version 1.0 specification, and is currently working as specification lead on the new JSR-286 Portlet version 2.0 specification. Naturally, Stefan spoke primarily of the new features in the upcoming WebSphere Portal Server version 6.1 product in the context of JSR-286, but the two aforementioned portlet specifications influence every serious Java based portal server like IBM’s WebSphere Portal Server, SAP Enterprise Portal, Oracle Portal Server, Liferay and JBoss Portal Server, just to name but a few.

Stefan Hepper and the site authorHowever, although Stefan answered a lot of question during his talks, oddly enough, for me the highlight was sharing a taxi and a 20 minute train ride from the conference back to Gardermoen airport (main Oslo airport) where we loosely discussed portlets and portals in depth, and Stefan willingly shared his knowledge with us indiscriminately. It goes without saying that this guy really knows his “stuff”, but it was also quite fascinating to hear how a Java Community Process expert group works in practice. I admit that I knew little of how the JCP works behind the scenes before our conversation, but I got the impression that Stefan is responsible for a whole lot of the final specification work and seems to carry a “heavy burden” by leading the group. However, you won’t find a nicer guy willing to help you with anything related to Java portlet/portal development should you need to call upon him for help.

As you may know, the JSR-168 specification is implemented and supported on almost every Java based portal server. The JSR-286 specification is expected to be finished in april 2008 and introduces quite a lot of new features. If memory serves me correctly, Stefan mentioned that the specifcation API has grown by over 100% since version 1.0. IBM WebSphere Portal Server 6.1 is scheduled for release sometime in the second quarter of 2008 and will support portlets complying with either of the portlet standards. It is also possible to communicate between portlets developed on either standard something that was not possible before between the proprietary IBM Portal API and the JSR-168 implementation.

I also mentioned to Stefan that I thought it was odd that there were so few JSR-168 or porlet related books available on the market. It just so happens that he has co-written and almost finalized a Manning book that was never published. It happens to be available for free download from the Manning web site, but requires registration (free). The book is titled “Portlets and Apache Portals” and it looks good. It also seems to cover WSRP (Web Services for Remote Portlets, version 1.0) and also portlet development using JSR-127 (Java Server Faces).

Sending SMTP mail with Java

Introduction

So your Java application needs to send a notification mail? Not an uncommon scenario, but how to do it? Luckily this turns out to be pretty easy in it’s simplest form, but SMTP configuration can be the killer. You are of course dependent on being able to access a SMTP mail server and also possessing a little knowledge of the SMTP protocol.

What you need

Some years ago, Sun released the Java Mail API. It doesn’t ship along with the standard Java distribution (yet!) so you will need to download it manually. It can be found here and at the time of writing is at version 1.4.1. The Mail API depends on code from the JavaBeans Activation Framework (JAF) so you’ll need to download that package also. It can be found at this link and at the time of writing is at version 1.1.1. Make sure you add the activation.jar file from the JAF distribution to your Java classpath and you will also need both the mail.jar and smtp.jar files from the Mail API distribution to enable you to send SMTP mail.

The code

The code itself is straightforward enough, but as I said earlier, it’s the SMTP mail server configuration that can turn out to be the problem. Specially if the server is configured to not let you use it indiscriminately to avoid SPAM etc. This will depend on the company policy configuration settings of the SMTP server you are trying to connect to.

OK, here’s a simple example of how it can be done…

import java.util.Date;
import java.util.Properties;
import javax.mail.Message;
import javax.mail.MessagingException;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;

public class Main {
    public static void main(String[] args) {
        Properties props = new Properties();
        props.put("mail.smtp.host", "your SMTP mail server here");
        props.put("mail.debug", "true");

        Session session = Session.getInstance(props);

        try {
            Message msg = new MimeMessage(session);
            msg.setFrom(new InternetAddress("from@here.com"));
            InternetAddress[] address = {new InternetAddress("to@somewhere.com")};
            msg.setRecipients(Message.RecipientType.TO, address);
            msg.setSubject("Mail subject title");
            msg.setSentDate(new Date());
            msg.setText("Message body string");

            Transport.send(msg);
        }
        catch (MessagingException e) {}
    }
}

So, to summarize, start you of by creating a Java Properties object and populating it with relevant configuration information. You need to specify the SMTP host name or IP address for the key “mail.smtp.host”. The “mail.debug” property is useful for development and will give you a hint what’s going wrong should you get into trouble. Proceed on by creating a javax.mail.Session object and passing it your properties object. To create the actual mail message use a javax.mail.internet.MimeMessage object passing along the session instance you just created. Populate the javax.mail.Message object with a valid sender address and receiver address array (mail has only one sender, but can have multiple receivers). Add a mail subject, the timestamp and of course the mail message body. Then all that remains is to actually post the message to the SMTP server. That where the hard part usually begins.
So, not that difficult all in all, but remember to encapsulate the code in a try/catch block and catch the javax.mail.MessagingException exception type for it to compile. Handle errors appropriately, there is a lot that could possibly go wrong here.

SMTP server authentication

As I mentioned earlier, configuration can be the killer. These days most SMTP servers don’t let any old message pass through the system without some kind of policy checking switched on. It is likely that you will need to authenticate your application to the SMTP server when creating the session object. It is also possible that the server will attempt to validate the sender e-mail address your application is using so you need to choose it wisely since it will need to be valid in the mail domain.

To create an authenticated session object you will need to make a few minor adjustments to the code. Create a javax.mail.Authenticator subclass and override the protected method getPasswordAuthentication. By default this method returns null, so you will have to make it return an initialized javax.mail.PasswordAuthentication object containing your username and password.

You also need to tell the session object to use your new authentication class so add the property “mail.smtp.auth” to your Properties object and set its to “true”. Also change the code that creates the session object by using an overloaded version passing both your Properties object and an instance of your new Authenticator subclass. The new code should look something like this:

import java.util.Date;
import java.util.Properties;
import javax.mail.Authenticator;
import javax.mail.Message;
import javax.mail.MessagingException;
import javax.mail.PasswordAuthentication;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;

public class Main {
    public static void main(String[] args) {
        Properties props = new Properties();
        props.put("mail.smtp.host", "your SMTP mail server here");
        props.put("mail.smtp.auth", "true");
        props.put("mail.debug", "true");

        Session session = Session.getInstance(props, new MyAuth());

        try {
            Message msg = new MimeMessage(session);
            msg.setFrom(new InternetAddress("from@here.com"));
            InternetAddress[] address = {new InternetAddress("to@somewhere.com")};
            msg.setRecipients(Message.RecipientType.TO, address);
            msg.setSubject("");
            msg.setSentDate(new Date());

            msg.setText("Message body string");

            Transport.send(msg);
        }
        catch (MessagingException e) {}
    }
}

class MyAuth extends Authenticator {
    protected PasswordAuthentication getPasswordAuthentication() {
        return new PasswordAuthentication("your username","your password");
    }
}

And that ought to do it! This code worked fine for me when testing with two separately configured Microsoft Exchange servers (ESMTP , version 6.0.3790.1830 and 6.0.3790.3959) in different mail domains as my SMTP server host, but only if clear text authentication (BASIC) was enabled on the Exchange server.

In both cases the Exchange server checked my sender address and also insisted that my application authenticate itself before allowing it to post.