There are a few sure-fire ways to do it, but only one to do it without direct access to the original repository server, and (after initial creation of the repository) not even direct access to the back-up server. Well, you need HTTP access, but that’s all. We’re assuming proper access is allowed, and that neither server minds the occasional suck of the bandwidth.

To start, you need a Subversion repository on which to store the copy. Somewhere on this blog is a quickie how-to that will help get one configured. Once you have a server configured, you need to make a repository to receive the back-up; be sure that the server configuration allows exposing the repository path as necessary.

Unless you have some web-based tool to create the repository, you need to pop into the back-up “to” server (hereafter named “backup.server”) and create the repository (cleverly named “Repository”). Note my paths are for not-Windows, so if you’re on that OS, flip the slashes over. I’m also making some assumptions about the system configuration and permissions. If you’re not allowed to do this, of course, it will fail.

svnadmin create /path/to/svn/Repository

The command won’t return anything, but you should be able to look and see the new Repository folder in the /path/to/svn, or whever your subversion repository will live (in agreement with your Apache configuration). There’s one thing that Subversion doesn’t do by default, and that’s configure the hooks in a way that allow us to use the provided Subversion svnsync tool. In the new repository folder is a folder named “hooks.” By default in that folder are a number of templates. One in particular is of interest, the pre-revprop-change.tmpl file. The template file does some checking to ensure that a particular entity is limited to a particular action. The documentation notes that the file must exist and return zero for the hook to pass; you can just create an empty, executable script file named pre-revprop-change in that folder, and it works fine. Something very simple like #!/bin/sh works. Of course, it doesn’t do any protection (more on that), but gets us flying into the back-up.

After creating the repository and creating the pre-revprop-change script, direct access to the server is no longer required. Somewhere in the middle, either on the source server, destination server, or some other system in the middle with HTTP access to both and Subversion installed, we can kick off a pretty straight-forward svnsync command.. Here’s what it looks like, and following is a discussion of the bits we’re using.

svnsync init http://backup.server/Repository http://source.server/Repository --source-username=sourceUser --sync-username=syncUser

The “init” tells svnsync to configure the destination server so that it knows . It also does a little file manipulation on the system to create configurations to link the two together, hold usernames and passwords, and other Subversion magic. For the curious, watch the files in your home folder’s .subversion folder (again, on not-Windows) to see what changes. Slightly uncomfortable is that there are files there with passwords (assuming there are passwords associated with the servers) that are stored in clear-text; they are stored with owner-only permissions, but their presence can make some people squirm. Used as described above, svnsync will prompt for the passwords as required; add the parameters of –source-password and –sync-password to avoid being prompted (and have the passwords in your history…).

The first URL is the destination, or the back-up server Repository. Of course, the full and correct URL should be used.

The second URL is the source. Also here the full and correct URL should be used.

The source- and sync-username parameters (each preceded with double-hyphens) are optional. They’re used to provide the user to gain access where authentication is required. If authentication is required and these are not provided, the current username will be used. As noted in the comments, there are similar source- and sync-password parameters, too, to avoid being prompted if the server requires passwords.

If this is successful, a very simple response will confirm that the properties are configured.

Copied properties for revision 0.

Once done, trigger the copy command. This will be the same command to copy the first and each iteration in the middle. Issuing the command will bring the repository up to date, in full Subversion fashion, maintaining all of the history along the way. Since the init starts at revision 0, it may be some time if the repository is large or has a lot of revisions. While it’s working, there should be a cycle of “copying properties” and “transmitting data” and “committed version” messages as each revision is copied. When it reaches the current revision it will stop.

svnsync sync http://backup.server/RepositoryPath --source-username=sourceUser --sync-username=syncUser --sync-password=syncPassword

Here note that the sync-password parameter is provided. This line can be added to a cron job or other automatically run script to provide periodic updates to the repository. Of course, again, use the correct values for your system.

That’s the guts of it. Easy, four steps, and done. Make a repository. Prep the hooks. Run an init. Run a sync (repeat as necessary).

About that hook. Reading the svnsync documentation and the contents of the template file, many warnings abound about the trouble that happens if a sync’d-to repository is otherwise updated; and they’re true. Consider if a user uses the back-up repository and commits a change; they get to use the next revision number. The next sync will come along and try to use the same next revision number and fail because it already exists. For that simple reason it’s worth protecting with a more robust pre-revprop-change file. That’s a little outside the scope of this document, but it’s not much harder than changing the template file to use your sync username instead of the one in the file. Here’s a trivial example that will work with our example syncUser.

#!/usr/bin
if [ "$3" == "syncUser" ] ; then exit 0 ; fi
exit 1

Note this really only limits changing properties (and therefore revision numbers) to the one user, so if you’re going to do this, make that user be a non-user, one used only for the back-up.

Anyone using Eclipse has undoubtedly run into Mylyn once or twice, probably by accident. There’s a goofy icon on a number of views that looks like three balls, one in front of the other, and if you bonk it the whole view presents different information than it did before. Especially if done by accident, it can be frustrating and difficult to revert; some of us taking the “when in doubt, restart” mindset brought about by one of our common operating system, and restart the IDE to get the view back to what we expect.

That icon is the gateway to a powerful tool that, like so many others, once understood can provide incredible utility. Before digesting a flow of work that includes using that button, here’s a bit about what Mylyn is.

What is Mylyn?

