001    /**
002     * ================================================
003     * LibLoader : a free Java resource loading library
004     * ================================================
005     *
006     * Project Info:  http://reporting.pentaho.org/libloader/
007     *
008     * (C) Copyright 2006, by Pentaho Corporation and Contributors.
009     *
010     * This library is free software; you can redistribute it and/or modify it under the terms
011     * of the GNU Lesser General Public License as published by the Free Software Foundation;
012     * either version 2.1 of the License, or (at your option) any later version.
013     *
014     * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
015     * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
016     * See the GNU Lesser General Public License for more details.
017     *
018     * You should have received a copy of the GNU Lesser General Public License along with this
019     * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
020     * Boston, MA 02111-1307, USA.
021     *
022     * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
023     * in the United States and other countries.]
024     *
025     *
026     * ------------
027     * $Id: ResourceLoader.java 2713 2007-04-01 13:43:18Z taqua $
028     * ------------
029     * (C) Copyright 2006, by Pentaho Corporation.
030     */
031    package org.jfree.resourceloader;
032    
033    import java.util.Map;
034    import java.net.URL;
035    
036    /**
037     * A resource loader knows how to get binary rawdata from a location specified
038     * by an resource key. A resource key is a wrapper around any kind of data that
039     * is suitable to identify a resource location. The resource key can also hold
040     * configuration data for the factory.
041     *
042     * If the storage system is hierarchical, a new resource key can be derived from
043     * a given path-string.
044     *
045     * @author Thomas Morgner
046     */
047    public interface ResourceLoader
048    {
049      /**
050       * Checks, whether this resource loader implementation was responsible for
051       * creating this key.
052       *
053       * @param key
054       * @return
055       */
056      public boolean isSupportedKey (ResourceKey key);
057    
058      /**
059       * Creates a new resource key from the given object and the factory keys.
060       *
061       * @param value
062       * @param factoryKeys
063       * @return the created key or null, if the format was not recognized.
064       * @throws ResourceKeyCreationException if creating the key failed.
065       */
066      public ResourceKey createKey (Object value,
067                                    Map factoryKeys)
068          throws ResourceKeyCreationException;
069    
070      /**
071       * Derives a new resource key from the given key. If neither a path nor new
072       * factory-keys are given, the parent key is returned.
073       *
074       * @param parent the parent
075       * @param path the derived path (can be null).
076       * @param factoryKeys the optional factory keys (can be null).
077       * @return the derived key.
078       * @throws ResourceKeyCreationException if the key cannot be derived for any
079       * reason.
080       */
081      public ResourceKey deriveKey (ResourceKey parent,
082                                    String path,
083                                    Map factoryKeys)
084          throws ResourceKeyCreationException;
085    
086      /**
087       * Loads the binary data represented by this key.
088       *
089       * @param key
090       * @return
091       * @throws ResourceLoadingException
092       */
093      public ResourceData load (ResourceKey key)
094          throws ResourceLoadingException;
095    
096      public void setResourceManager (ResourceManager manager);
097    
098      public URL toURL (ResourceKey key);
099    }