path: root/libjava/classpath/gnu/xml/pipeline/PipelineFactory.java

/* PipelineFactory.java --
   Copyright (C) 1999,2000,2001 Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */

package gnu.xml.pipeline;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.lang.reflect.Constructor;
import java.util.StringTokenizer;

import org.xml.sax.*;
import org.xml.sax.ext.*;


/**
 * This provides static factory methods for creating simple event pipelines.
 * These pipelines are specified by strings, suitable for passing on
 * command lines or embedding in element attributes.  For example, one way
 * to write a pipeline that restores namespace syntax, validates (stopping
 * the pipeline on validity errors) and then writes valid data to standard
 * output is this: <pre>
 *      nsfix | validate | write ( stdout )</pre>
 *
 * <p> In this syntax, the tokens are always separated by whitespace, and each
 * stage of the pipeline may optionally have a parameter (which can be a
 * pipeline) in parentheses.  Interior stages are called filters, and the
 * rightmost end of a pipeline is called a terminus.
 *
 * <p> Stages are usually implemented by a single class, which may not be
 * able to act as both a filter and a terminus; but any terminus can be
 * automatically turned into a filter, through use of a {@link TeeConsumer}.
 * The stage identifiers are either class names, or are one of the following
 * short identifiers built into this class.  (Most of these identifiers are
 * no more than aliases for classes.)  The built-in identifiers include:</p>

 <table border="1" cellpadding="3" cellspacing="0">
    <tr bgcolor="#ccccff" class="TableHeadingColor">
        <th align="center" width="5%">Stage</th>
        <th align="center" width="9%">Parameter</th>
        <th align="center" width="1%">Terminus</th>
        <th align="center">Description</th>
    </tr>

    <tr valign="top" align="center">
        <td><a href="../dom/Consumer.html">dom</a></td>
        <td><em>none</em></td>
        <td> yes </td>
        <td align="left"> Applications code can access a DOM Document built
        from the input event stream.  When used as a filter, this buffers
        data up to an <em>endDocument</em> call, and then uses a DOM parser
        to report everything that has been recorded (which can easily be
        less than what was reported to it).  </td>
    </tr>
    <tr valign="top" align="center">
        <td><a href="NSFilter.html">nsfix</a></td>
        <td><em>none</em></td>
        <td>no</td>
        <td align="left">This stage ensures that the XML element and attribute
        names in its output use namespace prefixes and declarations correctly.
        That is, so that they match the "Namespace plus LocalName" naming data
        with which each XML element and attribute is already associated.  </td>
    </tr>
    <tr valign="top" align="center">
        <td><a href="EventFilter.html">null</a></td>
        <td><em>none</em></td>
        <td>yes</td>
        <td align="left">This stage ignores all input event data.</td>
    </tr>
    <tr valign="top" align="center">
        <td><a href="CallFilter.html">server</a></td>
        <td><em>required</em><br> server URL </td>
        <td>no</td>
        <td align="left">Sends its input as XML request to a remote server,
        normally a web application server using the HTTP or HTTPS protocols.
        The output of this stage is the parsed response from that server.</td>
    </tr>
    <tr valign="top" align="center">
        <td><a href="TeeConsumer.html">tee</a></td>
        <td><em>required</em><br> first pipeline</td>
        <td>no</td>
        <td align="left">This sends its events down two paths; its parameter
        is a pipeline descriptor for the first path, and the second path
        is the output of this stage.</td>
    </tr>

    <tr valign="top" align="center">
        <td><a href="ValidationConsumer.html">validate</a></td>
        <td><em>none</em></td>
        <td>yes</td>
        <td align="left">This checks for validity errors, and reports them
        through its error handler.  The input must include declaration events
        and some lexical events.  </td>
    </tr>
    <tr valign="top" align="center">
        <td><a href="WellFormednessFilter.html">wf</a></td>
        <td><em>none</em></td>
        <td>yes</td>
        <td align="left"> This class provides some basic "well formedness"
        tests on the input event stream, and reports a fatal error if any
        of them fail.  One example: start/end calls for elements must match.
        No SAX parser is permitted to produce malformed output, but other
        components can easily do so.</td>
    </tr>
    <tr valign="top" align="center">
        <td>write</td>
        <td><em>required</em><br> "stdout", "stderr", or filename</td>
        <td>yes</td>
        <td align="left"> Writes its input to the specified output, as pretty
        printed XML text encoded using UTF-8.  Input events must be well
        formed and "namespace fixed", else the output won't be XML (or possibly
        namespace) conformant.  The symbolic names represent
        <em>System.out</em> and <em>System.err</em> respectively; names must
        correspond to files which don't yet exist.</td>
    </tr>
    <tr valign="top" align="center">
        <td>xhtml</td>
        <td><em>required</em><br> "stdout", "stderr", or filename</td>
        <td>yes</td>
        <td align="left"> Like <em>write</em> (above), except that XHTML rules
        are followed.  The XHTML 1.0 Transitional document type is declared,
        and only ASCII characters are written (for interoperability).  Other
        characters are written as entity or character references; the text is
        pretty printed.</td>
    </tr>
    <tr valign="top" align="center">
        <td><a href="XIncludeFilter.html">xinclude</a></td>
        <td><em>none</em></td>
        <td>no</td>
        <td align="left">This stage handles XInclude processing.
        This is like entity inclusion, except that the included content
        is declared in-line rather than in the DTD at the beginning of
        a document.
        </td>
    </tr>
    <tr valign="top" align="center">
        <td><a href="XsltFilter.html">xslt</a></td>
        <td><em>required</em><br> XSLT stylesheet URI</td>
        <td>no</td>
        <td align="left">This stage handles XSLT transformation
        according to a stylesheet.
        The implementation of the transformation may not actually
        stream data, although if such an XSLT engine is in use
        then that can happen.
        </td>
    </tr>

 </table>

 * <p> Note that {@link EventFilter#bind} can automatically eliminate
 * some filters by setting SAX2 parser features appropriately.  This means
 * that you can routinely put filters like "nsfix", "validate", or "wf" at the
 * front of a pipeline (for components that need inputs conditioned to match
 * that level of correctness), and know that it won't actually be used unless
 * it's absolutely necessary.
 *
 * @author David Brownell
 */
