Journal

Starting and configuring a Jetty 7 instance in Equinox

Henrik Gustafsson — Wed, 16 Feb 2011 13:01:02 +0000

Starting an embedded Jetty 7 server in Equinox is easy, but getting the right configuration in the right place can be slightly harder.

I am currently using the following Jetty bundles:

org.eclipse.jetty.client
org.eclipse.jetty.continuation
org.eclipse.jetty.deploy
org.eclipse.jetty.http
org.eclipse.jetty.io
org.eclipse.jetty.jmx
org.eclipse.jetty.osgi.boot
org.eclipse.jetty.security
org.eclipse.jetty.server
org.eclipse.jetty.servlet
org.eclipse.jetty.servlets
org.eclipse.jetty.util
org.eclipse.jetty.webapp
org.eclipse.jetty.xml

Some bundles are required only because I want to support gzip loading, jmx introspection and authentication. What bundles can be removed is left as an exercise to the reader.

Jetty is started by the org.eclipse.jetty.osgi.boot bundle, so I make sure this is auto-started. However, in order for Jetty to become useful I also need to reconfigure it.

When the Jetty boot bundle is activated, it runs the DefaultJettyAtJettyHomeHelper#startJettyAtJettyHome(org.osgi.framework.BundleContext) method and that in turn looks at a few properties to determine where to read the configuration from. We elected to use the jetty.home.bundle property.

Armed with the information gleaned from those docs, and the instructions on how to inject new server-wide features into Jetty-OSGi on the eclipse wiki, I created a fragment bundle that is loaded and activated with org.eclipse.jetty.osgi.boot and modifies the jetty.home.bundle property so the configuration is read from the fragment bundle instead of the one included in the Jetty boot bundle.

To set the property I created a fragment activator (all package names have been changed to protect the innocent):

package jettyconfig;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

public class FragmentActivator implements BundleActivator {

    @Override
    public void start(BundleContext context) throws Exception {
        // Set jetty.home.bundle to the name of our bundle
        System.setProperty("jetty.home.bundle", "jettyconfig");
    }

    @Override
    public void stop(BundleContext context) throws Exception {
    }
}

The fragment activator will be executed just before the Jetty boot bundle is activated.

It would also be possible to set this property from the command-line (as is probably more proper), but after some discussion we preferred to do it like this until something better comes along.

The MANIFEST.MF looks like this:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Jetty Configuration
Bundle-SymbolicName: jettyconfig
Bundle-Version: 1.0.0.qualifier
Fragment-Host: org.eclipse.jetty.osgi.boot;bundle-version="7.2.2"
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Bundle-Vendor: Henrik Gustafsson

Finally, I could put my config in /etc/jetty.xml in the fragment bundle, and Jetty is started with this configuration. As a starting point for my jetty.xml I used the jetty-osgi-default.xml file and the notes on the jetty.xml wiki page. In particular I needed a ContextHandlerCollection (or perhaps a OSGiAppProvider) configured for Jetty to pick up the services properly.

Adding authentication to a Jetty 7 deployment through jetty-web.xml

Henrik Gustafsson — Fri, 28 Jan 2011 18:17:26 +0000

In a setup similar to the one I wrote about here, we had to add some basic http authentication. To add authentication to a context handler all that is needed is to set a security handler to it. This can be accomplished in at least two ways, programmatically or using the web.xml. The former is a bit ugly and the latter stops us from exposing our servlets using OSGi-DS (see previous post). After some internal discussion we opted for a third variant; using jetty-web.xml. I mean, since we had to put it there, so we might as well put it to good use!

From the start we decided we would want to share the authentication configuration between (most of) the different context handlers we have now exposed as OSGi-services. This means we needed some way of sharing the data that we create. We have the realm file used by the HashLoginService configurable as a system property, and we could share that, creating new HashLoginService instances in each context handler. However, it gets more complicated if we want to configure some other LoginService and use that everywhere. So, we decided to attempt to share the actual LoginService instance. In fact, after some experimentation and refactoring of the xml-files I ended up with being able to share the entire SecurityHandler between the services using Server#setAttribute().

