/*\
 * Copyright  2006 Klaus Rogall, Hamburg, Germany (klaus.rogall@web.de). All rights reserved.
 * _____________________________________________________________________________________________________________________
 * 
 * This class is "Open Source" as defined by the Open Source Initiative (OSI). You can redistribute it and/or modify it
 * under the terms of the BSD License. The license text is appended to the end of this file.
\*/

package de.klaro.base.util;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.net.URLDecoder;

import org.apache.commons.lang.ClassUtils;


/**
 * Diese Klasse enthlt Methoden zur Verarbeitung von Ressourcen.
 *
 * Ressourcen sind Daten, die als Input-Stream verarbeitet werden knnen. Zur Ermittlung der Ressourcen wird der
 * Context-Classloader des Threads benutzt (und wenn dieser die Ressource nicht liefern kann, ersatztweise der
 * Default-Classloader); Ressourcen werden daher blicherweise ber den Klassenpfad gesucht.
 *
 * Achtung: In bestimmten Laufzeitumgebungen kann entsprechende Security-Einstellungen der Zugriff auf Ressourcen
 * eingeschrnkt sein (z.B. in Browsern). So zum Beispiel ist das Laden von Ressourcen aus lokalen JAR-Dateien aus
 * einem Java-Applet heraus ohne weitere Modifikationen nicht mglich.
 *
 * Die Methoden dieser Klassen untersttzen u.a. auch sogenannte Klassen-Properties. Klassen-Properties sind
 * Properties, deren Name aus einem Klassennamen abgeleitet werden. Zu jeder Klasse knnen assoziierte Properties
 * geladen werden, die z.B. zur Festlegung von Konfigurationsparametern der Klasse dienen knnen. Der Name von
 * Klassen-Properties wird durch Ergnzung des Klassennamens um die Endung "Data" ermittelt. Beispiel: die Klasse
 * aaa.bbb.ccc.MyClass hat die assoziierten Klassen-Properties aaa/bbb/ccc/MyClassData.properties.
 *
 * @see     java.lang.ClassLoader
 */

public abstract class Resources extends Object
{

    /* ______________________________________________________________________________________________________________ *\
    \* Konstanten                                                                                                     */


    /** Endung der Namen von Klassen-Properties, die an den Klassennamen angehngt wird. */
    private static final String CLASS_PROPERTIES_SUFFIX = "Data";


    /* ______________________________________________________________________________________________________________ *\
    \* Klassenvariablen                                                                                               */


    /* ______________________________________________________________________________________________________________ *\
    \* Instanzvariablen                                                                                               */


    /* ______________________________________________________________________________________________________________ *\
    \* Konstruktoren                                                                                                  */


    /**
     * Erzeugt eine Instanz dieser Klasse.
     *
     * Da verhindert werden soll, dass Instanzen dieser Klasse ausserhalb dieser Klasse erzeugt werdem, ist dieser
     * Konstruktor 'private' deklariert.
     */

    private Resources()
    {
        super();
    }


    /* ______________________________________________________________________________________________________________ *\
    \* Instanzmethoden                                                                                                */


    /* ______________________________________________________________________________________________________________ *\
    \* Klassenmethoden                                                                                                */


    /**
     * Liefert den Input-Stream der mit einer Klasse assoziierten Klassen-Properties.
     *
     * @param  clazz            Die Klasse, deren Klassen-Properties geliefert werden sollen
     * @return                  Die Klassen-Properties der Klasse
     * @throws IOException      Die Ressource konnte nicht gefunden werden
     */

    public static InputStream getResourceStream(Class<?> clazz) throws IOException
    {
        return getResourceAsStream(clazz.getName().replace('.','/') + CLASS_PROPERTIES_SUFFIX + Const.PROPERTIES_FILE_SUFFIX);
    }


    /**
     * Liefert den Input-Stream der mit einer Klasse assoziierten Klassen-Properties, die jedoch in einem anderen
     * Package liegen.
     *
     * @param  packageName      Der Package-Name, der benutzt werden soll
     * @param  clazz            Die Klasse, deren Klassen-Properties geliefert werden sollen
     * @return                  Die Klassen-Properties der Klasse
     * @throws IOException      Die Ressource konnte nicht gefunden werden
     */

    public static InputStream getResourceStream(String packageName,Class<?> clazz) throws IOException
    {
        return getResourceAsStream(packageName.replace('.','/') + "/" + ClassUtils.getShortClassName(clazz) + CLASS_PROPERTIES_SUFFIX + Const.PROPERTIES_FILE_SUFFIX);
    }


    /**
     * Liefert den Input-Stream von Properties, die im Package der angegebenen Klasse liegen.
     *
     * @param  clazz            Die Klasse, dessen Package-Name benutzt wird
     * @param  propertiesName   Der Name der Properties
     * @return                  Die Klassen-Properties der Klasse
     * @throws IOException      Die Ressource konnte nicht gefunden werden
     */

    public static InputStream getResourceStream(Class<?> clazz,String propertiesName) throws IOException
    {
        return getResourceAsStream(clazz.getPackage().getName().replace('.','/') + "/" + propertiesName);
    }


    /**
     * Liefert die URL einer Ressource.
     *
     * @param  resource         Der Name der Ressource
     * @return                  Der Input-Stream zur Ressource
     * @throws IOException      Die Ressource konnte nicht gefunden werden
     */

    public static URL getResource(String resource) throws IOException
    {
        ClassLoader classloader = Thread.currentThread().getContextClassLoader();
        if (classloader == null)
            classloader = Resources.class.getClassLoader();

        URL url = classloader.getResource(resource);

        if (url == null)
            throw new IOException("no such resource: " + resource);

        return url;
    }

    
    /**
     * Liefert die Datei einer Ressource.
     *
     * @param  resource         Der Name der Ressource
     * @return                  Der Datei zur Ressource
     * @throws IOException      Die Ressource konnte nicht gefunden werden
     */
    
    public static File getResourceAsFile(String resource) throws IOException
    {
        return new File(URLDecoder.decode(getResource(resource).getFile(),"UTF-8"));
    }


    /**
     * Liefert einen Input-Stream zu einer Ressource.
     *
     * @param  resource         Der Name der Ressource
     * @return                  Der Input-Stream zur Ressource
     * @throws IOException      Die Ressource konnte nicht gefunden werden
     */

    public static InputStream getResourceAsStream(String resource) throws IOException
    {
        ClassLoader classloader = Thread.currentThread().getContextClassLoader();
        if (classloader == null)
            classloader = Resources.class.getClassLoader();

        InputStream stream = classloader.getResourceAsStream(resource);

        if (stream == null)
        {
            throw new IOException("no such resource: " + resource);
        }

        return stream;
    }


    /* ______________________________________________________________________________________________________________ *\
    \* Klassen                                                                                                        */

}

/*\
 * _____________________________________________________________________________________________________________________
 * 
 * This software is distributed under the terms of the BSD License:
 * 
 * Copyright  2006 Klaus Rogall, Hamburg, Germany (klaus.rogall@web.de). All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
 * following conditions are met:
 * 
 * - Redistributions of source code must retain the above copyright notice, this list of conditions and the following
 *   disclaimer.
 * - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
 *   disclaimer in the documentation and/or other materials provided with the distribution.
 * - Neither the name of the Klaus Rogall nor the names of its contributors may be used to endorse or promote products
 *   derived from this software without specific prior written permission.
 *   
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * _____________________________________________________________________________________________________________________
\*/