public class PipelineFactory
{
    /**
     * Creates a simple pipeline according to the description string passed in.
     */
    public static EventConsumer createPipeline (String description)
    throws IOException
    {
        return createPipeline (description, null);
    }

    /**
     * Extends an existing pipeline by prepending the filter pipeline to the
     * specified consumer.  Some pipelines need more customization than can
     * be done through this simplified syntax.  When they are set up with
     * direct API calls, use this method to merge more complex pipeline
     * segments with easily configured ones.
     */
    public static EventConsumer createPipeline (
        String          description,
        EventConsumer   next
    ) throws IOException
    {
        // tokens are (for now) what's separated by whitespace;
        // very easy to parse, but IDs never have spaces.

        StringTokenizer         tokenizer;
        String                  tokens [];

        tokenizer = new StringTokenizer (description);
        tokens = new String [tokenizer.countTokens ()];
        for (int i = 0; i < tokens.length; i++)
            tokens [i] = tokenizer.nextToken ();

        PipelineFactory         factory = new PipelineFactory ();
        Pipeline                pipeline = factory.parsePipeline (tokens, next);

        return pipeline.createPipeline ();
    }


    private PipelineFactory () { /* NYET */ }


    /**
     * Extends an existing pipeline by prepending a pre-tokenized filter
     * pipeline to the specified consumer.  Tokens are class names (or the
     * predefined aliases) left and right parenthesis, and the vertical bar.
     */
    public static EventConsumer createPipeline (
        String          tokens [],
        EventConsumer   next
    ) throws IOException
    {
        PipelineFactory         factory = new PipelineFactory ();
        Pipeline                pipeline = factory.parsePipeline (tokens, next);

        return pipeline.createPipeline ();
    }


