commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From simonetrip...@apache.org
Subject svn commit: r1076408 - in /commons/sandbox/digester3/trunk/src/site: site.xml xdoc/guide/dvsd3.xml
Date Wed, 02 Mar 2011 21:46:40 GMT
Author: simonetripodi
Date: Wed Mar  2 21:46:40 2011
New Revision: 1076408

URL: http://svn.apache.org/viewvc?rev=1076408&view=rev
Log:
started describing the differences of Digester and Digester3

Added:
    commons/sandbox/digester3/trunk/src/site/xdoc/guide/dvsd3.xml   (with props)
Modified:
    commons/sandbox/digester3/trunk/src/site/site.xml

Modified: commons/sandbox/digester3/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/digester3/trunk/src/site/site.xml?rev=1076408&r1=1076407&r2=1076408&view=diff
==============================================================================
--- commons/sandbox/digester3/trunk/src/site/site.xml (original)
+++ commons/sandbox/digester3/trunk/src/site/site.xml Wed Mar  2 21:46:40 2011
@@ -31,12 +31,13 @@
     </menu>
 
     <menu name="Developers Guide">
-      <item name="Core APIs"            href="/guide/core.html"/>
-      <item name="Plugins"              href="/guide/plugins.html"/>
-      <item name="Substitution"         href="/guide/substitution.html"/>
-      <item name="XML Rules"            href="/guide/xmlrules.html"/>
-      <item name="Annotations"          href="/guide/annotations.html"/>
-      <item name="FAQ"                  href="/guide/faq.html"/>
+      <item name="Core APIs"                 href="/guide/core.html"/>
+      <item name="Plugins"                   href="/guide/plugins.html"/>
+      <item name="Substitution"              href="/guide/substitution.html"/>
+      <item name="XML Rules"                 href="/guide/xmlrules.html"/>
+      <item name="Annotations"               href="/guide/annotations.html"/>
+      <item name="Digester vs. Digester3"    href="/guide/dvsd3.html"/>
+      <item name="FAQ"                       href="/guide/faq.html"/>
     </menu>
   </body>
 

Added: commons/sandbox/digester3/trunk/src/site/xdoc/guide/dvsd3.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/digester3/trunk/src/site/xdoc/guide/dvsd3.xml?rev=1076408&view=auto
==============================================================================
--- commons/sandbox/digester3/trunk/src/site/xdoc/guide/dvsd3.xml (added)
+++ commons/sandbox/digester3/trunk/src/site/xdoc/guide/dvsd3.xml Wed Mar  2 21:46:40 2011
@@ -0,0 +1,140 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+  <properties>
+    <title>Commons Digester | How to migrate from old Digester</title>
+    <author email="dev@commons.apache.org">Commons Documentation Team</author>
+  </properties>
+  <body>
+    <section name="New Digester APIs">
+      <p>The main difference between Digester <i>1.X</i>, <i>2.X</i>
and <i>3.X</i> is that the
+      while the first follows the approach <i>"given a Digester instance, then configure
it"</i>,
+      the new Digester instead follows the opposite approach <i>"given one (or more)
configuration(s), create
+      multiple Digester instances" or "configure once, create everywhere".</i></p>
+      <p>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:</p>
+      <source>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")));
+    ...
+}</source>
+      <p>Nothing wrong with that approach but configuration is not reusable; the <i>RuleSet</i>
+      interface fills in some way the reuse of configurations lack:</p>
+      <source>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");
+  }
+
+}</source>
+      <p>then, in our sample servlet</p>
+      <source>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")));
+    ...
+  }
+
+}</source>
+      <p>Nothing wrong again, but:</p>
+      <ol>
+        <li>RuleSet is not really a configuration, it just sets rules to given Digester
instance;</li>
+        <li>Digester instance creation is totally delegated to clients;</li>
+        <li>Rules that match to the same pattern, need to specify this last <i>n</i>
times for how many
+        rules match, that violates the DRY principle;</li>
+        <li>Rules semantic is not intuitive, since their creation is strictly related
to
+        methods/constructors arguments.</li>
+      </ol>
+      <p>In the new Digester, <i>RuleSet</i> has been suppressed in favor
of <i>RulesModule</i></p>
+      <source>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();
+  }
+
+}</source>
+      <p>Then, our sample Servlet become:</p>
+      <source>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")));
+    ...
+  }
+
+}</source>
+
+      <p>As you can notice, the <i>RulesModule</i> implements rules via
fluent APIs,
+      making rules semantic simpler, and the effort of configuration is moved to the startup;
+      the <i>DigesterLoader</i> indeed will analyze all the <i>RulesModule</i>
instances
+      and will be ready to create new Digester instances with pre-filled rules.</p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: commons/sandbox/digester3/trunk/src/site/xdoc/guide/dvsd3.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/sandbox/digester3/trunk/src/site/xdoc/guide/dvsd3.xml
------------------------------------------------------------------------------
    svn:keywords = Date Revision Author HeadURL Id

Propchange: commons/sandbox/digester3/trunk/src/site/xdoc/guide/dvsd3.xml
------------------------------------------------------------------------------
    svn:mime-type = text/xml



Mime
View raw message