001    package org.apache.maven.settings.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.settings.Settings;
029    
030    /**
031     * Handles deserialization of settings from some kind of textual format like XML.
032     * 
033     * @author Benjamin Bentmann
034     */
035    public interface SettingsReader
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.settings.io.isStrict";
043    
044        /**
045         * Reads the settings from the specified file.
046         * 
047         * @param input The file to deserialize the settings from, must not be {@code null}.
048         * @param options The options to use for deserialization, may be {@code null} to use the default values.
049         * @return The deserialized settings, never {@code null}.
050         * @throws IOException If the settings could not be deserialized.
051         * @throws SettingsParseException If the input format could not be parsed.
052         */
053        Settings read( File input, Map<String, ?> options )
054            throws IOException, SettingsParseException;
055    
056        /**
057         * Reads the settings from the specified character reader. The reader will be automatically closed before the method
058         * returns.
059         * 
060         * @param input The reader to deserialize the settings from, must not be {@code null}.
061         * @param options The options to use for deserialization, may be {@code null} to use the default values.
062         * @return The deserialized settings, never {@code null}.
063         * @throws IOException If the settings could not be deserialized.
064         * @throws SettingsParseException If the input format could not be parsed.
065         */
066        Settings read( Reader input, Map<String, ?> options )
067            throws IOException, SettingsParseException;
068    
069        /**
070         * Reads the settings from the specified byte stream. The stream will be automatically closed before the method
071         * returns.
072         * 
073         * @param input The stream to deserialize the settings from, must not be {@code null}.
074         * @param options The options to use for deserialization, may be {@code null} to use the default values.
075         * @return The deserialized settings, never {@code null}.
076         * @throws IOException If the settings could not be deserialized.
077         * @throws SettingsParseException If the input format could not be parsed.
078         */
079        Settings read( InputStream input, Map<String, ?> options )
080            throws IOException, SettingsParseException;
081    
082    }