    private String              tokens [];
    private int                 index;

    private Pipeline parsePipeline (String toks [], EventConsumer next)
    {
        tokens = toks;
        index = 0;

        Pipeline retval = parsePipeline (next);

        if (index != toks.length)
            throw new ArrayIndexOutOfBoundsException (
                    "extra token: " + tokens [index]);
        return retval;
    }

    // pipeline  ::= stage | stage '|' pipeline
    private Pipeline parsePipeline (EventConsumer next)
    {
        Pipeline        retval = new Pipeline (parseStage ());

        // minimal pipelines:  "stage" and "... | id"
        if (index > (tokens.length - 2)
                || !"|".equals (tokens [index])
                ) {
            retval.next = next;
            return retval;
        }
        index++;
        retval.rest = parsePipeline (next);
        return retval;
    }

    // stage     ::= id    | id '(' pipeline ')'
    private Stage parseStage ()
    {
        Stage           retval = new Stage (tokens [index++]);

        // minimal stages:  "id" and "id ( id )"
        if (index > (tokens.length - 2)
                || !"(".equals (tokens [index]) /*)*/
                )
            return retval;

        index++;
        retval.param = parsePipeline (null);
        if (index >= tokens.length)
            throw new ArrayIndexOutOfBoundsException (
                    "missing right paren");
        if (/*(*/ !")".equals (tokens [index++]))
            throw new ArrayIndexOutOfBoundsException (
                    "required right paren, not: " + tokens [index - 1]);
        return retval;
    }


    //
    // these classes obey the conventions for constructors, so they're
    // only built in to this table of shortnames
    //
    //  - filter (one or two types of arglist)
    //     * last constructor is 'next' element
    //     * optional (first) string parameter
    //
    //  - terminus (one or types of arglist)
    //     * optional (only) string parameter
    //
    // terminus stages are transformed into filters if needed, by
    // creating a "tee".  filter stages aren't turned to terminus
    // stages though; either eliminate such stages, or add some
    // terminus explicitly.
    //
    private static final String builtinStages [][] = {
        { "dom",        "gnu.xml.dom.Consumer" },
        { "nsfix",      "gnu.xml.pipeline.NSFilter" },
        { "null",       "gnu.xml.pipeline.EventFilter" },
        { "server",     "gnu.xml.pipeline.CallFilter" },
        { "tee",        "gnu.xml.pipeline.TeeConsumer" },
        { "validate",   "gnu.xml.pipeline.ValidationConsumer" },
        { "wf",         "gnu.xml.pipeline.WellFormednessFilter" },
        { "xinclude",   "gnu.xml.pipeline.XIncludeFilter" },
        { "xslt",       "gnu.xml.pipeline.XsltFilter" },

// XXX want:  option for validate, to preload external part of a DTD

            //  xhtml, write ... nyet generic-ready
    };

    private static class Stage
    {
        String          id;
        Pipeline        param;

        Stage (String name)
            {  id = name; }

        public String toString ()
        {
            if (param == null)
                return id;
            return id + " ( " + param + " )";
        }

        private void fail (String message)
        throws IOException
        {
            throw new IOException ("in '" + id
                    + "' stage of pipeline, " + message);
        }

