1 /*

     2  * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package sun.util.spi;

    27 

    28 import java.util.Properties;

    29 import java.util.InvalidPropertiesFormatException;

    30 import java.io.InputStream;

    31 import java.io.OutputStream;

    32 import java.io.IOException;

    33 

    34 /**

    35  * Service-provider class for loading and storing {@link Properites} in XML

    36  * format.

    37  *

    38  * @see Properties#loadFromXML

    39  * @see Properties#storeToXML

    40  */

    41 

    42 public abstract class XmlPropertiesProvider {

    43 

    44     /**

    45      * Initializes a new instance of this class.

    46      */

    47     protected XmlPropertiesProvider() {

    48         // do nothing for now

    49     }

    50 

    51     /**

    52      * Loads all of the properties represented by the XML document on the

    53      * specified input stream into a properties table.

    54      *

    55      * @param props the properties table to populate

    56      * @param in the input stream from which to read the XML document

    57      * @throws IOException if reading from the specified input stream fails

    58      * @throws java.io.UnsupportedEncodingException if the document's encoding

    59      *         declaration can be read and it specifies an encoding that is not

    60      *         supported

    61      * @throws InvalidPropertiesFormatException Data on input stream does not

    62      *         constitute a valid XML document with the mandated document type.

    63      *

    64      * @see Properties#loadFromXML

    65      */

    66     public abstract void load(Properties props, InputStream in)

    67         throws IOException, InvalidPropertiesFormatException;

    68 

    69     /**

    70      * Emits an XML document representing all of the properties in a given

    71      * table.

    72      *

    73      * @param props the properies to store

    74      * @param out the output stream on which to emit the XML document.

    75      * @param comment  a description of the property list, can be @{code null}

    76      * @param encoding the name of a supported character encoding

    77      *

    78      * @throws IOException if writing to the specified output stream fails

    79      * @throws java.io.UnsupportedEncodingException if the encoding is not

    80      *         supported by the implementation

    81      * @throws NullPointerException if {@code out} is null.

    82      * @throws ClassCastException  if this {@code Properties} object

    83      *         contains any keys or values that are not

    84      *         {@code Strings}.

    85      *

    86      * @see Properties#storeToXML

    87      */

    88     public abstract void store(Properties props, OutputStream out,

    89                                String comment, String encoding)

    90         throws IOException;

    91 }