This resulted in the following addition to our jetty.xml:






    

    
        MyRealm
        
            
        
        5
        
    

    
        true
        BASIC
        
            
                admin
            
        
    

    
        
            
        
        MyRealm
        
            
                
                    /*
                    
                        
                    
                
            
        
    

    
        
    

    
        DefaultSecurityConstraint
        
    

    
        DefaultLoginService
        
    

    
        DefaultSecurityHandler

Notice how we set attributes on the server for several of the objects we created. We can't/don't want to reuse the same SecurityHandler everywhere (actually not, read to the end...), but we still want to reuse some of the other parts. This allows us to change some of the settings, but still lets us reconfigure the LoginService from a single place.

Next, I just had to swap the otherwise empty jetty-web.xml for this this:





    
        
            DefaultSecurityHandler

Yea, right. Finally. However, once a second component is added, this thing reared its head:

2011-01-31 12:51:11,173 INFO  org.eclipse.jetty.util.log Deployable added: webthing-1.0.0.qualifier/jetty-web.xml
2011-01-31 12:51:11,206 WARN  org.eclipse.jetty.util.log FAILED t.w.WebThing{/hello,null}: java.lang.IllegalStateException: STARTED
2011-01-31 12:51:11,206 WARN  org.eclipse.jetty.util.log Unable to reach node goal: started
java.lang.IllegalStateException: STARTED
    at org.eclipse.jetty.server.handler.HandlerWrapper.setHandler(HandlerWrapper.java:70)
    at org.eclipse.jetty.servlet.ServletContextHandler.startContext(ServletContextHandler.java:205)
    at org.eclipse.jetty.server.handler.ContextHandler.doStart(ContextHandler.java:584)
    at org.eclipse.jetty.util.component.AbstractLifeCycle.start(AbstractLifeCycle.java:55)
    at org.eclipse.jetty.deploy.bindings.StandardStarter.processBinding(StandardStarter.java:36)
    at org.eclipse.jetty.deploy.AppLifeCycle.runBindings(AppLifeCycle.java:180)
    at org.eclipse.jetty.deploy.DeploymentManager.requestAppGoal(DeploymentManager.java:481)
    at org.eclipse.jetty.deploy.DeploymentManager.addApp(DeploymentManager.java:137)
    at org.eclipse.jetty.osgi.boot.OSGiAppProvider.addContext(OSGiAppProvider.java:197)
    at org.eclipse.jetty.osgi.boot.OSGiAppProvider.addContext(OSGiAppProvider.java:179)
    at org.eclipse.jetty.osgi.boot.internal.webapp.WebBundleDeployerHelper.registerContext(WebBundleDeployerHelper.java:400)
    at org.eclipse.jetty.osgi.boot.internal.webapp.WebBundleDeployerHelper.registerContext(WebBundleDeployerHelper.java:348)
    at org.eclipse.jetty.osgi.boot.internal.webapp.WebBundleDeployerHelper.registerContext(WebBundleDeployerHelper.java:308)
    at org.eclipse.jetty.osgi.boot.internal.webapp.JettyContextHandlerServiceTracker.serviceChanged(JettyContextHandlerServiceTracker.java:247)
    at org.eclipse.osgi.internal.serviceregistry.FilteredServiceListener.serviceChanged(FilteredServiceListener.java:104)
    at org.eclipse.osgi.framework.internal.core.BundleContextImpl.dispatchEvent(BundleContextImpl.java:933)
    at org.eclipse.osgi.framework.eventmgr.EventManager.dispatchEvent(EventManager.java:227)
    at org.eclipse.osgi.framework.eventmgr.ListenerQueue.dispatchEventSynchronous(ListenerQueue.java:149)
    at org.eclipse.osgi.internal.serviceregistry.ServiceRegistry.publishServiceEventPrivileged(ServiceRegistry.java:756)
    at org.eclipse.osgi.internal.serviceregistry.ServiceRegistry.publishServiceEvent(ServiceRegistry.java:711)
    at org.eclipse.osgi.internal.serviceregistry.ServiceRegistrationImpl.register(ServiceRegistrationImpl.java:130)
    at org.eclipse.osgi.internal.serviceregistry.ServiceRegistry.registerService(ServiceRegistry.java:206)
    at org.eclipse.osgi.framework.internal.core.BundleContextImpl.registerService(BundleContextImpl.java:507)
    at org.eclipse.equinox.internal.ds.InstanceProcess.registerService(InstanceProcess.java:504)
    at org.eclipse.equinox.internal.ds.InstanceProcess.buildComponents(InstanceProcess.java:212)
    at org.eclipse.equinox.internal.ds.Resolver.buildNewlySatisfied(Resolver.java:441)
    at org.eclipse.equinox.internal.ds.Resolver.enableComponents(Resolver.java:213)
    at org.eclipse.equinox.internal.ds.SCRManager.performWork(SCRManager.java:800)
    at org.eclipse.equinox.internal.ds.SCRManager$QueuedJob.dispatch(SCRManager.java:767)
    at org.eclipse.equinox.internal.ds.WorkThread.run(WorkThread.java:89)
    at org.eclipse.equinox.internal.util.impl.tpt.threadpool.Executor.run(Executor.java:70)

Turns out it's not a particularly good idea to share the security handler. So, in the end the configuration for the components looked like this:





    
        
            DefaultLoginService
        
        
            DefaultSecurityConstraint
        
    

    
        
            
                
            
            MyRealm
            
                
                    
                        /*

Now, if there were only some nice way of injecting these services into our OSGi-components without going though the Server attributes...

Improvement suggestions and corrections welcome!

Deploying a servlet in Jetty 7 using OSGi-DS

Henrik Gustafsson — Wed, 26 Jan 2011 21:48:33 +0000

I recently had to deploy a servlet to an instance of a Jetty 7 (7.2.2 to be precise) server embedded in Equinox. To bootstrap Jetty I used the org.eclipse.jetty.osgi.boot bundle as described on the Eclipse Wiki. This bundle is not shipped with 7.2.2 but can be built from source easily.

As it stands, all services in our system runs using OSGi-DS, and I figured it would be neat if I were able to deploy the servlets in a similar fashion.

The servlets themselves are constructed in a non-trivial manner, and had some dependencies on other OSGi-DS-exposed services, so programmatic construction of the servlet instances is preferable for now.

Turns out that's not completely simple or free of hacks, but also not extremely hard.

The org.eclipse.jetty.osgi.boot bundle registers a service tracker looking for services extending org.eclipse.jetty.server.handler.ContextHandler, which basically means that if I just add a tag to my OSGi service component description I can have Jetty pick up on that automagically.

Yay! Well, almost. This was my first try at a component:

package test.webthing;

import java.util.Map;

import javax.servlet.Servlet;

import org.eclipse.jetty.osgi.boot.OSGiWebappConstants;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;
import org.osgi.service.component.ComponentContext;

public class WebThing extends ServletContextHandler {

    public WebThing() {
        setContextPath("/hello");
    }

    private void addServlet(final Servlet servlet) {
        final ServletHolder holder =
            getServletHandler().newServletHolder();
        holder.setServlet(servlet);
        addServlet(holder, "/");
    }

    public void activate(Map properties)
        throws Exception {
        addServlet(new HelloServlet());
    }
}

That didn't quite work, however; I got this beauty in the logs:

2011-01-26 23:04:24,302 DEBUG org.eclipse.jetty.osgi.boot FrameworkEvent ERROR
java.lang.IllegalArgumentException: the property contextFilePath is required
    at org.eclipse.jetty.osgi.boot.internal.webapp.JettyContextHandlerServiceTracker.serviceChanged(JettyContextHandlerServiceTracker.java:231)
    at org.eclipse.osgi.internal.serviceregistry.FilteredServiceListener.serviceChanged(FilteredServiceListener.java:104)
    at org.eclipse.osgi.framework.internal.core.BundleContextImpl.dispatchEvent(BundleContextImpl.java:933)
    at org.eclipse.osgi.framework.eventmgr.EventManager.dispatchEvent(EventManager.java:227)
    at org.eclipse.osgi.framework.eventmgr.ListenerQueue.dispatchEventSynchronous(ListenerQueue.java:149)
    at org.eclipse.osgi.internal.serviceregistry.ServiceRegistry.publishServiceEventPrivileged(ServiceRegistry.java:756)
    at org.eclipse.osgi.internal.serviceregistry.ServiceRegistry.publishServiceEvent(ServiceRegistry.java:711)
    at org.eclipse.osgi.internal.serviceregistry.ServiceRegistrationImpl.register(ServiceRegistrationImpl.java:130)
    at org.eclipse.osgi.internal.serviceregistry.ServiceRegistry.registerService(ServiceRegistry.java:206)
    at org.eclipse.osgi.framework.internal.core.BundleContextImpl.registerService(BundleContextImpl.java:507)
    at org.eclipse.equinox.internal.ds.InstanceProcess.registerService(InstanceProcess.java:504)
    at org.eclipse.equinox.internal.ds.InstanceProcess.buildComponents(InstanceProcess.java:212)
    at org.eclipse.equinox.internal.ds.Resolver.buildNewlySatisfied(Resolver.java:441)
    at org.eclipse.equinox.internal.ds.Resolver.enableComponents(Resolver.java:213)
    at org.eclipse.equinox.internal.ds.SCRManager.performWork(SCRManager.java:800)
    at org.eclipse.equinox.internal.ds.SCRManager$QueuedJob.dispatch(SCRManager.java:767)
    at org.eclipse.equinox.internal.ds.WorkThread.run(WorkThread.java:89)
    at org.eclipse.equinox.internal.util.impl.tpt.threadpool.Executor.run(Executor.java:70)

Ok, so, I set my breakpoints to stun and started debugging. What happened was that in JettyContextHandlerServiceTracker#serviceChanged() there was a check that required the property "contextFilePath" of the service to be set to something other than null. Digging further revealed that not only did it have to be set to something non-null, it also needed to be a valid jetty-web.xml-file. "But Why!?", I exclaimed, but added the property to my component properties and created a dummy jetty-web.xml file:

Aha! Progress in the logs!

2011-01-26 22:36:35,763 INFO  org.eclipse.jetty.util.log Deployable added: webthing-1.0.0.qualifier/jetty-web.xml

And indeed, the servlet works!

$ curl http://localhost:8080/hello/
HELLO
$

So I modified my component slightly to look like this:

package test.webthing;

import java.util.Map;

import javax.servlet.Servlet;

import org.eclipse.jetty.osgi.boot.OSGiWebappConstants;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;

public class WebThing extends ServletContextHandler {
    private void addServlet(final Servlet servlet) {
        final ServletHolder holder =
            getServletHandler().newServletHolder();
        holder.setServlet(servlet);
        addServlet(holder, "/");
    }

    public void activate(Map properties)
        throws Exception {
        setContextPath(
            (String) properties.get(
                OSGiWebappConstants.SERVICE_PROP_CONTEXT_PATH));
        addServlet(new HelloServlet());
    }
}

and added the contextPath property to my component description (to make it consistent), which now looked like this:

Hopefully the requirement for a jetty.xml-file will go away in the future, but for now, I can live with it like this, but if anyone has an idea of how to make it better, let me know!

The "webthing" bundle can be downloaded here.

A fond farewell to Purple Scout

Henrik Gustafsson — Sat, 28 Aug 2010 03:40:13 +0000

So, this is it.

I switched on the alarm at the Purple Scout offices, probably for the last time. A few tears were shed and a few hugs were shared during the latter part of the evening, I'm not ashamed to admit. Purple Scout has been like a second home and family for me for the better part of four years. I pity one and all who have not been so lucky as to have experienced the camaraderie and fellowship associated with being a Purple Scout employee.

Why am I leaving Purple Scout?

All other things being equal, the reasons making the scale tip over to Procera's favor were threefold: First, for various reasons I have never been able to complete a project or product about which I have felt both engaged in and proud of, and the PSM project/product might just be it. The next opportunity for a project that I feel so strongly about had I stayed with Purple Scout would most likely be a long way away. It's a personal type of closure that I've yet to achieve. The second reason was more of a pragmatic one. When this project was removed, what was I to do? Certainly there would eventually show up some sort of task that I might perform, but I find it highly unlikely that I would get the same sort of challenges, team dynamics and sense of brotherhood that the PSM-team has. Finally, and by far the most important reason, almost the entire team of my project collectively signed the new employment contracts, with the last member having personal reasons for not doing so. We even sent all of our signed contracts in the same envelope.

And where am I going?

My new employer is Procera Networks. Can they ever provide the same incredible experience? Well, they do have some exciting challenges lined up, first and foremost the next version of our software that we need to finish, but no matter what exciting technical problems they offer, will they live up to the same standards as Purple Scout when it comes to being a good employer and, indeed, a good friend?

Only time will tell, but I suppose the only way of finding out is at the end. Whether I'm about to cry because of people and places I already miss on my way out of the door. I sure hope that will be the case.

Procera certainly does show some promise though! Besides, our team will be quite the horde of Purple People joining Procera, so their resistance will be futile. They will be assimipurpled. Purplimilated. Purplified. Or perhaps they're just that good already. We'll see.

To all of you who make up Purple Scout and its ideals, thank you for the wonderful time we've had, and a special thank you to Johan Strömhage and Kasper Aase whose dedication to their employees have been a beacon of light through economic recessions and growth alike.

Suspiciously absent above, but no less instrumental to my experience at Purple Scout is Emil Erlandsson. However, he's part of the swarm of Purple locusts currently preparing our descent upon the unsuspecting Malmö offices of Procera Networks. I'm not quite done with him yet :)

I wish Purple Scout all the best in the future and I hope to be meeting and working with all of you again!

So…

PSM-team is dead, long live PSM-team!

My opinions on multiple function / method exit points

Henrik Gustafsson — Wed, 18 Nov 2009 12:13:31 +0000

I originally posted this at Stack Overflow as a response to this question. Since then some people have asked me the same questions outside, so I figured I should just post it here.

There are good things to say about having a single exit-point, just as there are bad things to say about the inevitable "arrow" programming that results.

If using multiple exit points during input validation or resource allocation, I try to put all the 'error-exits' very visibly at the top of the function.

Both the Spartan Programming article of the "SSDSLPedia" and the single function exit point article of the "Portland Pattern Repository's Wiki" have some insightful arguments around this.

If you really want a single exit-point (in any non-exception-enabled language) for example in order to release resources in one single place, I find the careful application of goto to be good; see for example this rather contrived example (compressed to save screen real-estate):

int f(int y) {
    int value = -1;
    void *data = NULL;

    if (y < 0)
        goto clean;

    if ((data = malloc(123)) == NULL)
        goto clean;

    /* More code */

    value = 1;
