AbstractPropertiesFactory.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  17. package org.apache.commons.collections4.properties;

  18. import java.io.File;
  19. import java.io.FileNotFoundException;
  20. import java.io.IOException;
  21. import java.io.InputStream;
  22. import java.io.Reader;
  23. import java.net.URI;
  24. import java.net.URL;
  25. import java.nio.file.Files;
  26. import java.nio.file.Path;
  27. import java.nio.file.Paths;
  28. import java.util.Objects;
  29. import java.util.Properties;

  30. /**
  31.  * Subclasses create and load {@link Properties} and subclasses of {@link Properties} like {@link SortedProperties}.
  32.  *
  33.  * @param <T> {@link Properties} or a subclass like {@link SortedProperties}.
  34.  * @see Properties
  35.  * @since 4.4
  36.  */
  37. public abstract class AbstractPropertiesFactory<T extends Properties> {

  38.     /**
  39.      * Enumerates property formats.
  40.      *
  41.      * @since 4.5.0-M1
  42.      */
  43.     public enum PropertyFormat {

  44.         /** Properties file format. */
  45.         PROPERTIES,

  46.         /** XML file format. */
  47.         XML;

  48.         static PropertyFormat toPropertyFormat(final String fileName) {
  49.             return Objects.requireNonNull(fileName, "fileName").endsWith(".xml") ? XML : PROPERTIES;
  50.         }
  51.     }

  52.     /**
  53.      * Constructs an instance.
  54.      */
  55.     protected AbstractPropertiesFactory() {
  56.         // no init.
  57.     }

  58.     /**
  59.      * Subclasses override to provide customized properties instances.
  60.      *
  61.      * @return a new Properties instance.
  62.      */
  63.     protected abstract T createProperties();

  64.     /**
  65.      * Creates and loads properties from the given file.
  66.      *
  67.      * @param classLoader the class loader to use to get the named resource.
  68.      * @param name        the location of the properties file.
  69.      * @return a new properties object.
  70.      * @throws IOException              Thrown if an error occurred reading the input stream.
  71.      * @throws IllegalArgumentException Thrown if the input contains a malformed Unicode escape sequence.
  72.      */
  73.     public T load(final ClassLoader classLoader, final String name) throws IOException {
  74.         try (InputStream inputStream = classLoader.getResourceAsStream(name)) {
  75.             return load(inputStream, PropertyFormat.toPropertyFormat(name));
  76.         }
  77.     }

  78.     /**
  79.      * Creates and loads properties from the given file.
  80.      *
  81.      * @param file the location of the properties file.
  82.      * @return a new properties object.
  83.      * @throws IOException              Thrown if an error occurred reading the input stream.
  84.      * @throws IllegalArgumentException Thrown if the input contains a malformed Unicode escape sequence.
  85.      * @throws FileNotFoundException    Thrown if the file does not exist, is a directory, or cannot be opened for
  86.      *                                  reading.
  87.      * @throws SecurityException        Thrown if a security manager's {@code checkRead} method denies read access to
  88.      *                                  the file.
  89.      */
  90.     public T load(final File file) throws FileNotFoundException, IOException {
  91.         return load(file.toPath());
  92.     }

  93.     /**
  94.      * Creates and loads properties from the given input stream.
  95.      *
  96.      * @param inputStream the location of the properties file.
  97.      * @return a new properties object.
  98.      * @throws IOException              Thrown if an error occurred reading the input stream.
  99.      * @throws IllegalArgumentException Thrown if the input contains a malformed Unicode escape sequence.
  100.      */
  101.     public T load(final InputStream inputStream) throws IOException {
  102.         if (inputStream == null) {
  103.             return null;
  104.         }
  105.         final T properties = createProperties();
  106.         properties.load(inputStream);
  107.         return properties;
  108.     }

  109.     /**
  110.      * Creates and loads properties from the given input stream.
  111.      *
  112.      * @param inputStream the location of the properties file.
  113.      * @param propertyFormat The format of the given file.
  114.      * @return a new properties object.
  115.      * @throws IOException              Thrown if an error occurred reading the input stream.
  116.      * @throws IllegalArgumentException Thrown if the input contains a malformed Unicode escape sequence.
  117.      * @since 4.5.0-M1
  118.      */
  119.     public T load(final InputStream inputStream, final PropertyFormat propertyFormat) throws IOException {
  120.         if (inputStream == null) {
  121.             return null;
  122.         }
  123.         final T properties = createProperties();
  124.         if (propertyFormat == PropertyFormat.XML) {
  125.             properties.loadFromXML(inputStream);
  126.         } else {
  127.             properties.load(inputStream);
  128.         }
  129.         return properties;
  130.     }

  131.     /**
  132.      * Creates and loads properties from the given path.
  133.      *
  134.      * @param path the location of the properties file.
  135.      * @return a new properties object.
  136.      * @throws IOException              Thrown if an error occurred reading the input stream.
  137.      * @throws IllegalArgumentException Thrown if the input contains a malformed Unicode escape sequence.
  138.      */
  139.     public T load(final Path path) throws IOException {
  140.         try (InputStream inputStream = Files.newInputStream(path)) {
  141.             return load(inputStream, PropertyFormat.toPropertyFormat(Objects.toString(path.getFileName(), null)));
  142.         }
  143.     }

  144.     /**
  145.      * Creates and loads properties from the given reader.
  146.      *
  147.      * @param reader the location of the properties file.
  148.      * @return a new properties object.
  149.      * @throws IOException              Thrown if an error occurred reading the input stream.
  150.      * @throws IllegalArgumentException Thrown if the input contains a malformed Unicode escape sequence.
  151.      */
  152.     public T load(final Reader reader) throws IOException {
  153.         final T properties = createProperties();
  154.         properties.load(reader);
  155.         return properties;
  156.     }

  157.     /**
  158.      * Creates and loads properties from the given file name.
  159.      *
  160.      * @param name the location of the properties file.
  161.      * @return a new properties object.
  162.      * @throws IOException              Thrown if an error occurred reading the input stream.
  163.      * @throws IllegalArgumentException Thrown if the input contains a malformed Unicode escape sequence.
  164.      */
  165.     public T load(final String name) throws IOException {
  166.         return load(Paths.get(name));
  167.     }

  168.     /**
  169.      * Creates and loads properties from the given URI.
  170.      *
  171.      * @param uri the location of the properties file.
  172.      * @return a new properties object.
  173.      * @throws IOException              Thrown if an error occurred reading the input stream.
  174.      * @throws IllegalArgumentException Thrown if the input contains a malformed Unicode escape sequence.
  175.      */
  176.     public T load(final URI uri) throws IOException {
  177.         return load(Paths.get(uri));
  178.     }

  179.     /**
  180.      * Creates and loads properties from the given URL.
  181.      *
  182.      * @param url the location of the properties file.
  183.      * @return a new properties object.
  184.      * @throws IOException              Thrown if an error occurred reading the input stream.
  185.      * @throws IllegalArgumentException Thrown if the input contains a malformed Unicode escape sequence.
  186.      */
  187.     public T load(final URL url) throws IOException {
  188.         try (InputStream inputStream = url.openStream()) {
  189.             return load(inputStream, PropertyFormat.toPropertyFormat(url.getFile()));
  190.         }
  191.     }

  192. }