001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019package org.apache.maven.doxia; 020 021import java.io.Reader; 022 023import org.apache.maven.doxia.parser.ParseException; 024import org.apache.maven.doxia.parser.Parser; 025import org.apache.maven.doxia.parser.manager.ParserNotFoundException; 026import org.apache.maven.doxia.sink.Sink; 027 028/** 029 * Basic interface of the Doxia framework. 030 * 031 * @author Jason van Zyl 032 * @since 1.0 033 */ 034public interface Doxia { 035 036 /** 037 * Parses the given source model using a parser with given id, 038 * and emits Doxia events into the given sink. 039 * 040 * @param source not null reader that provides the source document 041 * @param parserId identifier for the parser to use 042 * @param sink a sink that consumes the Doxia events 043 * @throws ParserNotFoundException if no parser could be found for the given id 044 * @throws ParseException if the model could not be parsed 045 */ 046 void parse(Reader source, String parserId, Sink sink) throws ParserNotFoundException, ParseException; 047 048 /** 049 * Parses the given source model using a parser with given id, 050 * and emits Doxia events into the given sink. 051 * 052 * @param source not null reader that provides the source document 053 * @param parserId identifier for the parser to use 054 * @param sink a sink that consumes the Doxia events 055 * @param reference string containing the reference to the source (e.g. filename) 056 * @throws ParserNotFoundException if no parser could be found for the given id 057 * @throws ParseException if the model could not be parsed 058 */ 059 void parse(Reader source, String parserId, Sink sink, String reference) 060 throws ParserNotFoundException, ParseException; 061 062 /** 063 * Return a parser for the given <code>parserId</code>. 064 * 065 * @param parserId identifier for the parser to use 066 * @return the parser identified by parserId 067 * @throws ParserNotFoundException if no parser could be found for the given id 068 */ 069 Parser getParser(String parserId) throws ParserNotFoundException; 070}