clean:
   free(data);
   return value;
}

Personally I, in general, dislike arrow programming more than I dislike multiple exit-points, although both are useful when applied correctly. The best, of course, is to structure your program to require neither. Breaking down your function into multiple chunks usually help :)

Although when doing so, I find I end up with multiple exit points anyway as in this example, where some larger function has been broken down into several smaller functions:

int g(int y) {
  value = 0;

  if ((value = g0(y, value)) == -1)
    return -1;

  if ((value = g1(y, value)) == -1)
    return -1;

  return g2(y, value);
}

Depending on the project or coding guidelines, most of the boiler-plate code could be replaced by macros. As a side note, breaking it down this way makes the functions g0, g1 ,g2 very easy to test individually.

Obviously, in an OO and exception-enabled language, I wouldn't use if-statements like that (or at all, if I could get away with it with little enough effort), and the code would be much more plain. And non-arrowy. And most of the non-final returns would probably be exceptions.

In short;

Few returns are better than many returns
More than one return is better than huge arrows, and guard clauses are generally ok.
Exceptions could/should probably replace most 'guard clauses' when possible.

Varför vaccinerade jag mig?

Henrik Gustafsson — Tue, 17 Nov 2009 17:41:34 +0000

Jag var idag och vaccinerade mig mot A(H1N1)v / nya influensan / svininfluensan / galtfebern, och förutsatt att jag inte drar på mig den riktiga influensan dom närmaste två veckorna (som exempelvis i väntrummet efter vaccinationen där massa människor var samlade på liten yta...barriärvård, tack? :) så bör jag vara rätt safe.

