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 }