        EventConsumer createStage (EventConsumer next)
        throws IOException
        {
            String       name = id;

            // most builtins are just class aliases
            for (int i = 0; i < builtinStages.length; i++) {
                if (id.equals (builtinStages [i][0])) {
                    name = builtinStages [i][1];
                    break;
                }
            }

            // Save output as XML or XHTML text
            if ("write".equals (name) || "xhtml".equals (name)) {
                String          filename;
                boolean         isXhtml = "xhtml".equals (name);
                OutputStream    out = null;
                TextConsumer    consumer;

                if (param == null)
                    fail ("parameter is required");

                filename = param.toString ();
                if ("stdout".equals (filename))
                    out = System.out;
                else if ("stderr".equals (filename))
                    out = System.err;
                else {
                    File f = new File (filename);

/*
                    if (!f.isAbsolute ())
                        fail ("require absolute file paths");
 */
                    if (f.exists ())
                        fail ("file already exists: " + f.getName ());

// XXX this races against the existence test
                    out = new FileOutputStream (f);
                }

                if (!isXhtml)
                    consumer = new TextConsumer (out);
                else
                    consumer = new TextConsumer (
                        new OutputStreamWriter (out, "8859_1"),
                        true);

                consumer.setPrettyPrinting (true);
                if (next == null)
                    return consumer;
                return new TeeConsumer (consumer, next);

            } else {
                //
                // Here go all the builtins that are just aliases for
                // classes, and all stage IDs that started out as such
                // class names.  The following logic relies on several
                // documented conventions for constructor invocation.
                //
                String          msg = null;

                try {
                    Class       klass = Class.forName (name);
                    Class       argTypes [] = null;
                    Constructor constructor = null;
                    boolean     filter = false;
                    Object      params [] = null;
                    Object      obj = null;

                    // do we need a filter stage?
                    if (next != null) {
                        // "next" consumer is always passed, with
                        // or without the optional string param
                        if (param == null) {
                            argTypes = new Class [1];
                            argTypes [0] = EventConsumer.class;

                            params = new Object [1];
                            params [0] = next;

                            msg = "no-param filter";
                        } else {
                            argTypes = new Class [2];
                            argTypes [0] = String.class;
                            argTypes [1] = EventConsumer.class;

                            params = new Object [2];
                            params [0] = param.toString ();
                            params [1] = next;

                            msg = "one-param filter";
                        }


                        try {
                            constructor = klass.getConstructor (argTypes);
                        } catch (NoSuchMethodException e) {
                            // try creating a filter from a
                            // terminus and a tee
                            filter = true;
                            msg += " built from ";
                        }
                    }

                    // build from a terminus stage, with or
                    // without the optional string param
                    if (constructor == null) {
                        String  tmp;

                        if (param == null) {
                            argTypes = new Class [0];
                            params = new Object [0];

                            tmp = "no-param terminus";
                        } else {
                            argTypes = new Class [1];
                            argTypes [0] = String.class;

                            params = new Object [1];
                            params [0] = param.toString ();

                            tmp = "one-param terminus";
                        }
                        if (msg == null)
                            msg = tmp;
                        else
                            msg += tmp;
                        constructor = klass.getConstructor (argTypes);
                            // NOT creating terminus by dead-ending
                            // filters ... users should think about
                            // that one, something's likely wrong
                    }

                    obj = constructor.newInstance (params);

                    // return EventConsumers directly, perhaps after
                    // turning them into a filter
                    if (obj instanceof EventConsumer) {
                        if (filter)
                            return new TeeConsumer ((EventConsumer) obj, next);
                        return (EventConsumer) obj;
                    }

                    // if it's not a handler, it's an error
                    // we can wrap handlers in a filter
                    EventFilter         retval = new EventFilter ();
                    boolean             updated = false;

                    if (obj instanceof ContentHandler) {
                        retval.setContentHandler ((ContentHandler) obj);
                        updated = true;
                    }
                    if (obj instanceof DTDHandler) {
                        retval.setDTDHandler ((DTDHandler) obj);
                        updated = true;
                    }
                    if (obj instanceof LexicalHandler) {
                        retval.setProperty (
                            EventFilter.PROPERTY_URI + "lexical-handler",
                            obj);
                        updated = true;
                    }
                    if (obj instanceof DeclHandler) {
                        retval.setProperty (
                            EventFilter.PROPERTY_URI + "declaration-handler",
                            obj);
                        updated = true;
                    }

                    if (!updated)
                        fail ("class is neither Consumer nor Handler");

                    if (filter)
                        return new TeeConsumer (retval, next);
                    return retval;

                } catch (IOException e) {
                    throw e;

                } catch (NoSuchMethodException e) {
                    fail (name + " constructor missing -- " + msg);

                } catch (ClassNotFoundException e) {
                    fail (name + " class not found");

                } catch (Exception e) {
                    // e.printStackTrace ();
                    fail ("stage not available: " + e.getMessage ());
                }
            }
            // NOTREACHED
            return null;
        }
    }