Innan jag skriver något mer kanske jag ska påpeka att jag inte har någon som helst medicinsk utbildning, så tänk själva och fråga er läkare om något är oklart.

Så varför vaccinerade jag mig? Förutom det uppenbara -- jag har ingen lust att ligga hemma och vara sjuk i flera veckor -- så är det mest en fråga om solidaritet.

Ju fler som vaccinerar sig, ju färre smittvägar har viruset, och ju färre smittvägar ju mindre risk är att personer som inte kan ta vaccinet av diverse anledningar exponeras för smittan, d.v.s populationsimmuniteten höjs. Mängden människor som inte kan ta vaccinet och mängden människor som riskerar allvarliga effekter överlappar till stor del om man får tro avsnittet "Innan du får Pandemrix" i FASS artikel om Pandemrix och frågorna 3 och 17 i ECDCs Frequently asked questions on pandemic (H1N1) 2009.

Som en bieffekt kan man hoppas att inte så många blir sjukskrivna samtidigt pga vaccinet och kan gå till jobbet och bidra till BNP som dom goda löneslavar vi är :)

Enligt mig(!) giltiga ursäkter att inte ta vaccinet

Graviditet
Äggallergi
Febersjuk (vilket bara är en temporär ursäkt)
Du har redan haft influensan
Rekommendation från läkare eller sköterska

