001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.shiro.config;
020
021import org.apache.shiro.io.ResourceUtils;
022import org.apache.shiro.util.AbstractFactory;
023import org.apache.shiro.util.CollectionUtils;
024import org.apache.shiro.util.Factory;
025import org.slf4j.Logger;
026import org.slf4j.LoggerFactory;
027
028/**
029 * Base support class for {@link Factory} implementations that generate their instance(s) based on
030 * {@link Ini} configuration.
031 *
032 * @since 1.0
033 */
034public abstract class IniFactorySupport<T> extends AbstractFactory<T> {
035
036    public static final String DEFAULT_INI_RESOURCE_PATH = "classpath:shiro.ini";
037
038    private static transient final Logger log = LoggerFactory.getLogger(IniFactorySupport.class);
039
040    private Ini ini;
041
042    protected IniFactorySupport() {
043    }
044
045    protected IniFactorySupport(Ini ini) {
046        this.ini = ini;
047    }
048
049    public Ini getIni() {
050        return ini;
051    }
052
053    public void setIni(Ini ini) {
054        this.ini = ini;
055    }
056
057    /**
058     * Returns a new Ini instance created from the default {@code classpath:shiro.ini} file, or {@code null} if
059     * the file does not exist.
060     *
061     * @return a new Ini instance created from the default {@code classpath:shiro.ini} file, or {@code null} if
062     *         the file does not exist.
063     */
064    public static Ini loadDefaultClassPathIni() {
065        Ini ini = null;
066        if (ResourceUtils.resourceExists(DEFAULT_INI_RESOURCE_PATH)) {
067            log.debug("Found shiro.ini at the root of the classpath.");
068            ini = new Ini();
069            ini.loadFromPath(DEFAULT_INI_RESOURCE_PATH);
070            if (CollectionUtils.isEmpty(ini)) {
071                log.warn("shiro.ini found at the root of the classpath, but it did not contain any data.");
072            }
073        }
074        return ini;
075    }
076
077    /**
078     * Tries to resolve the Ini instance to use for configuration.  This implementation functions as follows:
079     * <ol>
080     * <li>The {@code Ini} instance returned from {@link #getIni()} will be returned if it is not null or empty.</li>
081     * <li>If {@link #getIni()} is {@code null} or empty, this implementation will attempt to find and load the
082     * {@link #loadDefaultClassPathIni() default class path Ini}.</li>
083     * <li>If neither of the two attempts above returns an instance, {@code null} is returned</li>
084     * </ol>
085     *
086     * @return the Ini instance to use for configuration.
087     */
088    protected Ini resolveIni() {
089        Ini ini = getIni();
090        if (CollectionUtils.isEmpty(ini)) {
091            log.debug("Null or empty Ini instance.  Falling back to the default {} file.", DEFAULT_INI_RESOURCE_PATH);
092            ini = loadDefaultClassPathIni();
093        }
094        return ini;
095    }
096
097    /**
098     * Creates a new object instance by using a configured INI source.  This implementation functions as follows:
099     * <ol>
100     * <li>{@link #resolveIni() Resolve} the {@code Ini} source to use for configuration.</li>
101     * <li>If there was no resolved Ini source, create and return a simple default instance via the
102     * {@link #createDefaultInstance()} method.</li>
103     * </ol>
104     *
105     * @return a new {@code SecurityManager} instance by using a configured INI source.
106     */
107    public T createInstance() {
108        Ini ini = resolveIni();
109
110        T instance;
111
112        if (CollectionUtils.isEmpty(ini)) {
113            log.debug("No populated Ini available.  Creating a default instance.");
114            instance = createDefaultInstance();
115            if (instance == null) {
116                String msg = getClass().getName() + " implementation did not return a default instance in " +
117                        "the event of a null/empty Ini configuration.  This is required to support the " +
118                        "Factory interface.  Please check your implementation.";
119                throw new IllegalStateException(msg);
120            }
121        } else {
122            log.debug("Creating instance from Ini [" + ini + "]");
123            instance = createInstance(ini);
124            if (instance == null) {
125                String msg = getClass().getName() + " implementation did not return a constructed instance from " +
126                        "the createInstance(Ini) method implementation.";
127                throw new IllegalStateException(msg);
128            }
129        }
130
131        return instance;
132    }
133
134    protected abstract T createInstance(Ini ini);
135
136    protected abstract T createDefaultInstance();
137}