From 5dbc4ba8f8e9266ddd7da9d33857ca70c622bee8 Mon Sep 17 00:00:00 2001
From: Michael Bayne <mdb@threerings.net>
Date: Wed, 12 Feb 2003 05:35:21 +0000
Subject: [PATCH] Interfaces to support an extensible XML parsing and writing
 system.

git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@2262 542714f4-19e9-0310-aa3c-eee0fc999fb1
---
 .../threerings/tools/xml/NestableRuleSet.java | 65 +++++++++++++++++++
 .../threerings/tools/xml/NestableWriter.java  | 21 ++++++
 2 files changed, 86 insertions(+)
 create mode 100644 src/java/com/threerings/tools/xml/NestableRuleSet.java
 create mode 100644 src/java/com/threerings/tools/xml/NestableWriter.java

diff --git a/src/java/com/threerings/tools/xml/NestableRuleSet.java b/src/java/com/threerings/tools/xml/NestableRuleSet.java
new file mode 100644
index 000000000..395857630
--- /dev/null
+++ b/src/java/com/threerings/tools/xml/NestableRuleSet.java
@@ -0,0 +1,65 @@
+//
+// $Id: NestableRuleSet.java,v 1.1 2003/02/12 05:35:21 mdb Exp $
+
+package com.threerings.tools.xml;
+
+import org.apache.commons.digester.Digester;
+
+/**
+ * Used to define rule sets that can be nested within other rule sets. For
+ * example, say you have a "scene" object definition like so:
+ *
+ * <p> (Note that in the examples square brackets are used instead of
+ * angle brackets to simplify my life when composing the documentation.)
+ *
+ * <pre>
+ * [scene name="Foo" version=5]
+ * [/scene]
+ * </pre>
+ *
+ * This scene is extended with some auxiliary data defined by libraries
+ * which can parse and generate XML for their auxiliary objects:
+ *
+ * <pre>
+ * [scene sceneId=1 name="Foo" version=5]
+ *   [spot]
+ *     [portal portalId=1 x=1 y=1 targetSceneId=2/]
+ *     [portal portalId=2 x=15 y=3 targetSceneId=3/]
+ *     [portal portalId=3 x=9 y=6 targetSceneId=4/]
+ *   [/spot]
+ *   [miso]
+ *     [object tileId=878172 x=4 y=13 action="cluck"/]
+ *     [object tileId=123843 x=18 y=23 action="bark"/]
+ *   [/miso]
+ * [/scene]
+ * </pre>
+ *
+ * The spot and miso services can define nestable rule sets which will be
+ * handed to the scene services who will instruct them to add their rule
+ * instances with a prefix of <code>scene.spot</code> and
+ * <code>scene.miso</code> respectively. They then happily parse their
+ * auxiliary objects without knowing that they have been nested inside
+ * some larger structure.
+ *
+ * <p> The nestable ruleset should then leave a single object on the
+ * digester stack that the enclosing entity can grab.
+ *
+ * <p> This isn't proper use of XML, but it solves the problem at hand in
+ * an easily extensible manner.
+ */
+public interface NestableRuleSet
+{
+    /**
+     * Returns the name of the nested object's outer element so that the
+     * parent parser can use it to compose the total path prefix.
+     */
+    public String getOuterElement ();
+
+    /**
+     * Instructs this ruleset to add its rules such that it parses its
+     * object from the specified path prefix. The outer element returned
+     * by {@link #getOuterElement} will have been included in the path
+     * prefix.
+     */
+    public void addRuleInstances (String prefix, Digester digester);
+}
diff --git a/src/java/com/threerings/tools/xml/NestableWriter.java b/src/java/com/threerings/tools/xml/NestableWriter.java
new file mode 100644
index 000000000..716fae293
--- /dev/null
+++ b/src/java/com/threerings/tools/xml/NestableWriter.java
@@ -0,0 +1,21 @@
+//
+// $Id: NestableWriter.java,v 1.1 2003/02/12 05:35:21 mdb Exp $
+
+package com.threerings.tools.xml;
+
+import org.xml.sax.SAXException;
+import com.megginson.sax.DataWriter;
+
+/**
+ * Provides the writing component of the nestable parsing system described
+ * by {@link NestableRuleSet}.
+ */
+public interface NestableWriter
+{
+    /**
+     * Called to generate XML for the supplied object to the supplied data
+     * writer.
+     */
+    public void write (Object object, DataWriter writer)
+        throws SAXException;
+}