Enligt mig(!) ogiltiga ursäkter

Kvicksilver/Tiomersal/Thimerosal är farligt!
Men bieffekterna…!
Jag har tappat bort kallelsen (Droppa in på ditt närmaste vaccinationsställe!)
Jag vet inte vart vaccinationsstället ligger
Jag sitter ändå bara på min kammare, träffar inget folk etc.
Jag är lat/sprut-rädd/whatever (även om du försöker rationalisera det till något annat!)
WAA WAA KONSPIRATION BIG PHARMA ILLUMINATI AUTISM

På bloggen Tankebrott görs ett mer grundligt jobb än vad jag gör i att reda ut det hela här.

För den som har intresse i att följa influensans utveckling kan jag rekommendera ECDCs site om H1N1-pandemin samt Smittskyddsinstitutets influensarapport-sida för information som inte är helt förstörd av kvällspressen.

Så har du inte vaccinerat dig än, så gå till ditt närmaste vaccinationsställe och få din skattefinansierade immunförsvarsuppgradering!

Och på vägen dit, i väntrummet och på hemresan kan jag rekommendera att lyssna på The Skeptics Guide To The Universe H1N1-special.

Trying out the picture gallery

Henrik Gustafsson — Thu, 24 Sep 2009 19:23:23 +0000

