001    package org.apache.maven.model.io;
002    
003    /*
004     * Licensed to the Apache Software Foundation (ASF) under one
005     * or more contributor license agreements.  See the NOTICE file
006     * distributed with this work for additional information
007     * regarding copyright ownership.  The ASF licenses this file
008     * to you under the Apache License, Version 2.0 (the
009     * "License"); you may not use this file except in compliance
010     * with the License.  You may obtain a copy of the License at
011     *
012     *   http://www.apache.org/licenses/LICENSE-2.0
013     *
014     * Unless required by applicable law or agreed to in writing,
015     * software distributed under the License is distributed on an
016     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017     * KIND, either express or implied.  See the License for the
018     * specific language governing permissions and limitations
019     * under the License.
020     */
021    
022    import java.io.File;
023    import java.io.IOException;
024    import java.io.InputStream;
025    import java.io.Reader;
026    import java.util.Map;
027    
028    import org.apache.maven.model.Model;
029    
030    /**
031     * Handles deserialization of a model from some kind of textual format like XML.
032     *
033     * @author Benjamin Bentmann
034     */
035    public interface ModelReader
036    {
037    
038        /**
039         * The key for the option to enable strict parsing. This option is of type {@link Boolean} and defaults to {@code
040         * true}. If {@code false}, unknown elements will be ignored instead of causing a failure.
041         */
042        String IS_STRICT = "org.apache.maven.model.io.isStrict";
043    
044        /**
045         * The key for the option to enable tracking of line/column numbers. This option is of type
046         * {@link org.apache.maven.model.InputSource} and defaults to {@code null}. Providing an input source enables
047         * location tracking.
048         */
049        String INPUT_SOURCE = "org.apache.maven.model.io.inputSource";
050    
051        /**
052         * Reads the model from the specified file.
053         *
054         * @param input The file to deserialize the model from, must not be {@code null}.
055         * @param options The options to use for deserialization, may be {@code null} to use the default values.
056         * @return The deserialized model, never {@code null}.
057         * @throws IOException If the model could not be deserialized.
058         * @throws ModelParseException If the input format could not be parsed.
059         */
060        Model read( File input, Map<String, ?> options )
061            throws IOException, ModelParseException;
062    
063        /**
064         * Reads the model from the specified character reader. The reader will be automatically closed before the method
065         * returns.
066         *
067         * @param input The reader to deserialize the model from, must not be {@code null}.
068         * @param options The options to use for deserialization, may be {@code null} to use the default values.
069         * @return The deserialized model, never {@code null}.
070         * @throws IOException If the model could not be deserialized.
071         * @throws ModelParseException If the input format could not be parsed.
072         */
073        Model read( Reader input, Map<String, ?> options )
074            throws IOException, ModelParseException;
075    
076        /**
077         * Reads the model from the specified byte stream. The stream will be automatically closed before the method
078         * returns.
079         *
080         * @param input The stream to deserialize the model from, must not be {@code null}.
081         * @param options The options to use for deserialization, may be {@code null} to use the default values.
082         * @return The deserialized model, never {@code null}.
083         * @throws IOException If the model could not be deserialized.
084         * @throws ModelParseException If the input format could not be parsed.
085         */
086        Model read( InputStream input, Map<String, ?> options )
087            throws IOException, ModelParseException;
088    
089    }