001    /*
002     * Copyright 2002-2004 the original author or authors.
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005     * use this file except in compliance with the License. You may obtain a copy of
006     * the License at
007     * 
008     * http://www.apache.org/licenses/LICENSE-2.0
009     * 
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012     * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013     * License for the specific language governing permissions and limitations under
014     * the License.
015     */
016    package org.springframework.richclient.image;
017    
018    import java.awt.Image;
019    
020    /**
021     * A interface for retrieving images by key. The key abstracts away the path to
022     * the image resource, effectively acting as an alias. For example, the key
023     * <code>wizard.pageImage</code> may map to a image resource in the classpath
024     * at <code>/images/wizard/title_banner.gif</code>
025     * <p>
026     * <p>
027     * Image source implementations are responsible for resolving the underlying
028     * image resource and loading it into memory. They may also cache image
029     * resources.
030     * 
031     * @author Keith Donald
032     */
033    public interface ImageSource {
034    
035        /**
036         * Loads the image with the specified key. Caching may or may not be
037         * performed.
038         * <p>
039         * <p>
040         * If the load is successful, the image resource is returned. If the load
041         * fails, a broken image indicator is returned if it is set for this source.
042         * If not set, an exception is thrown.
043         * 
044         * @param key
045         *            The image key
046         * @return The image.
047         * @throws NoSuchImageResourceException,
048         *             if no image could be found and no broken image indicator is
049         *             set.
050         */
051        public Image getImage(String key);
052    
053        /**
054         * Returns the image resource indexed by the specified key. A resource is a
055         * lightweight pointer to the image in the classpath, filesystem, or
056         * network, and not the actual loaded image itself.
057         * 
058         * @param key
059         *            The image key.
060         * @return The image resource.
061         */
062        public AwtImageResource getImageResource(String key);
063    
064    }