Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Message-ID: <396B1CE3.E3CE6785@infoplanning.com>
Date: Tue, 11 Jul 2000 09:10:59 -0400
From: Berin Loritsch <bloritsch@infoplanning.com>
MIME-Version: 1.0
To: Cocoon Dev List <cocoon-dev@xml.apache.org>
Subject: Avalon synchronization
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

Cocoon has been synchronized as of midnight last night.  The one last remaining
issue with the synchronization has almost been completely addressed (it compiles,
but it shouldn't be where it is).

I did a search to find every location where org.apache.arch.* was used, because
that should be considered deprecated.  The official resting place for all of those
classes is org.apache.avalon.* (.named and .config were merged into
org.apache.avalon).  org.apache.cocoon.Parameters has been moved to
org.apache.avalon.utils because one of the core pieces used it, and because it
is generic enough to be incorporated into Avalon.

It is important to note that all of the core classes (Component, Composer, etc.)
are maintained in the Avalon CVS directory.

The last remaining issue is the location of the SitemapConfigurationBuilder.
org.apache.arch.config is deprecated, and was used because it called protected
members of the ConfigurationImpl class (now kept in org.apache.avalon).  It
has a hack that will allow it to exist outside the same package as ConfigurationImpl,
so it should be moved where it makes the most sense (probably org.apache.cocoon.sitemap).

Functionality wise, it doesn't do a whole lot, and SAXConfigurationBuilder does all
the SitemapConfigurationBuilder and more.  I would suggest using a different pattern
for building the Configuration system:

Avalon uses an AvalonConfigurationBuilder that intercepts the SAX events it uses,
and passes the rest on to the SAXConfigurationBuilder.  Avalon then creates the
objects it needs with the Configurations returned from SAXConfigurationBuilder.

As an enhancement to make the afforementioned system work, SAXConfigurationBuilder
is re-useable.  It can be used in multiple locations within a file, or for many files.
It is imperitive that you call the startDocument and endDocument methods when you
use it multiple times.  Included is the key source file to demonstrate what the
AvalonConfigurationBuilder does:

/**
 * Title:        Avalon Server Framework<p>
 * Description:  This is the foundation of all Server projects.  It's strengths are
 * separation of concerns, strong component oriented architecture,
 * and robust implementations.<p>
 * Copyright:    Copyright (c) Berin Loritsch<p>
 * Company:      IPMS<p>
 * @author Berin Loritsch
 * @version 1.0
 */

package org.apache.avalon.loader;

import org.xml.sax.ContentHandler;
import org.xml.sax.Locator;
import org.xml.sax.Attributes;
import org.xml.sax.SAXException;
import org.xml.sax.Attributes;
import org.xml.sax.ext.LexicalHandler;
import java.util.Stack;
import java.util.Vector;
import java.util.Hashtable;
import java.util.Enumeration;
import org.apache.avalon.SAXConfigurationBuilder;
import org.apache.avalon.Configuration;
import org.apache.avalon.engine.servicemap.BlockInitialContextFactory;
import org.apache.avalon.engine.Avalon;
import org.apache.avalon.blocks.Block;

public class AvalonConfigurationBuilder implements ContentHandler {
    /** The current location within the file */
    private Stack current = new Stack();
    /** The configuration builder */
    private SAXConfigurationBuilder confBuilder = new SAXConfigurationBuilder();
    /** Boolean for whether we are inside a block */
    private boolean insideBlock = false;

    /**
     * Construct a new <code>AvalonConfigurationBuilder</code> instance.
     */
    public AvalonConfigurationBuilder() {
        super();

        // Add the default namespace declaration
        Namespace ns=new Namespace();
        ns.uri="";
        ns.previousUri=ns;
        this.namespaces.put("",ns);

        kernel = Avalon.getKernel();
    }

    /**
     * Receive an object for locating the origin of SAX document events.
     */
    public void startDocument() throws SAXException {
        current.clear();
        blocks.clear();
        insideBlock = false;
    }

    /**
     * Receive notification of the end of a document.
     */
    public void endDocument() throws SAXException {
    }

    ...

    /**
     * Receive notification of the beginning of an element.
     */
    public void startElement(String uri, String loc, String raw, Attributes attr) throws SAXException {
        String name = this.resolve(uri,loc,raw);

        current.push(name);

        if (name.equals("block")) {
            if (insideBlock) {
                throw new SAXException("Blocks cannot be nested.");
            } else {
                insideBlock = true;
                confBuilder.startDocument();
                confBuilder.setDocumentLocator(this.loc);
            }
        }

        if (insideBlock) {
            confBuilder.startElement(uri, loc, raw, attr);
        }

        ....
    }

    /**
     * Receive notification of the end of an element.
     */
    public void endElement(String uri, String loc, String raw) throws SAXException {
        String test = (String) current.pop();
        String name = this.resolve(uri,loc,raw);

        if (!test.equals(name)) {
            throw new SAXException("Not matching element.");
        }

        if (insideBlock) {
            confBuilder.endElement(uri, loc, raw);
        }

        if (name.equals("block")) {
            insideBlock = false;
            confBuilder.endDocument();

            kernel.addChild(confBuilder.getConfiguration());
        }
    }
    ...
}