Mylyn is an Eclipse plug-in, usually included by default in a lot of their packages but available for later installation if necessary; it’s certainly in the Java and JavaEE packages (I would guess these are the ones most of us use). It’s got its own documentation and propaganda site hosted at Eclipse (http://www.eclipse.org/mylyn/), so I’ll try to avoid repeating more than is necessary, instead hoping to shine a little light on the process, inviting you to work it into your own project and application lifecycle management.

Mylyn is a “task-focused interface,” which makes it really useful if you embrace and use Eclipse’s tools for task management. When most of us develop software, we tend to think in terms of projects, work-spaces, or even file system structures. Our software is organized into groups that make sense on some level, and those groups are made of smaller groups. Because of this, far too often we think of our software as a project-based product. As we’re assigned tasks to work on, though, those tasks often break those boundaries. More often it breaks it into a subset of our work-space.

Consider a typical client-server application. There’s probably a workspace (or few) with a project for the server software and one for the client software. There may be a separate project containing common classes developed for use on both sides. There may be additional server-side projects, especially if implementing a SAAS-style project. There may even further be additional sub-projects with an intent on layering or isolating specific implementations, perhaps for the purpose of swapping out for specific environments. When we have such a structure of projects in our Eclipse workspace, there’s going to be a set of top-level projects, each with their sources, libraries, and resource folders.

Consider now a typical list of tasks for such a project. Tasks to create a log-in interface, report log-in failures, provide log-in auditing. Tasks to provide lists of data, allow user sorting or filtering of the data, and even adding, editing, and deleting the data. Where these tasks overlap the projects can be difficult to see initially, but as we’ve all done this, we know there are classes and resources added and affected throughout our work-spaces, across source-tree boundaries, and across projects.

Mylyn doesn’t remove any of this, but as we learned by accidentally hitting that button, it does help streamline the views. Further, it helps when we do that inevitable bouncing back and forth between tasks. Let’s jump in and imagine managing a little bit of development with the help of Mylyn.

Task List

The “Task List” view is the central point for finding, creating, and focusing tasks. It’s really fundamental to making Mylyn make sense, and if you’re not integrating task tracking into Eclipse, much of the usefulness of Mylyn is lost. Out of the box, Mylyn has connectors for Bugzilla, Jira, the built-in Eclipse task list and more! Some of them are added to Eclipse by default, some are just available in the list of plug-ins, and some can be added as third-party add-ons.

The easiest way to get started with your task tracking software is to open the “Task Repositories” view in Eclipse, click on the “Add Task Repository” button (or right-click the middle of the view and add it that way), and in the dialog-box that pops-up, click the “Install more connectors” button. For the most part, once you add the connector, providing whatever URIs, paths, credentials, and whatnot that are required, you should find that your “Task List” view is populated with tasks for you to work on.

Really the installation of a repository and task tracking system is outside of the scope of this document, so let’s just start out using the local task list in Eclipse. This is fine for single machine use, but, of course, doesn’t synchronize by default with anything that allows multiple developers to participate. To play along, you can simply add a task using the “Task List” view; click the “New task” button or right-click and select “New task” from the context menu, choose the “Local” repository, and you’ll be rewarded with a new task window. You can add a title and details if you like, but let’s focus for a moment on the Mylyn bits here.

Looking at the task in the source editor area (that’s where they appear), there are only two Mylyn interactions visible for the Local repository. The first is near the title of the task (once saved); the little purple dot will allow you to activate the task. Once activated, Mylyn (by default) will start keeping track of the work done related to this task. Any files opened in the IDE will become part of this collection, which they call a “context.” In more advanced repositories, and when so selected in the preferences, this will also track the time that the task is active, including noting breaks in editing activity, to help with your time tracking. At the bottom of the task editor window are two tabs, named Private and Context. Clicking the Context tab will show the list of affected files (which should be empty when the task is started).

If you activate a task, you should notice a few things happen. If you still have the task open in the editor, it’s purple dot will appear to be on a depressed button to help identify it as the active task. Likewise, there should be a purple dot next to the task in the “Task List” view. Finally, any navigator windows will also have that annoying three-ball button depressed, and all of the projects and source files will have disappeared; more correctly, the navigator windows will show all of the files that exist in the context.

You can activate and deactivate the tasks easily by clicking the purple ball either on the task editor, or more concisely in the “Task List” view. I recommend keeping the “Task List” open (hide it with a “fast view” so it becomes an icon if you want the real estate back) to allow fast switching between tasks. More on that in a second.

Let’s look at filling the context, now that we’ve got a task set up.

Filling the Context

The various navigation views, such as the “Project Explorer,” “Package Manager,” and the raw “Navigator” are strong users of the Mylyn context. (Note for the purposes of this document, I refer to all of them as “navigation” or “navigator” views, allowing you to choose your favorite or one appropriate for the situation in which you find yourself.) You can toggle the context filter on the views without affecting the context tracking help Mylyn provides. This allows you to work as you always have, but still take limited advantage of the Mylyn task-focused interface. Since we’re trying to embrace Mylyn, let’s shift how we work a little bit.

Activate that sample task. If you’re not playing with an existing work-space, create a project to play with (or create one anyway if you want to minimize risk to other projects). I simply created a new Java project, and named it Foo. Eclipse did what it always did and created the project files and folders in my work-space, but since I have a task activated, I didn’t see anything happen. The workspace itself isn’t yet part of the context. I can see my new project by turning off the Mylyn context to verify that it’s there.

My pretend task (and more importantly my empty project) requires me to add a class (or something). If you use the context menus to create classes, you’ll note right away that the folders are missing, so it would seem hard to do so; deactivate the context view, browse to the place you want to make your class and create it. Alternatively, leave the context view activated and use the File menu or context menu on the blank navigator view and get through the “new” menus and dialogs to create a class. Again, I named mine Foo, and in bad form just put it in the root (default package) of my Foo/src folder. Activating the context filter, and the context should contain only my Foo.java, and the navigation viewer tree necessary to display it. If I close the source editor, the file remains in the view, with or without the context turned on. If we return to our task, perhaps by double-clicking it in the “Task List” view, we can check out that once empty context tab, and we should see the same tree view displayed therein.

In a more complete project, we can see that this could be handy in streamlining our navigator views by streamlining the trees to only show the files related to our task. If a file isn’t visible, we can find it using one of the many Eclipse tools such as the “Open Type” (ctrl+shift+T) or “Open Resource” (ctrl+shift+R) dialogs, clicking on a type in our source and hitting F3 or Ctrl+G to jump to its declaration, or even by toggling the context view filter button and navigating to the class and double-clicking to open it in the editor. When the context filter is on, we’ll only see the items opened while the task is active.

Further, the context only contains members visited while the task was active. This helps reduce the context to just the methods and members that were worked on (or reviewed) during the session, helping to further streamline the views. This will aid in removing much of the background noise that occurs as we work on more complete projects, defending our time by filtering out methods in our classes that aren’t related to our task…keeping us focused on the task at hand and the things it affects.

It will happen sometimes that an element isn’t wanted in the context. Perhaps it was opened by mistake, perhaps it was only opened for a quick review but isn’t part of the work being done. Right-clicking a file in the navigator view will allow you to remove it from the context. Be forewarned that doing so will close its editor window. It does not undo any changes made, but does remove it from the context for tracking purposes. Removing higher parts of the navigator trees will prune all the items from the context that are beneath it, too, so you can quickly clean contexts before you’re done working.

Switching active tasks in the Task List switches the context and information in the other views. This is the next best part of Mylyn to the streamlined views.

Switching Tasks

If your project is like most of the projects I work on, it’s seldom the case that you strictly work on only one thing at a time. Well, you probably work on one thing at a time, but switch rapidly back and forth. In many agile disciplines, it’s not uncommon for the start of work on one task to spawn several others. In a “getting things done” mindset, there are two kinds of work; things you can do right now without interrupting what you’re working on, and what you make note of to do later. This can be seen often in software as the simple task of “create log-in” can immediately be seen as needing separate tasks such as generating a web page or other UI, making a message to a service, handling the service request and forming a response, handling the response, and handling errors… Working strictly in a GTD or agile approach, the developer who picked the “create log-in” task should be creating those other tasks as they are recognized.

If you have only the one task discussed so far, create a second task. When done, activate it instead of the first. A few things you may notice should include that the navigator view is again empty, automatically turning on the context filter and removing all of our previous files (not to worry; they’re still not gone). In the “Task List” view, our one active task has the heavy purple ball highlighted, but our previously active task has a dim purple ball. This indicates that the other task has items in its context associated with it. If we reactivate the other task, our editor and navigators should return as we had them when we highlighted the other task. The new task has no dim purple ball as we hadn’t opened anything (if you did as I just described), and its context is empty.

So, this brings to light the bigger usefulness of Mylyn. Switching tasks helps keep the views focused on the items associated with those tasks. As you work on both the client call to the server and the server handling of that call, switching back and forth between those tasks allows maintaining comprehensive lists of software only associated with those tasks. Those lists may overlap, for example in a common classes project used by both our client and server, but the client task would mostly have client code in its context, and the server code would likewise have its code but not the client code in its context.

Further, when using the more advanced task repositories that support it, the time spent on each task will be correctly recorded. Perhaps it takes all day to write the client-server query and response, but the two tasks could be unevenly divided in the day, and this can help track the six hours for one and the two hours for the other separately. Additionally, if you’re interrupted with a meeting, either deactivating the active task or going idle will stop the timer, and the interruption won’t make the task seem disproportionately time-consuming.

Time-tracking is turned off by default, but is easy to add. In the Window menu, select Preferences. Then find Tasks in the list. Near the bottom of the right pane is “Time Tracking.” Turn on the “Track time” check box, and time tracking will start when tasks are activated and the time will be added to task lists that support it. In our simple use of the Local repository, there will be a simple “active time spent” bit at the bottom of the task editor windows.

Task Updates

Note this time is for the entire task, not any specific activity on it, so if you’re looking to track parts of a task more accurately, you need to use a task repository that allows incremental updates such as comments and post comments as bits are done, so you can see the differences in time for each bit. Task repositories like Bugzilla or Jira both support this.

While our simple Local task tracker will keep a list of the files affected, the more advanced trackers do much more than that. For example, using Bugzilla allows uploading the context as a zipped attachment, containing the Java files and resources in the context. This allows gathering files for code reviews or a kind of version control to be directly associated with the task tracking. Some tools that integrate with both task tracking and version control will use Mylyn to help coordinate the context through other means as well.

When completing tasks, the “Task List” view allows filtering them out. Test this by opening one of our simple tasks, clicking the complete button and saving it. It should appear dimmed and crossed-off. Then click the crossed-out check mark button on the tool bar and our dimmed task disappears from the view. Toggle the button and it returns. The task and its context can be recalled at any time, to refresh your memory on why it was created and what work was associated with it.

Conclusion

To take all of this in a wrapped-up day-to-day example, we’ll assume a task tracking system is in place and incorporated in the Eclipse “Task List” and that a project full of source already exists. Done with the previous task, a skim through the task list will help pick the next thing to do. Many heretofore unmentioned features of the task list include ordering by expected due date, and filtering by assigned developer if the tracking tool allows it.

Selecting a task, the developer activates it. Depending on the tracking system, this should include a submission back to the repository so that the task will be noted as in progress and another developer won’t select it. Once active, the IDE should present a clear, streamlined work-space. In accordance with the requirements of the task, the developer opens and creates new classes. Occasionally more work than can be easily done may be noted, so the developer pauses and adds new tasks and subtasks. Perhaps correlating work is found to be necessary and appropriately other tasks are activated and noted as in progress, like the first one.

As work is completed, in part or in whole, the developer marks progress on the active task, submitting comments and contexts, optionally with time updates, to the task repository as well as version control system. Switching tasks switches views, helping focus the work to what is important to that task.

As tasks become complete, they are marked as done in the task repository, with their final context and time updates committed. As the set of tasks diminishes, the developer winds down this set of work. Eventually the last task is marked as complete and all of the code is committed.

A deep breath and sigh of relief, and the developer returns to the task list to find the next thing to do…

First we create a class that has a dependency on the spring context.  The magic here is a combination of implementing ApplicationContextAware and defining the ApplicatonContext object as static.

package com.objectpartners.util;

import org.springframework.beans.BeansException;
import org.springframework.context.ApplicationContext;
import org.springframework.context.ApplicationContextAware;

public class SpringContext implements ApplicationContextAware {
  private static ApplicationContext context;

  public void setApplicationContext(ApplicationContext context) throws BeansException {
    this.context = context;
  }
  public static ApplicationContext getApplicationContext() {
    return context;

  }
}

Next,  we wire SpringContext into our spring container by defining it in our application-context.xml:

<bean id="springContext" class="com.objectpartners.util.SpringContext />

Now,  anywhere we need access to the spring context we can import SpringContext and call the getApplicationContext method like so:

import com.objectpartners.util.SpringContext;
class LegacyCode {
.
.

  SpringBean bean = (SpringBean)SpringContext.getApplicationContext.getBean("springBean");
.
.
}

Keep in mind that if there are multiple spring containers running on the JVM the static ApplicationContext object will be overwritten by the last container loaded so this approach may not work for you.

Let’s take a really simple and dumb annotated Entity object.

@Entity
@Table(name="pojo")
public class POJO {

    @Id
    @GeneratedValue(strategy=GenerationType.IDENTITY)
    public Long id;

    @Column
    public String something;
}

When used, we would expect the database to populate our id column when we saved the object for the first time. Simple, easy.

Let’s make a simple DAO definition to save such an object.

public interface POJODAO {
    public POJO saveOrUpdate(final POJO pojo);
}

We’ll leave the implementation of this up to the specific application, but now we know we have a way to save (or update) our POJO. Let’s make a trivial class that will do exactly this.

public class POJOWork {

    public POJODAO pojoDao = null;

    public void makeAndSavePOJO() {
        final POJO pojo = new POJO();
        pojo.something = Long.toHexString(System.currentTimeMillis());
        pojoDao.saveOrUpdate(pojo);
        if (pojo.id == null) {
            throw new RuntimeException("POJO Save Failed!");
        }
    }
}

Here we’ve got a pretty useless method that creates and saves one of our objects, assigning some goofy data to its member. Of course, in your code, this would be more useful. After the save is complete, the ID field is used. Here, for a trivial and probably very undesireable validation, the ID field is checked for null, which it shouldn’t be after a successful save, and will throw an Exception if the field is null. Again, of course, in your code something more useful would be done.

In good test-driven (or test-defended) development, we want to have a test that verifies our method does what we expect it to. There are a few obstacles in our method that we run into when we’re writing our test, the least of which is that the object we need to mock is local to the member.

Here’s a quick method that works around this, ensures that the DB interaction is mocked, and passes our simple method without hitting that Exception.

import static org.easymock.EasyMock.*;
import static org.junit.Assert.assertNotNull;

import org.easymock.IAnswer;
import org.junit.Test;

public class POJOWorkTest {
    @Test
    public void makeAndSavePOJOSuccess(){
        final POJOWork pojoWork = new POJOWork();
        pojoWork.pojoDao = createMock(POJODAO.class);

        expect(pojoWork.pojoDao.saveOrUpdate(isA(POJO.class))).andAnswer(new IAnswer() {
            @Override
            public POJO answer() throws Throwable {
                final POJO pojo = (POJO)getCurrentArguments()[0];
                assertNotNull(pojo.something);
                pojo.id = 0l;
                return pojo;
            }
        });

        replay(pojoWork.pojoDao);
        pojoWork.makeAndSavePOJO();
        verify(pojoWork.pojoDao);
    }
}

Digesting the test bit by bit, we start out making our object. We then assign its DAO to a mock implementation.

We know that we’re going to call the method, so we set up an expectation. Since we don’t have either an equals() method or other means by which to compare the object passed to our expectation, we simply accept one of its kind with the isA() EasyMock matcher. If EasyMock accepts our match (which it will), it then invokes our IAnswer, calling the answer() method.

In our answer() method, we grab the parameter (which we know from the matcher will be the right type and exist). We can do some validation here that helps us overcome other lack of access to the object; in our case, we just confirm that our POJO.somethign has a value.

Happy that our object is prepared for the DB, we play its part and assign the id field a value. Since our test simply makes sure it’s not null, we just give it a number. Should we have needed to, we could have put more thought into this, of course. Then, because our interface says we return our POJO, we do so from our answer() method.

With our peparation complete, the test tells EasyMock to start waiting for calls, we call the method, it runs, calling our prepared EasyMock method and running as if it were in a real execution flow, and finally we validate with EasyMock that our expectations were met. Running this test gives us total green-bar happiness.

Sure, that’s the easy one; a method with a return value. What happens if we don’t return anything, or what is returned has nothing to do with our object? Let’s change our interface a little to just save and not return our object.

public interface POJODAO {
    public void saveOrUpdate(final POJO pojo);
}

With that little change, our POJOWork code is still valid, as it was not making use of the returned value, but we can no longer use the easy expect().andAnswer() or expect().andReturn() EasyMock methods.

import static org.easymock.EasyMock.*;
import static org.junit.Assert.assertNotNull;

import org.easymock.IArgumentMatcher;
import org.junit.Test;

class POJOMatcher implements IArgumentMatcher {
    @Override
    public void appendTo(StringBuffer arg0) {
    }

    @Override
    public boolean matches(Object arg0) {
        final POJO pojo = (POJO) arg0;
        assertNotNull(pojo.something);
        pojo.id = 0l;
        return true;
    }
}

public class POJOWorkTest {
    private POJO isPOJO() {
        reportMatcher(new POJOMatcher());
        return new POJO();
    }

    @Test
    public void makeAndSavePOJOSuccess() {
        final POJOWork pojoWork = new POJOWork();
        pojoWork.pojoDao = createMock(POJODAO.class);

        pojoWork.pojoDao.saveOrUpdate(isPOJO());
        expectLastCall();

        replay(pojoWork.pojoDao);
        pojoWork.makeAndSavePOJO();
        verify(pojoWork.pojoDao);
    }
}

That’s a bit more work, and it’s not nearly as elegant or flexible. Let’s go over this bit-by-bit, too.

The new class, POJOMatcher, makes use of the EasyMock.IArgumentMatcher interface to allow EasyMock to send an object for comparison. The matches() method will be used to determine if that’s the right deal after all. Since we’ve really got nothing to compare to, we do our validation in the matches() method just like in the answer() method before, and when it passes we set the id. The argument passed to the matcher is the one created in our test method, so it will have an id when the method continues from the mocked save attempt.

Our test class has a new isPOJO() method, which kind of binds the IArgumentMatcher to our POJO type. While we do have to return an instance of our class, unless we want to use it to validate the information in the POJOMatcher.matches() method, it can be empty (as it is). had we wanted to, we could have made the isPOJO() more intelligent, perhaps taking a POJO as a parameter for comparison, and returning that after setting up the ReportMatcher.

In our test method, we changed the preparation a little bit. Since the method doesn’t return a value any more, we can’t pass it to EasyMock.expect(), and then can’t use the expect().andAnswer() or expect().andReturn() methods, which is how we got wrapped up in ReportMatcher and IArgumentMatcher anyway. “Calling” the method and then telling EasyMock we expect the last call using the expectLastCall() will satisfy the replay and verify and let the mock do its job.

When the call is run in the middle, our matcher will be called, comparing, ignoring our isPOJO()-provided POJO, and verifying the POJO actually passed in our implementation in the POJOMatcher.matches() method, and successfully setting the id.

Now, in both cases, we can validate the information contained in a local object when passing through a mocked method, and can also meet our initial goal of affecting the passed object as the real object is expected to have affected it.

Jay comes to OPI with 8 years of experience building distributed and scalable JEE applications. His main focus has been providing solutions using open-source frameworks, such as Spring and Hibernate. Jay’s work experience includes retail, asset management, manufacturing and the pharmaceutical industries. He has a passion for new technologies, and most recently is looking to build efficient Google App Engine solutions.

His addition solidifies OPI’s strategy towards employing the top talent within the local IT/software community. We’re excited to have him as part of the OPI team!

Liferay Portal and OpenSSO both require a minimum 1.5 JVM, but I would recommend using Java 6 (as Java 1.5 reached its End of Service Life in October, 2009). Make sure that your JAVA_HOME environment variable is correctly set to point to your Java 6 installation.

For OpenSSO to work correctly with Liferay Portal, both servers need to be running in the same domain.  To solve this issue while running both servers on a single machine, edit the hosts file (/etc/hosts or %SystemRoot%\system32\drivers\etc\) and add/update your localhost entry:
127.0.0.1 localhost localhost.example.com
where example.com is your actual domain.

Install Liferay Portal
Liferay Portal is an open source portal. Liferay comes in two editions, Enterprise Edition (EE) and Community Edition (CE).
For a full discussion on the differences, see this. Downloads are available here. For this article, I used Liferay Portal 5.2.3 CE bundled with Tomcat 6.0 (6.0.18).

Installation consisted of:

1. Unzip liferay-portal-tomcat-6.0-5.2.3.zip to a directory. This will create a liferay-portal-5.2.3 folder.
   • On Linux/MacOS, you will need to add execute permissions to all of the shell scripts in the bin directory: chmod +x *.sh
2. In liferay-portal-5.2.3/tomcat-6.0.18/bin/, executing startup.sh (or startup.bat) will start Tomcat, and deploy Liferay Portal.
3. Open a browser to http://localhost.example.com:8080, and you will see the Liferay login page. You can login with test@liferay.com/test.

Install OpenSSO/OpenAM
OpenSSO is an open source access management and federation server platform. Announced by Sun Microsystems in July 2005, OpenSSO was based on Sun Java System Access Manager, and was the core of Sun’s commercial access management and federation product, OpenSSO Enterprise (formerly Sun Access Manager and Sun Federation Manager). Oracle completed their acquisition of Sun Microsystems in February 2010 and announced that OpenSSO would no longer be their strategic product. OpenSSO will continue to be developed and supported by ForgeRock under the name of OpenAM (see this).

I downloaded the latest OpenAM build (OpenAM Snapshot 9.5.1 RC1) from here. For consistency, I will refer to OpenSSO as OpenAM for the remainder of this article.

As OpenAM also requires a servlet container, I downloaded the latest Tomcat (6.0.29) from here.
Installation of the Tomcat server consisted of:

1. Unzip apache-tomcat-6.0.29 zip file. This will create an apache-tomcat-6.0.29 folder.
2. As both Liferay Portal and OpenAM will be running on the same machine, I needed to update the ports that the OpenAM Tomcat server was using.
   • Edit apache-tomcat-6.0.29/conf/server.xml. I changed all of the ports from 8xxx to 9xxx. For example, 8080 to 9080, 8443 to 9443, etc.
   • On Linux/MacOS, you will need to add execute permissions to all of the shell scripts in the bin directory: chmod +x *.sh
3. Edit catalina.sh (or catalina.bat) and add the following line to the start of the file, after the comment block listing the various Environment Variable Prequisites:
   Linux/MacOS: JAVA_OPTS="$JAVA_OPTS -Xmx1024m -XX:MaxPermSize=256m"
   Windows: set JAVA_OPTS="%JAVA_OPTS% -Xmx1024m -XX:MaxPermSize=256m"

Installation of OpenAM consisted of:

1. Unzip openam_snapshot_951RC1.zip to a directory. This will create an opensso folder.
2. Copy the opensso.war from opensso/deployable-war/ to apache-tomcat-6.0.29/webapps/.
3. In apache-tomcat-6.0.29/bin/, execute startup.sh (or startup.bat) to start Tomcat and deploy OpenAM.
   • After Tomcat has deployed OpenAM, you will see the exploded war file as apache-tomcat-6.0.29/webapps/opensso.
4. Open a browser to http://localhost.example.com:9080/opensso, which should redirect you to http://localhost.example.com:9080/opensso/config/options.htm,
   to complete the OpenAM configuration.
5. You should see the OpenAM configuration options page. Under Custom Configuration click Create New Configuration. Enter the following:
   • Default User Password — password
   • Server Settings — default entries are ok
   • Configuration Data Store Settings — select First Instance, select OpenAM as Configuration Data Store, leave other entries
   • User Data Store Settings — select OpenAM User Data Store
   • Site Configuration — select No
   • Default Policy Agent User — policy01
   • Configurator Summary Details – click Create Configuration. This will create the configuration for your OpenAM server under ~/opensso (or c:\Documents and Settings\{username}\opensso).
6. When this completes, in the Configuration Complete dialog, click Proceed to Login, which should now redirect you to http://localhost.example.com:9080/opensso/UI/Login.
   Type amAdmin as the username, password as the password, and click Log In. You should now see the OpenAM Console.
   • For detailed information about the OpenAM Console, see this and this. A detailed discussion of all of the functionality of OpenAM is beyond the scope
     of this article.
7. You can now delete the opensso.war file from apache-tomcat-6.0.29/webapps/ directory.

Additional OpenAM Configuration
To get OpenAM to work correctly with Liferay, you need to set Encode Cookie Value to Yes. This will prevent infinite redirection between Liferay and OpenAM on login.

1. In the OpenAM Console, select the Configuration tab.
2. Select the Servers and Sites tab.
3. Click Default Server Settings.
4. Select the Security tab.
5. In the Cookie section, select the Yes checkbox beside Encode Cookie Value.
6. Click Save.

Other people have reported having to set the com.iplanet.am.cookie.c66Encode property to true as well, to resolve the infinite redirection problem:

1. In the OpenAM Console, select the Configuration tab.
2. Select the Servers and Sites tab.
3. Click Default Server Settings.
4. Select the Advanced tab.
5. Find the com.iplanet.am.cookie.c66Encode property, and set the value to true.
6. Click Save.

Before updating Liferay to use OpenAM, I recommend adding the default Liferay user, test@liferay.com, to OpenAM.

1. In the OpenAM Console, select the Access Control tab.
2. Click the / (Top Level Realm) realm.
3. Select the Subjects tab.
4. Click New…
5. Setup the default Liferay user:
   • ID — joebloggs
   • First Name — Joe
   • Last Name — Bloggs
   • Full Name — Joe Bloggs
   • Password — password
   • Click OK to create the user.
6. Click Joe Bloggs to add the email address. Enter test@liferay.com for the Email Address, and click Save.

Integrate Liferay Portal with OpenAM
Now you are ready to update Liferay Portal to integrate with OpenAM for authentication.

1. If Liferay is running, shut it down (bin/shutdown).
2. Create a new file, called portal-ext.properties, in your Liferay directory, under liferay-portal-5.2.3/tomcat-6.0.18/webapps/ROOT/WEB-INF/classes/.
3. Edit this file, and add the following properties:
   open.sso.auth.enabled=true
   open.sso.login.url=\

   http://localhost.example.com:9080/opensso/UI/Login?goto=\

   http://localhost.example.com:8080/c/portal/login

   open.sso.logout.url=\

   http://localhost.example.com:9080/opensso/UI/Logout?goto=\

   http://localhost.example.com:8080/web/guest/home

   open.sso.service.url=http://localhost.example.com:9080/opensso
open.sso.screen.name.attr=uid
open.sso.email.address.attr=mail
open.sso.first.name.attr=givenname
open.sso.last.name.attr=sn

4. Start Liferay (bin/startup).
5. Once Liferay has started, open a browser to http://localhost.example.com/8080, and you should be redirected to the OpenAM login page
   (http://localhost.example.com:9080/opensso/UI/Login). Enter joebloggs for the User Name, and password for the Password. Click Log In.

You will be authenticated against OpenAM, and redirected to Liferay.

Now that Liferay is using OpenAM for authentication, if you create a new user in OpenAM, that user will also be created in Liferay on the first log in. That newly created user in Liferay will only have the basic information filled in – First Name, Last Name, Screenname, Email Address – and will have the default Roles, Groups, and Organizations assigned.

This article demonstrated a basic integration with OpenAM and Liferay Portal. Now you are ready to explore more advanced topics include configuring OpenAM to use an existing LDAP or other user datastore, creating a custom datastore plugin (e.g. JDBC) for OpenAM, setting up a separate realm for Liferay users, as well as taking advantage of OpenAM for incoming and outbound SSO in conjuction with Liferay Portal. Enjoy!

Taken straight from the Spring documentation, the following example shows a similar use to what we’d done.

@RequestMapping(value="/owners/{ownerId}", method=RequestMethod.GET)
public String findOwner(@PathVariable String ownerId, Model model) {
  Owner owner = ownerService.findOwner(ownerId);
  model.addAttribute("owner", owner);
  return "displayOwner";
}

Our code looked pretty much the same, with our names and useful bits, of course. Quickly scanning that documentation shows that our syntax was accurate. The compiler didn’t complain, and sometimes it worked. Where it got confusing is that the code would work just fine when run in an integration test using HTTPUnit (in the IDE and run by Ant) and in a Servlet engine (Tomcat, specifically) when launched from Eclipse. Some people had success when deploying to Tomcat using an Eclipse-created WAR file, but some people experienced failure. Everyone failed when using the Ant-built WAR file.

When the error occurred, the root cause of the Exception caught ultimately was the following:

java.lang.IllegalStateException: No parameter name specified for argument of type [java.lang.String], and no parameter name information found in class file either.

When you look at the code, you can see the @RequestMapping has the appropriate {variable} notation, and that the parameter list has a variable of the same name, of type String, as expected (other types can be used, but ours was a String also).

A peek at the Ant script gave a clue to the solution. Changing the javac target’s debug attribute to “on” allowed the Ant-built WAR file to also deploy and run with success. That’s when the head-slapping began.

When the code is compiled with debug, as it is when working in the IDE, and apparently is sometimes when exporting from the IDE (probably some of us have a workspace setting different than the others), the name of the parmeter is available to the JVM at runtime. When the code is compiled without debugging, as the Ant script was doing, then the parameter name is lost, truncated by the p-code generator based on its type and order and other factors.

Adding the name to the @PathVariable annotation allows the runtime to find the correct parameter even without debug information in the class file. Again, straight from the same documentation, just a couple paragraphs down from the other example shows the more correct way to declare the @PathVariable. Right above the example on their page is a discrete mention of this fact, and a recommendation that you specify the name. Below is the subtle difference in the declaration, one that makes all the difference.

@RequestMapping(value="/owners/{ownerId}", method=RequestMethod.GET)
public String findOwner(@PathVariable("ownerId") String ownerId, Model model) {
  // implementation omitted
}

While it’s convenient to have Spring work this out for you during the development cycle, it seems more appropriate that the value be required which can be achieved simply by removing the default from the annotation. Since it isn’t that way, it’s certainly a good practice to get into to always provide the name (or names) of your path variable when annotating your controllers in Spring.

A quick search of the Internet reveals thousands upon thousands of books, articles, and studies focused on becoming more efficient. Blogs on the agile methodology preach bringing speed to development and TDD strives to make the QA cycle a blip on the project timeline. Grails and Spring Roo bring projects and prototypes online in minutes rather than days. It cannot be argued that more efficient development reduces cost and makes good business sense – but are there other benefits as well?

Doing the same work in less time
As developers our days mandate carbon output – what we get in return for our expenditure is variable. As we develop we need to be conscious about making the most of our machines each minute that we are in front of them as well as time we spend away from them. An few moments of consideration can save thousands of watts of power each day. Do you stare at your console while compiling or do you execute other tasks during that time? Do you practice TDD to remove much of the overhead of manual testing? Do you hibernate or fully shut down your machine when leaving for meetings or lunch? These are all small things by themselves, but few million persons doing them everyday makes a very large difference.

Conserving bandwidth
Each bit we push and pull across the wire has a cost associated with it. As such, it is in everyone’s best interest to conserve bandwidth (unless you are in the business of selling bandwidth) at every turn. Servers will do less work, switches and firewalls breathe more easily, pages load faster, and all while using less energy and costing your client less. Here again, the work we do can have a large impact over time.

• Have we minimized and optimized CSS and JavaScript?
• Are we serving only compressed images?
• Have we done all we can to leverage client side caching?
• Is Ajax being used to reduce full page loads?

All of these things result in more speed for the user, less cost for the client, and less carbon out of the pipe.

Optimising code
Servers are like athletes – the harder they work the more energy they need to consume to keep going. World class athletes have figured out that at a certain level of performance even the smallest gains in efficiency determine victory or loss. Cyclists shave fractions of grams of weight off each component to save weight, then test in wind tunnels to reduce drag. Swimmers now wear full body suits of technologically advanced material modeled after shark skin to reduce friction in the water. They do this all to finish fractions of a second faster than they could before. Can we learn from the world’s elite athletes and reduce total clock cycles necessary to compete a task?

Here again we have a situation where everyone wins. When we fully optimize our code we will use fewer resources to complete the same set of tasks. Our code will be faster, the user experience better, client costs reduced, and less energy will be wasted. While techniques for code optimization is beyond the scope of this writing it is something that we as developers need to be conscious of and work to master.

Summary
While the methods and mechanisms that can be used to make software an integral part of sustainable computing are seemingly infinite, we can all work to implement a small, finite set of options every day and together make a huge difference. Whether we simply add break statements to for loops or implement reduced carbon data centres, we can all do something everyday to reduce the number of bits of carbon we produce.

I had put a few code samples in my presentation that I’d pulled from a recent project. Stuff I knew worked, so I wouldn’t be surprised with any hastily thrown together code with style, format, or syntax errors. One of the classes was an annotated Spring class, with some code not too much unlike this snippet:

@Autowire private SomeBean someBean;

We went down a path of queries related to how to create new ones, which is a simple @interface declaration like the following.

public @interface Foo{ }

They queried how to put them in the code, and I pointed back to the example. I also showed them some other examples related to using them on class definitions, methods, and on parameter values, as defined by the @Target annotation and ElementType enum. We looked at examples of commonly encountered annotations such as @Deprecated and @SuppressWarning among others. We even looked at the different uses of @Retention and discussed the RetentionPolicy enum; how SOURCE is used to provide hints for the compilers (and IDEs) but aren’t retained in the compiled code, how CLASS is retained in the code but not necessarily available at runtime, and how RUNTIME is certain to be available at runtime.

Then they wanted to know how to use them. Not how to implement them, but how to access the @Retention(RetentionPolicy.RUNTIME) declared annotations.

I hated to admit that I didn’t really know. I knew there weren’t any frequently used utility classes for grabbing annotations, but that there were annotation-related methods on the reflection classes. I knew in practice that they were used, but not directly how, so I set out to learn so I could completely satisfy their questions.

To be sure, I use annotations all day long. I probably @Deprecate a method every day, sometimes permanently, sometimes just to quickly find uses as Eclipse is faster at adding them to problems than it is at searching. Any class that extends or implements another is surely fraught with @Override annotations. I probably write twice as many @Test annotated methods than anything else. I have @Autowire in nearly every function-full class of a Spring application, and every Hibernate project is filled with the @Column and all the other JPA annotations.

What I hadn’t had to do, though, was write any code to find and use annotations. I can’t even recall passing an annotation to a method to try to identify them. After much digging, I ascertained that indeed there aren’t any utility classes that aid in finding or using annotations. There’s got to be some heavy work behind the classpath scanning in frameworks like Spring and Hibernate to find annotated classes and methods. I’m not quite prepared to dive into that, but let’s look at some simple cases of using annotations.

First, a simple set of annotations should be built for our various uses. Let’s take one for each kind of element: class, method, and property.

@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
public @interface TypeAnnotation { }

@Target(ElementType.FIELD) @Retention(RetentionPolicy.RUNTIME)
public @interface FieldAnnotation { }

@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME)
public @interface MethodAnnotation { }

@Target(ElementType.PARAMETER) @Retention(RetentionPolicy.RUNTIME)
public @interface ParameterAnnotation { }

There are actually eight different ElementTypes that can be used, but these are surely the most common, and are certainly enough to provide a thorough example. I’ll expand on the simple examples here, but I wanted to first discuss the annotations on our annotations.

The @Target annotation lets the compiler know where the annotation may be used. Compilers and IDEs will warn if the annotation is used on the wrong type of element. If the @Target is left off, the annotation may be applied anywhere without warning. The ElementType must be defined, and allows multiple, but not duplicate entries. Multiple ElementType allow the annotation to be used in any of those instances.

The @Retention annotation lets the compiler know how long to maintain the annotation. As mentioned, there are three RetentionPolicy values that are allowed, SOURCE, CLASS, and RUNTIME. If the @Retention annotation is used, a RetentionPolicy must be declared. If the @Retention annotation is not used, the default is CLASS, which will keep the annotation in the compiled class, but it may not be available to the runtime.

The @interface is used to define the annotation. The name of the interface is then used when putting the annotation in source later. Other than that modification to the naming, the annotation is declared much like any other interface, in that you can declare member variables and methods. It is important to note these aren’t intended for use as regular interfaces, so there are some other restrictions. Member variables must be public, static, or final, but may be of any valid type. Only public and abstract modifiers are allowed on methods. And only a small set of return types are allowed for methods; strictly, primitives, Strings, enumerations, other annotations are allowed, or 1-dimensional arrays of those types.

One more bit, if you want to make an annotation that takes a value without a name, you must declare a member variable named “value.” That is, like @SuppressWarnings(“unchecked”). It can be a single value or array, depending on your needs. If you define it as an array you can provide several values by wrapping them in squiggly-braces like @SuppressWarnings({“unchecked”,”unused”}) would do. If you do not wish to use “value,” the variable must be explicitly declared (and, truly, value is optional) such as @SuppressWarnings(value=”unchecked”).

Other differences will become apparent as the article continues, and as you play with annotations of your own. In trying to keep the article short, and not delve too much into every possible use case, I’ll show some simple uses, point out some of these other nuances of @interface definitions, and leave it to the reader to expand on that.

We’ve got some trivial annotations set up, so let’s apply them to a simple class.

@TypeAnnotation class Foo {
  @FieldAnnotation public Object object;

  @MethodAnnotation public Object setObject(@ParameterAnnotation final Object object){
    this.object = object;
  }
}

If you’ve used annotations in your code, you’ve probably used some or all of these kinds of annotations. Certainly, the annotations used before have actually done something. Before we get into doing something, let’s try to find the annotations at runtime.

I mentioned previously that Spring and Hibernate and other frameworks have functionality to scan classes in the classpath for annotations. If you’ve taken a look at how they do it (they’re both open-source projects, so dig in…) or hit a search engine looking for the answer, you probably have seen or correctly surmised that interrogating a classpath is not as easy as it seems. As such, I’m not going to try to lay that out here (sorry to whet your appetite), but instead will use the annotations in a more explicit manner.

First, a simple method to see if the annotation exists, just as an example of accessing them.

public boolean isAliased(final Class type) {
    final TypeAnnotation typeAnnotation = type.getAnnotation(TypeAnnotation.class);
    return (typeAnnotation != null);
}

The trivial example interrogates the provided class using the Class.getAnnotation() method. There’s a similar Class.getAnnotations() that will return an array (zero-length if empty) of the annotations if you want to check for more than one. This would be used very simply by something like the following snippets, the first returning true, and the other false.

isAliased(Foo.class);
isAliased("yes, a literal".getClass());

It isn’t a terribly useful example, so let’s make a method that does a little more. First, let’s expand one of our annotations to give us some runtime differences from source.

@Target(ElementType.FIELD) @Retention(RetentionPolicy.RUNTIME)
public @interface FieldAnnotation { String value(); }

Here we’ve changed our FieldAnnotation to require we provide some additional information in the form of a String property. It’s been named “value” for convenience, so we can use it without forcing the use of the name. Note that it looks like a method declaration, but we’ll be treating it as both a variable and a function.

If we applied the same annotation to the same class as before, we’d run into an error as we’re missing a required property. Let’s update our class a little and give this value some functionality.

@TypeAnnotation class Foo {
    @FieldAnnotation("here") public Object object;

    @FieldAnnotation("there") public Object other;

    @MethodAnnotation public Object setObject(@ParameterAnnotation final Object object){
      this.object = object;
    }
}

Again, the class isn’t terribly useful, but we now have two annotated member variables with different names. Let’s make a quick method to set those values by their annotation name, ignoring their object name.

void setPropertyByAnnotationName(final Object object, final String name, final Object value) {
    final Field[] fields = object.getClass().getDeclaredFields();
    for (final Field field : fields) {
        final FieldAnnotation fieldAnnotation = field.getAnnotation(FieldAnnotation.class);
        if(fieldAnnotation!=null && name.equals(fieldAnnotation.value()){
            field.set(object, value);
        }
    }
}

Lots of spots for error there, as there’s no null checking, it assumes the field is accessible, and the object is of the right type…but it matches our simple Foo class, so we’ll let it go for now. As with the Class, there is a Field.getAnnotations() in case you’d like to investigate more than one annotation. What we have is a method that interrogates our object (first one) to look for fields (member variables) annotated with our FieldAnnotation. When it finds one, it checks to see if the name matches the value (note it looks like a function here) in the annotation. When there’s a match, it sets the value as provided by our value parameter. This would be used simply as thus:

Foo foo = new Foo();
setPropertyByAnnotationName(foo, "here", "this is set!");
setPropertyByAnnotationName(foo, "there", Calendar.getInstance());

With this, we should end up with a Foo.object that contains the String “this is set!” and Foo.other that contains a Calendar with the current time in it.

One might desire to ask what good is that? We surely have access to Foo.object and Foo.other directly in this class, but it will certainly be the case that we might not have such access in other classes. Additionally, with the annotation, we don’t even really need to care that it’s a Foo object. We could very easily declare another class with similar annotated members and have their fields accessed with the same method we just created. This is roughly how Spring’s @Autowire works. They, of course, do a bit more in terms of recognizing names and types and whatnot without explicit definition, but this is the crux of it.

Accessing methods is done pretty much the same way. Let’s use the @MethodAnnotation to use the setter we’ve got. Note that calling methods is a lot trickier because the annotation itself has no way to ensure that the parameter list is correct. It is up to the method using reflection to determine if the prototype of the method is something it can work with. For brevity, I’ll leave this using the original annotation, which means every annotated method will be called and its value set to the same thing; the same modifications on the @FieldAnnotation can be done here for similar functionality.

void callMethodByAnnotation(final Object object, final Object value) {
    final Method[] methods = object.getClass().getDeclaredMethods();
    for (final Method method : methods) {
        final MethodAnnotation methodAnnotation = method.getAnnotation(MethodAnnotation.class);
        if(fieldAnnotation!=null){
            method.invoke(object, value);
        }
    }
}

Again, a slew of opportunities for errors with missing null-checks, accessibility, and the mentioned parameter list validation. Also, there is a similar Method.getAnnotations() method that will return an array of annotations in case you want to check for more than one. This method simply checks the class for all methods with the right annotation, and if found, tries to invoke the method with the provided object as the parameter. Again, with this functionality you can find methods in classes without caring about their real names. This, again with more guts, is how Spring handles its @RequestMapping methods in @Controller classes. As before, this can be implemented with this simple

Foo foo = new Foo();
callMethodByAnnotation(foo, ""this is set!");

In the end, we end up with Foo.other set to a String saying “this is set!” using the annotation instead of calling the method directly.

Trickier is handling the ElementTypePARAMETER annotations. This is because there’s no direct reflection access to the parameter list. There are a few arrays that can be gathered to help identify the parameters, but the parameters are actually only realized when you use the Method.invoke(), so to use these, you need to handle all of the parameters by annotation, name, or type. A typical use would be some form of IOC or other runtime association of parameters to other values available to the application.

Why this is tricky is that there is no opportunity, except perhaps inside an invoked method, to access the parameter annotations when calling the methods directly. With that understanding, we can see that these are best paired with annotated classes or methods, where the functions are going to be called indirectly, and therefore there is time to interrogate the Method for annotations before calling Method.invoke. That said, let’s modify our other method-calling method to take a map of values to tie to our parameters.

Before we do, though, this brings about another sticky bit. Unlike classes, member variables, and methods, parameters don’t always keep their names. When classes are compiled, the parameters are reduced essentially to a type and order. The variable name associated with it is not kept with the method unless the class is compiled with debugging symbols. As such, like we did for the fields, we’ll add a required value to represent the name of the parameter. This way, the annotation will maintain the value that we’ll use to pull values from our map, and it won’t matter if debug is enabled or not; our annotation will continue to work.

@Target(ElementType.PARAMETER) @Retention(RetentionPolicy.RUNTIME)
public @interface ParameterAnnotation { String value(); }

And since it’s required with no default, we’ll have to change our class appropriately.

@TypeAnnotation class Foo {
    @FieldAnnotation("here") public Object object;

    @FieldAnnotation("there") public Object other;

    @MethodAnnotation public Object setObject(@ParameterAnnotation("inside") final Object object){
        this.object = object;
    }
}

And we’ll modify the method to take advantage of that annotation.

public void callMethodByAnnotation(final Object object, final Map map) {
    final Method[] methods = object.getClass().getDeclaredMethods();
    for (final Method method : methods) {
        final MethodAnnotation methodAnnotation = method.getAnnotation(MethodAnnotation.class);
        if (methodAnnotation != null) {

            final Annotation[][] parameterAnnotations = method.getParameterAnnotations();
            final Object[] parameters = new Object[parameterAnnotations.length];
            for (int i = 0; i < parameterAnnotations.length; i++) {
                parameters[i] = null;

                final Annotation[] annotations = parameterAnnotations[i];
                for (final Annotation annotation : annotations) {
                    if (annotation instanceof ParameterAnnotation) {
                        parameters[i] = map.get(((ParameterAnnotation) annotation).value());
                    }
                }
            }
            method.invoke(object, parameters);
        }
    }
}

Note the busy work necessary to grab the annotation. The annotations come from an array of arrays. The first dimension is one for each parameter, and the second dimension is the array of annotations for the parameter at that first dimension. If there are no parameters, the first dimension array is zero-length. For each parameter, if there are no annotations, that second dimension array is zero length. There is a related Method.getParameterTypes() that could be used to be certain that the type in the map was compatible with the type in the parameter, but ours is an Object, so we can be a little sloppy.

The new method can be used very much like the other, except we'll pass the parameters in a Map. We could, of course, use any mechanism for keeping track of the things that could be put in the parameter list. If you've used Spring to annotate a @Controller with @RequestMethod methods, you'll notice that you can just toss in a whole slew of parameters such as ModelMap or HttpServletRequest and it will figure them out by type.

Map map = new Map();
map.put("inside", "this is set!");
Foo foo = new Foo();
callMethodByAnnotation(foo,map);

Same caveats as before regarding shortcuts taken for brevity... Now when we call our method, it will check our map for the value. If it doesn't find an element in the map that matches our annotation name, it puts null in the parameter list. As before, our Foo.other will have a String with the value "this is set!" when we're done.

That seems like a lot of busy work to make sense of annotations. Really it's a lot of fluff code around it to make it understandable. Really, the magic lies in the getAnnotations() or getAnnotation() methods on the Class and the reflection classes Field and Method, and the Method.getParameterAnnotations() method. And, of course, our trivial examples don't carry much insight into any kind of usefulness, so let's expand on this and make a one-class annotated XML parser. A very simple one, mind you.

Parsing XML is a pain that way too many of us go through. There are plenty of tools to help us do this, so this isn't intended as a replacement or any kind of competition for them. It's just familiar territory, and one I think I can squeak in a small pair of classes for a solid example of annotation use.

Consider this fairly trivial XML, where we have a Foo element with a single attribute, id, and a nested element also named Foo.

<Foo id="alpha">
    <Foo/>
</Foo>

The astute among us can quickly envision a likewise trivial POJO that would do the same. I'm making public members for brevity; for real, we'd use getters and setters, right?

class Foo {
    public String id;
    public Foo foo;
}

With this class in mind, we can see we'll need a couple annotations to handle identifying the class and our members.

@Target({ElementType.TYPE, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME)
@interface XMLElement { String value() default ""; }

@Target(ElementType.FIELD) @Retention(RetentionPolicy.RUNTIME)
@interface XMLAttibute { String value() default ""; }

A quick word about the two noticeable differences from the previous examples. First, we'll note that the XMLElement has been annotated with two ElementType targets. This allows the same attribute to be used to identify types and members, as XML elements are often neatly identified with POJOs. Also, I've added a default to each. This is both to show what it looks like and allow us to optionally rename the item in question. A small annoyance with the defaults is that there is no null value. When the value is an array, you can declare an empty list as the default, but that's not really null either.

@interface ArrayExampleAnnotation { String[] value() default {}; }

This allows us to alter our class to add the annotations as follows:

@XMLElement class Foo {
    @XMLAttribute public String id;
    @XMLElement public Foo foo;
}

We could be more explicit and annotate it thusly:

@XMLElement("Foo") class Foo {
    @XMLAttribute("id") public String id;
    @XMLElement("Foo") public Foo foo;
}

Or even make the POJO and XML a little less tightly coupled by changing the POJO names from the expected XML names (this is where the value makes more sense!):

@XMLElement("Foo") class FiddleStix {
    @XMLAttribute("id") public String identifyingAttribute;
    @XMLElement("Foo") public FiddleStix next;
}

Now we just need a function to digest our XML string and populate our POJO. To be short and sweet, and not emphasize the XML processing too much, I'm just going to use the typical W3C DOM classes that come with the Java runtime. Easy, short-ish.

public static  POJO turnXMLStringIntoPOJO(final String string, final Class type) {
    final POJO pojo = type.newInstance();
    final XMLElement topXmlElement = type.getAnnotation(XMLElement.class);
    final Document document = DocumentBuilderFactory.newInstance().newDocumentBuilder()
            .parse(new ByteArrayInputStream(string.getBytes()));
    if (document.getNodeName().equals(topXmlElement.value())) {
        final NamedNodeMap namedNodeMap = document.getAttributes();
        for (int i = 0; i < namedNodeMap.getLength(); i++) {
            final Node node = namedNodeMap.item(i);
            String name = node.getNodeName();
            final Field[] fields = type.getDeclaredFields();
            for (final Field field : fields) {
                final XMLAttribute xmlAttribute = field.getAnnotation(XMLAttribute.class);
                if (xmlAttribute != null) {
                    if (("".equals(xmlAttribute.value()) && field.getName().equals(name))
                            || xmlAttribute.value().equals(name)) {
                        field.set(pojo, node.getNodeValue());
                    }
                }
            }
        }
        final NodeList nodeList = document.getChildNodes();
        for (int i = 0; i < nodeList.getLength(); i++) {
            final Node node = nodeList.item(i);
            final String name = node.getNodeName();
            final Field[] fields = type.getDeclaredFields();
            for (final Field field : fields) {
                final XMLElement xmlElement = field.getAnnotation(XMLElement.class);
                if (xmlElement != null) {
                    if (("".equals(xmlElement.value()) && field.getName().equals(name))
                            || xmlElement.value().equals(name)) {
                        final Object object = field.getType().newInstance();
                        field.set(pojo, object);
                    }
                }
            }
        }
    }

    return pojo;
}

With a little recursion or other care, this simple method could be used to handle nesting our XML so that Foo could have Foo wtih Foo containing Foo... But for our purposes, this meets our needs. Again, much with the caveats of missing care exchanged for brevity. Notice it's a generic class, giving us flexibility to just send it any old class. With our caveats, it makes assumptions that the class is annotated (or null pointer exceptions will occur). The string is quickly (since it's small) into a DOM tree, and we make two passes through it, once for the attributes and once for the elements. We compare the names of the nodes to the names (value) of our annotations, if they're defined, or to the name of the field, if the value is empty. If a match is found for the annotation, we set the value to whatever the XML contained. If a match is contained for the element, we simply instantiate the right type and add it to our object. We could explore the DOM deeper and set its values, but that's a little larger example.

This class could take all three of our example classes (careful, as two of the classes will conflict) and parse the same XML and get the expected results.

String xmlString = "<Foo id=\"alpha\"><Foo /></Foo>";
Foo foo = turnXMLStringIntoPOJO(xmlString, Foo.class);
FiddleStix fiddleStix = turnXMLStringIntoPOJO(xmlString, FiddleStix.class);

What should result is that our objects would have an id String of "alpha" and their same-type member populated with an empty, but instantiated item. Both classes, from the same XML just because of the annotations.

And that, my friends, is how you use annotations. Well, one way...

1. Package your application as a jar file
2. Create an icon for your application
3. Create an application bundle

Some applications referenced below may not be installed on your Mac by default. If not, you can either install them from your distribution or download them.

I assume you already know how to do step one so we’ll move on to step two.

Find an icon you like for your application. A little Googling will produce a variety of free icons. The png file format will work for you. Be sure to follow any licensing restrictions that apply to your icon and do the following:

1. Download the png file.
2. Open the Icon Composer application (its in /Developer/Applications/Utilities).
3. Drag the png file into the largest box in the icon composer.
4. From the largest box drag it to the next largest then the next and so on to create various size icons. Be sure to go from larger to smaller for the best results.
5. Choose File->Save in the Icon Composer and save your new icns file.

Finally, build your application bundle:

1. Open the Jar Bundler (its in /Developer/Applications/Utilities).
2. Select the Classpath and Files tab and add your jar file to the classpath.
3. Select the Build Information tab.
4. Click Choose next to the Main Class drop down, select your application’s jar file again.
5. Select the entry point for you application from the Main Class drop down.
6. Select your JVM Version from the drop down
7. Click Choose Icon and select the icns file you created above.
8. Click Create Application, enter a name for your bundle, and click Create

Now you have an application bundle file you can just drop in your /Applications directory to install.