If you’re an impatient kind, here’s the source code.

I created the project  in Eclipse, instructions here.

Now, let’s start off with a “repository customizer” which is Nexus extension point we’ll use to insert a custom request processor into every repository…

public class GaTrackerRepositoryCustomizer implements RepositoryCustomizer {

    private final Logger log = LoggerFactory.getLogger(getClass());

    @Inject
    @Named("gaTracker")
    private RequestProcessor gaTracker;

    @Override
    public void configureRepository(Repository rep) throws ConfigurationException {
        log.debug("Attaching tracker to: " + rep.getName());
        rep.getRequestProcessors().put("gaTracker", gaTracker);
    }

    @Override
    public boolean isHandledRepository(Repository rep) {
        boolean b = true;
        log.info("Handles repository '" + rep.getName() + "': " + b);
        return b;
    }
}

Not too complicated. We’re using injection to get hold of the actual tracker components and we’re inserting it into all repostories.

Wait, all repositories? Yes, and it’s problem I haven’t really figured out yet. Ideally I’d like to track “hosted” repositories only. However, we’ve configured all our builds to use a few common development “groups” for convenience. However, Nexus seems to treat groups as first class members, so even though an artifact may be deployed in a hosted repository while accessed through a group, the request processor will not get notified for the hosted repository, only the group. I tend to see “groups” as equivalent to “views” in which case I’d expect the hosted repository to be called as well, but, no…

Now, let’s create a request processor which will react when someone “reads” a path in a repository.  We’ll take it in pieces…

@Named("gaTracker")
public class GaTrackerRequestProcessor implements RequestProcessor {

    public static final String GA_TRACKER_ID =
        System.getProperty("cubeia.nexus.gaTrackerId");
    public static final String GA_REFERER_URL =
        System.getProperty("cubeia.nexus.gaRefererUrl");

    private final Logger log = LoggerFactory.getLogger(getClass());
    private final JGoogleAnalyticsTracker tracker;

    public GaTrackerRequestProcessor() {
        if(GA_TRACKER_ID == null) {
            String msg = "Missing system property 'cubeia.nexus.gaTrackerId'";
            throw new IllegalStateException(msg);
        }
         log.info("Creating new tracker, with id: " + GA_TRACKER_ID);
        tracker = new JGoogleAnalyticsTracker("nexus", "read", GA_TRACKER_ID);
        checkRefererUrl();
        adaptLogging();
    }

    [...]

We configure the plugin via system properties (not too beautiful, I know), the “tracker id” is the google tracking code id and is mandatory, and the “refer url” will be set on the call to GA if available.  We’re using the JGoogleAnalytics library to call GA for us. Also, I’m being naughty and throwing an illegal state exception if the tracker id is missing, since GA updates every 24 hours we’d like to be notified on errors early.

There’s  two methods above, one sets the logging in the tracker code to use to slf4j logger instead and the other checks for and sets the referer URL:

private void adaptLogging() {
    /*
     * Adapt the logging to use slf4j instead.
     */
    tracker.setLoggingAdapter(new LoggingAdapter() {

        public void logMessage(String msg) {
            log.debug(msg);
        }

        public void logError(String msg) {
            log.error(msg);
        }
    });
}

private void checkRefererUrl() {
    if(GA_REFERER_URL != null) {
        /*
         * If we have a referer URL we need to set this. However, the
         * tracker does not have a getter for the URL binding strategy, so
         * we'll simply create a new one, ugly, but works.
         */
        log.info("Modifying GA tracking to use referer URL: " + GA_REFERER_URL);
        GoogleAnalytics_v1_URLBuildingStrategy urlb;
        urlb = new GoogleAnalytics_v1_URLBuildingStrategy("nexus", "read", GA_TRACKER_ID);
        urlb.setRefererURL("http://m2.cubeia.com");
        // set new referer
        tracker.setUrlBuildingStrategy(urlb);
    }
}

Not too complicated eh? The only thing to note is that the only way to set the refer URL isby creating a new URL building strategy. Well, I can live with that.

Before we go on we’ll create a small subclass on FocusPoint which we’ll use for tracking. Since JGoogleAnalitycs is made primarily for applications the focus point will URL encode itself, however, that won’t work for us, so we need to override it’s getContentURI method:

/**
 * Simple inner class that adapts the content URI to
 * not be URL-escaped.
 */
private static class Point extends FocusPoint {

