View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.maven.doxia;
20  
21  import java.io.Reader;
22  
23  import org.apache.maven.doxia.parser.ParseException;
24  import org.apache.maven.doxia.parser.Parser;
25  import org.apache.maven.doxia.parser.manager.ParserNotFoundException;
26  import org.apache.maven.doxia.sink.Sink;
27  
28  /**
29   * Basic interface of the Doxia framework.
30   *
31   * @author Jason van Zyl
32   * @since 1.0
33   */
34  public interface Doxia {
35  
36      /**
37       * Parses the given source model using a parser with given id,
38       * and emits Doxia events into the given sink.
39       *
40       * @param source not null reader that provides the source document
41       * @param parserId identifier for the parser to use
42       * @param sink a sink that consumes the Doxia events
43       * @throws ParserNotFoundException if no parser could be found for the given id
44       * @throws ParseException if the model could not be parsed
45       */
46      void parse(Reader source, String parserId, Sink sink) throws ParserNotFoundException, ParseException;
47  
48      /**
49       * Parses the given source model using a parser with given id,
50       * and emits Doxia events into the given sink.
51       *
52       * @param source not null reader that provides the source document
53       * @param parserId identifier for the parser to use
54       * @param sink a sink that consumes the Doxia events
55       * @param reference string containing the reference to the source (e.g. filename)
56       * @throws ParserNotFoundException if no parser could be found for the given id
57       * @throws ParseException if the model could not be parsed
58       */
59      void parse(Reader source, String parserId, Sink sink, String reference)
60              throws ParserNotFoundException, ParseException;
61  
62      /**
63       * Return a parser for the given <code>parserId</code>.
64       *
65       * @param parserId identifier for the parser to use
66       * @return the parser identified by parserId
67       * @throws ParserNotFoundException if no parser could be found for the given id
68       */
69      Parser getParser(String parserId) throws ParserNotFoundException;
70  }