I figured it'd be neat to be able to post pictures from time to time etc, so I tried out the photo gallery with a handful of pictures I took this spring. Try it out on the Pictures page.

Overused Extract Method refactoring

Henrik Gustafsson — Mon, 21 Sep 2009 20:57:31 +0000

I was reading the ObjectMentor blogs the other day, and came across a post called "One Thing: Extract till you Drop" by Robert C. Martin. I definitely see the point of using extract method to a great extent in order to clarify the extent of the program, but I felt that example went a bit too far for a number of reasons.

The names of the extracted methods made very little sense. Even when knowing what the class does it is hard to figure out the difference between replaceAllSymbols() and replaceAllInstances() and their relations to the other methods. You actually need to read them all in order to puzzle together the call-graph.
It introduces mutability in the class quite unnecessarily making reuse of the instance impossible.
Some of the extracted methods have strangely asymmetric abstraction levels.

There are also some other issues regarding efficiency and thread-safeness that I reacted strongly to, especially since they are so easy to avoid.

When implementing it myself I thought about the scenarios when this would be used, and I could find two main ones. The first is to use this to iterate over different strings using the same dictionary and the second is to iterate over different dictionaries using the same string. Not knowing anything about the use-case I went for the former.

I made an attempt to improve it in the comments, but I was tired and messed it up a bit. Normally I probably would have solved the same problem in a manner closer to this:

public class SymbolReplacer {
    private static final Pattern pattern =
        Pattern.compile("\\$([a-zA-Z]\\w*)");

    private final SymbolLookup lookup;

    SymbolReplacer(SymbolLookup lookup) {
        this.lookup = lookup;
    }

    public String replace(CharSequence stringToReplace) {
        final Matcher matcher = pattern.matcher(stringToReplace);
        return buildReplacement(matcher).toString();
    }

    private StringBuffer buildReplacement(Matcher matcher) {
        final int bufferLength =
            matcher.regionEnd() - matcher.regionStart();
        final StringBuffer buffer =
            new StringBuffer(bufferLength);

        fillBuffer(matcher, buffer);
        return buffer;
    }

    private void fillBuffer(Matcher matcher, StringBuffer buffer) {
        while (matcher.find())
            matcher.appendReplacement(buffer,
                getMatchReplacement(matcher));
        matcher.appendTail(buffer);
    }

    public String getMatchReplacement(Matcher matcher) {
        final String expansion =
            lookup.lookupValue(matcher.group(1));
        return (expansion != null) ?
            expansion :
            Matcher.quoteReplacement(matcher.group(0));
    }
}

I introduced the interface SymbolLookup as a replacement for the secret getSymbol() method. There are a few things I would like to fix in this as well; the getMatchReplacement() method is not as clear as I would have liked, and the line of abstraction between the different methods/layers is not well defined. Still, provided that SymbolLookup is thread-safe, so is this class. Also, you can reuse the instance to iterate over many strings.