I think the API for adding additional element mappings to the FOUserAgent is bound to cause problems when fop is deployed in a multi classloader environment.
Using tomcat as an example, an extension mapping deployed in a webapp can not be found if a well meaning administrator has placed fop.jar in tomcats common/lib directory. This is because FOTreeBuilder.addElementMapping(String) uses Class.forName() to load the element mapping class.
I see several possible solutions:
1) Let FOTreeBuilder.addElementMapping() also check the Thread.getContextClassLoader() for the extension element mapping. This will work in environments that actually sets the context classloader. Tomcat does but other environments doesn't.
2) Pass in an explicit classloader to use when loading extension mappings.
3) Let the client pass the actual element mapping object, instead of just passing in the name of the element mapping class.
I'm strongly in favor of 3) because it Just Work (tm), and when a ClassNotFoundException do occur, the programmer immediately knows why and how to fix it.
So I propose to change the API signature from FOUserAgent.addElementMapping(String) to FOUserAgent.addElementMapping(ElementMapping)