001    package org.apache.maven.artifact.repository.metadata.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.artifact.repository.metadata.Metadata;
029    
030    /**
031     * Handles deserialization of metadata from some kind of textual format like XML.
032     *
033     * @author Benjamin Bentmann
034     */
035    public interface MetadataReader
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        final String IS_STRICT = "org.apache.maven.artifact.repository.metadata.io.isStrict";
043    
044        /**
045         * Reads the metadata from the specified file.
046         *
047         * @param input The file to deserialize the metadata 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 metadata, never {@code null}.
050         * @throws IOException If the metadata could not be deserialized.
051         * @throws MetadataParseException If the input format could not be parsed.
052         */
053        Metadata read( File input, Map<String, ?> options )
054            throws IOException, MetadataParseException;
055    
056        /**
057         * Reads the metadata 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 metadata 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 metadata, never {@code null}.
063         * @throws IOException If the metadata could not be deserialized.
064         * @throws MetadataParseException If the input format could not be parsed.
065         */
066        Metadata read( Reader input, Map<String, ?> options )
067            throws IOException, MetadataParseException;
068    
069        /**
070         * Reads the metadata 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 metadata 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 metadata, never {@code null}.
076         * @throws IOException If the metadata could not be deserialized.
077         * @throws MetadataParseException If the input format could not be parsed.
078         */
079        Metadata read( InputStream input, Map<String, ?> options )
080            throws IOException, MetadataParseException;
081    
082    }