Commons Digester | How to migrate from old Digester

The main difference between Digester 1.X, 2.X and 3.X is that the + while the first follows the approach "given a Digester instance, then configure it", + the new Digester instead follows the opposite approach "given one (or more) configuration(s), create + multiple Digester instances" or "configure once, create everywhere".

Why? Even if both approaches sound complementary, the core concept is given by the assumption that every + Digester instance is not thread-safe, that implies that in a multi-thread application users have often + to reinstantiate the Digester and reconfigure it, i.e in a Servlet:

+ public class EmployeeServlet extends HttpServlet { + + public void doGet(HttpServletRequest req, HttpServletResponse res) + throws ServletException, IOException { + Digester digester = new Digester(); + digester.setNamespaceAware(true); + digester.setXIncludeAware(true); + digester.addObjectCreate("employee", Employee.class); + digester.addCallMethod("employee/firstName", "setFirstName", 0); + digester.addCallMethod("employee/lastName", "setLastName", 0); + + digester.addObjectCreate("employee/address", Address.class); + digester.addCallMethod("employee/address/type", "setType", 0); + digester.addCallMethod("employee/address/city", "setCity", 0); + digester.addCallMethod("employee/address/state", "setState", 0); + digester.addSetNext("employee/address", "addAddress"); + + Employee employee = (Employee) digester.parse(openStream(req.getParameter("employeeId"))); + ... +} +

Nothing wrong with that approach but configuration is not reusable; the RuleSet + interface fills in some way the reuse of configurations lack:

+ public class EmployeeRuleSet implements RuleSet { + + public void addRuleInstances(Digester digester) { + digester.addObjectCreate("employee", Employee.class); + digester.addCallMethod("employee/firstName", "setFirstName", 0); + digester.addCallMethod("employee/lastName", "setLastName", 0); + + digester.addObjectCreate("employee/address", Address.class); + digester.addCallMethod("employee/address/type", "setType", 0); + digester.addCallMethod("employee/address/city", "setCity", 0); + digester.addCallMethod("employee/address/state", "setState", 0); + digester.addSetNext("employee/address", "addAddress"); + } + +} +

then, in our sample servlet

+ public class EmployeeServlet extends HttpServlet { + + private final RuleSet employeeRuleSet = new EmployeeRuleSet(); + + public void doGet(HttpServletRequest req, HttpServletResponse res) + throws ServletException, IOException { + Digester digester = new Digester(); + digester.setNamespaceAware(true); + digester.setXIncludeAware(true); + + employeeRuleSet.addRuleInstances(digester); + + Employee employee = (Employee) digester.parse(openStream(req.getParameter("employeeId"))); + ... + } + +} +

Nothing wrong again, but:

RuleSet is not really a configuration, it just sets rules to given Digester instance;
Digester instance creation is totally delegated to clients;
Rules that match to the same pattern, need to specify this last n times for how many + rules match, that violates the DRY principle;
Rules semantic is not intuitive, since their creation is strictly related to + methods/constructors arguments.

In the new Digester, RuleSet has been suppressed in favor of RulesModule

+ class EmployeeModule extends AbstractRulesModule { + + @Override + protected void configure() { + forPattern("employee").createObject().ofType(Employee.class); + forPattern("employee/firstName").setBeanProperty(); + forPattern("employee/lastName").setBeanProperty(); + + forPattern("employee/address") + .createObject().ofType(Address.class) + .then() + .setNext("addAddress"); + forPattern("employee/address/type").setBeanProperty(); + forPattern("employee/address/city").setBeanProperty(); + forPattern("employee/address/state").setBeanProperty(); + } + +} +

Then, our sample Servlet become:

+ public class EmployeeServlet extends HttpServlet { + + private final DigesterLoader loader = newLoader(new EmployeeModule()) + .setNamespaceAware(true) + .setXIncludeAware(true); + + public void doGet(HttpServletRequest req, HttpServletResponse res) + throws ServletException, IOException { + Digester digester = loader.newDigester() + + Employee employee = digester.parse(openStream(req.getParameter("employeeId"))); + ... + } + +} + +

As you can notice, the RulesModule implements rules via fluent APIs, + making rules semantic simpler, and the effort of configuration is moved to the startup; + the DigesterLoader indeed will analyze all the RulesModule instances + and will be ready to create new Digester instances with pre-filled rules.