    public Point(String name) {
        super(name);
    }

    @Override
    public String getContentURI() {
        return getName();
    }
}

And finally we’ll tie it all toghether. We’ll react on “read” actions, create a URI (of form ‘//path’) and track asynchronously (which will spawn a new thread for calling GA:

 public boolean process(Repository rep, ResourceStoreRequest req, Action action) {
    if(action == Action.read) {
        /*
         * 1) create path by appending repo path to repo id
         * 2) create a subclass of focus point that handles proper URI's
         * 3) track asynchronously, this will perform the tracking on a new thread
         */
        String path = rep.getId() + req.getRequestPath();
        log.debug("Tracking path: " + path);
        FocusPoint p = new Point(path);
        tracker.trackAsynchronously(p);
    } else {
        log.debug("Ingoring action '" + action + "' for: " + req.getRequestPath());
    }
    return true;
}

And that’s it. It’s not perfect though ideally I’d like to track hosted repositories only, I’d like to avoid tracking crawlers and I would prefer not to configure via system properties (hint for you Nexus bundle users out there, you can set system properties in the “conf/wrapper.conf” files), but I’ll leave those for a rainy day.

Here’s the source code as a Maven project.

Enjoy!

Update: If you download and try to compile, you will probably be missing the JGoogleAnalytics lib. You’re welcome to use our, GA-tracked, repository if you like

<repository>
  <id>cubeia-nexus</id>
  <url>http://m2.cubeia.com/nexus/content/groups/public/</url>
  <releases>
    <enabled>true</enabled>
  </releases>
  <snapshots>
    <enabled>true</enabled>
  </snapshots>
</repository>

This has surely caused some frustration for us. After looking around we understood that the underlying bug is in Subversion while the Maven problem is reported here.

In the latter bug report, there is a suggestion for a workaround:

First, execute “mvn release:prepare”. When the error message appears, run “svn update” and then try again with “mvn release:prepare -Dresume”.

This has worked every time for us, but it has not ceased to feel like an ugly workaround.

Good luck!

1. You constantly update and “mvn install” everything and the kitchen sink, just to be sure

This is the most common problem I have seen. The fix for this will have benefits for many of the points below. Here’s a statement that I don’t think you can find anywhere in the Maven documentation, but that I firmly believe is true:
“Every Maven artifact HAS to have a home in one Maven repository.”

This means that, in your company, you have to have a repository manager, such as Archiva or Artifactory. Every module that you develop must be deployed to this repository. When should we deploy our artifacts, you might ask? The answer is: after each successful build, by your build server. We currently use Hudson for this, but Continuum or TeamCity will do the job as well.

Now, when each module is always deployed to the repository, and your Maven installation fetches its dependencies from this repository, you will no longer have to “update and install everything”. If you are working on one module, you should only have to build that module. The other modules will be downloaded to you automatically.

2. You and your colleagues solve the “dependency not found” problem by copying someone’s entire .m2-folder via memory stick
As crazy as this workaround seems, I have seen it done over and over again. Again, the solution is to have a repository manager. Once this is hooked up properly, you will never have to do the ugly “who has a memory stick?” dance again. You shouldn’t even have to fear wiping your local repository entirely, since download speed from the local repository manager should be very fast.

3. You solve missing dependency problems to old versions of local artifacts by taking the latest pom file of the module, changing the version and then installing that module
Consider the scenario where someone has changed the version of a module from 1.3-SNAPSHOT to 1.4-SNAPSHOT. You have been on a (well deserved) holiday, so you never updated and installed the 1.3-SNAPSHOT. Now, there’s another module that depends on 1.3-SNAPSHOT. How will you get a hold of that version? Well, you could dig around in the source management system to find the latest version of the module, where the version was still 1.3-SNAPSHOT, update to that version and install it. Or you could do the dirty trick of just changing your latest checkout from 1.4 to 1.3, install and then cross your fingers and hope that it works.

I think we all can agree that neither solution is pretty. Again, had your company had a repository manager, if there were at least one successful build of 1.3-SNAPSHOT, it would be in the repository. Problem solved.

4. You have lots of shell scripts / batch files that traverse the target folders of your modules to create a zip file
Maven has a way of doing this, called “assemblies”. They are not the easiest to set up, but once you have it set up, it will integrate with Maven in a much smoother way than most home cooked scripts. There are so many things that can go wrong with these scripts once versions start to change, modules are moved and so on. I think this is a matter of using the tool that is designed to do the job. This also means that you can create an assembly and deploy it to the Maven repository. Indeed, this is how we publish the distributions of Firebase to our customers and it works well for us.

5. You have lots of xml in your poms whose only purpose is to copy files into your deploy folders, but it’s not working properly and it’s not portable
This is the flip side of the coin in point 4. Maven does not seem to be built for copying files. If all you want to do is to copy your artifact (be it a war, an ear or a zip file), it might be easier to just create an ant / shell / batch script to do the job. I have been known to be a culprit of trying to bend Maven this way, but it just doesn’t seem to want to go there with me. One issue is which phase to bind the copy task to, not to mention problems with making the solution portable, so that your colleague can have the file copied to C:deploy, you can have it deployed to ~/deploy while the build server should skip this step altogether.

6. Your build stalls forever on “checking for updates from xxx-repo” and you don’t know why
This is a real time consumer that few developers seem to be sufficiently annoyed by to find the root cause of. Perhaps the delay is just too good of an excuse to go and get a coffee. Anyhow, a common cause of this problem is that you have snapshot dependencies and a number of repositories listed in your pom files. Maven has no concept of which artifact it should check for in which repository, so it happily looks for updates of all artifacts in all repositories. The trick, again (you guessed it), is to use a repository manager.

If you configure your Maven installation to look for all artifacts in this repository (by setting a mirror in your settings.xml), Maven will only look there. Since this server is local, it will be fast. It’s important here that the repository manager is also configured properly. For Archiva, this means that you should cache failures and only update snapshots daily.

7. If you work on the release branch, your trunk build might fail (or 1.0-SNAPSHOT should be good enough for everyone)
There are a few things that you should remember to do when creating a branch of your project. One is to tell your build server to also build this branch and the other is to change the version in your pom files. If you neglect to do the latter, problems will ensue when you change the signature of a method in your branch, and then try to develop on the trunk again.

There is a goal in the release plugin called “branch“, by running “mvn release:branch”, Maven can automatically rename the versions in the poms for you. (Disclaimer, I haven’t tried this myself, since we usually only branch when we create a release, using “mvn release:prepare” followed by “mvn release:perform”).

8. All your company internal dependencies end with -SNAPSHOT
The idea of a snapshot seems comforting to developers. It’s almost done. But sooner or later, you will have to put your foot down and release your module to the world, or at least your colleagues. There are a few problems with staying in snapshot land forever. First, it slows down your build, since Maven has to check for the latest snapshot from remote repositories (or at least repository, if you followed point 6). Second, if you depend on a snapshot, it’s hard to know which version of the snapshot you are depending on. My build can fail, while your build works, just because you happen to have a newer snapshot.

If you depend on a company internal module that works the way it is right now, it might be a good idea to drop a release of that module and change the dependency to the non snapshot version. Now we know that even if the guys working on that module go crazy with new features, your module will still build, since it depends on a stable release.

9. If you run “mvn dependency:analyze” the list of unused and undeclared dependencies is too long to recite before lunch
This might seem a bit anal, but there is a real danger in not knowing exactly what you depend on. The biggest issue here is caused by a problem with Maven’s way of handling transitive dependencies. Because of this, you can use code in your dependency’s dependencies and it will compile just fine. The problems come when either you decide to change the scope of that dependency to “provided”, or the writers of the module you depend on decide to change its dependencies. Now, the code will no longer compile. It also is an undocumented dependency which can lure you into a false sense of security. I have written more about this issue here.

Luckily, there is a way to check how many shortcuts you have taken by running “mvn dependency:analyze”. This will tell you which modules you are using without having declared a dependency to them and which modules you depend on, but are not using. Obviously, the second list is not as dangerous, but still brings in unnecessary jar files which will increase build time and the size of your project assemblies.

10. When someone releases a new version of a plugin that you use, your builds tend to fail
Maven has for some reason decided that you don’t need to specify the version of your plugin dependencies. Maven will find the “latest and greatest” for you. When a new version of a plugin is released, you will download and use it without knowing it. Sometimes, the “latest and greatest” is not always so, as low and behold, new versions can contain new bugs. Therefore, it is a good practice to always declare the version that you wish to use when you specify a plugin in your pom file. If you really want to be sure, you can specify the versions of Maven’s internal plugins as well.

References
The Official Maven Site
Maven: The Definitive Guide