001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.dbutils;
018
019import java.io.IOException;
020import java.io.InputStream;
021import java.util.HashMap;
022import java.util.Map;
023import java.util.Properties;
024import java.util.regex.Pattern;
025
026/**
027 * {@code QueryLoader} is a registry for sets of queries so
028 * that multiple copies of the same queries aren't loaded into memory.
029 * This implementation loads properties files filled with query name to
030 * SQL mappings.  This class is thread safe.
031 */
032public class QueryLoader {
033
034    /**
035     * The Singleton instance of this class.
036     */
037    private static final QueryLoader instance = new QueryLoader();
038
039    /**
040     * Matches .xml file extensions.
041     */
042    private static final Pattern dotXml = Pattern.compile(".+\\.[xX][mM][lL]");
043
044    /**
045     * Return an instance of this class.
046     * @return The Singleton instance.
047     */
048    public static QueryLoader instance() {
049        return instance;
050    }
051
052    /**
053     * Maps query set names to Maps of their queries.
054     */
055    private final Map<String, Map<String, String>> queries = new HashMap<>();
056
057    /**
058     * QueryLoader constructor.
059     */
060    protected QueryLoader() {
061        super();
062    }
063
064    /**
065     * Loads a Map of query names to SQL values.  The Maps are cached so a
066     * subsequent request to load queries from the same path will return
067     * the cached Map.  The properties file to load can be in either
068     * line-oriented or XML format.  XML formatted properties files must use a
069     * {@code .xml} file extension.
070     *
071     * @param path The path that the ClassLoader will use to find the file.
072     * This is <strong>not</strong> a file system path.  If you had a jarred
073     * Queries.properties file in the com.yourcorp.app.jdbc package you would
074     * pass "/com/yourcorp/app/jdbc/Queries.properties" to this method.
075     * @throws IOException if a file access error occurs
076     * @throws IllegalArgumentException if the ClassLoader can't find a file at
077     * the given path.
078     * @throws java.util.InvalidPropertiesFormatException if the XML properties file is
079     * invalid
080     * @return Map of query names to SQL values
081     * @see java.util.Properties
082     */
083    public synchronized Map<String, String> load(final String path) throws IOException {
084
085        Map<String, String> queryMap = this.queries.get(path);
086
087        if (queryMap == null) {
088            queryMap = this.loadQueries(path);
089            this.queries.put(path, queryMap);
090        }
091
092        return queryMap;
093    }
094
095    /**
096     * Loads a set of named queries into a Map object.  This implementation
097     * reads a properties file at the given path.  The properties file can be
098     * in either line-oriented or XML format.  XML formatted properties files
099     * must use a {@code .xml} file extension.
100
101     * @param path The path that the ClassLoader will use to find the file.
102     * @throws IOException if a file access error occurs
103     * @throws IllegalArgumentException if the ClassLoader can't find a file at
104     * the given path.
105     * @throws java.util.InvalidPropertiesFormatException if the XML properties file is
106     * invalid
107     * @since DbUtils 1.1
108     * @return Map of query names to SQL values
109     * @see java.util.Properties
110     */
111    protected Map<String, String> loadQueries(final String path) throws IOException {
112        // Findbugs flags getClass().getResource as a bad practice; maybe we should change the API?
113        final Properties props;
114        try (InputStream in = getClass().getResourceAsStream(path)) {
115
116            if (in == null) {
117                throw new IllegalArgumentException(path + " not found.");
118            }
119            props = new Properties();
120            if (dotXml.matcher(path).matches()) {
121                props.loadFromXML(in);
122            } else {
123                props.load(in);
124            }
125        }
126
127        // Copy to HashMap for better performance
128
129        @SuppressWarnings({"rawtypes", "unchecked" }) // load() always creates <String,String> entries
130        final
131        HashMap<String, String> hashMap = new HashMap(props);
132        return hashMap;
133    }
134
135    /**
136     * Removes the queries for the given path from the cache.
137     * @param path The path that the queries were loaded from.
138     */
139    public synchronized void unload(final String path) {
140        this.queries.remove(path);
141    }
142
143}