    private static class Pipeline
    {
        Stage           stage;

        // rest may be null
        Pipeline        rest;
        EventConsumer   next;

        Pipeline (Stage s)
            { stage = s; }

        public String toString ()
        {
            if (rest == null && next == null)
                return stage.toString ();
            if (rest != null)
                return stage + " | " + rest;
            throw new IllegalArgumentException ("next");
        }

        EventConsumer createPipeline ()
        throws IOException
        {
            if (next == null) {
                if (rest == null)
                    next = stage.createStage (null);
                else
                    next = stage.createStage (rest.createPipeline ());
            }
            return next;
        }
    }

/*
    public static void main (String argv [])
    {
        try {
            // three basic terminus cases
            createPipeline ("null");
            createPipeline ("validate");
            createPipeline ("write ( stdout )");

            // four basic filters
            createPipeline ("nsfix | write ( stderr )");
            createPipeline ("wf | null");
            createPipeline ("null | null");
            createPipeline (
"call ( http://www.example.com/services/xml-1a ) | xhtml ( stdout )");

            // tee junctions
            createPipeline ("tee ( validate ) | write ( stdout )");
            createPipeline ("tee ( nsfix | write ( stdout ) ) | validate");

            // longer pipeline
            createPipeline ("nsfix | tee ( validate ) | write ( stdout )");
            createPipeline (
                "null | wf | nsfix | tee ( validate ) | write ( stdout )");

            // try some parsing error cases
            try {
                createPipeline ("null (");              // extra token '('
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }

            try {
                createPipeline ("nsfix |");             // extra token '|'
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }

            try {
                createPipeline ("xhtml ( foo");         // missing right paren
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }

            try {
                createPipeline ("xhtml ( foo bar");     // required right paren
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }

            try {
                createPipeline ("tee ( nsfix | validate");// missing right paren
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }

            // try some construction error cases

            try {
                createPipeline ("call");                // missing param
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }
            try {
                createPipeline ("call ( foobar )");     // broken param
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }
            try {
                createPipeline ("nsfix ( foobar )");    // illegal param
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }
            try {
                createPipeline ("null ( foobar )");     // illegal param
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }
            try {
                createPipeline ("wf ( foobar )");       // illegal param
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }
            try {
                createPipeline ("xhtml ( foobar.html )");
                new File ("foobar.html").delete ();
                // now supported
            } catch (Exception e) {
                System.err.println ("** err: " + e.getMessage ()); }
            try {
                createPipeline ("xhtml");               // missing param
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }
            try {
                createPipeline ("write ( stdout ) | null");     // nonterminal
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }
            try {
                createPipeline ("validate | null");
                // now supported
            } catch (Exception e) {
                System.err.println ("** err: " + e.getMessage ()); }
            try {
                createPipeline ("validate ( foo )");    // illegal param
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }
            try {
                createPipeline ("tee");                 // missing param
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }
            try {
                    // only builtins so far
                createPipeline ("com.example.xml.FilterClass");
                System.err.println ("** didn't report error");
            } catch (Exception e) {
                System.err.println ("== err: " + e.getMessage ()); }

        } catch (Exception e) {
            e.printStackTrace ();
        }
    }
/**/

}