001    // Copyright 2004, 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry;
016    
017    import java.io.InputStream;
018    
019    import org.apache.hivemind.Locatable;
020    import org.apache.hivemind.Resource;
021    
022    /**
023     * Representation of a asset (GIF, JPEG, etc.) that may be owned by a {@link IComponent}.
024     * <p>
025     * Assets may be completely external (i.e., on some other web site), contained by the
026     * {@link javax.servlet.ServletContext}, or stored somewhere in the classpath.
027     * <p>
028     * In the latter two cases, the resource may be localized.
029     * 
030     * @author Howard Lewis Ship
031     */
032    
033    public interface IAsset extends Locatable
034    {
035        /**
036         * Returns a URL for the asset, ready to be inserted into the output HTML. If the asset can be
037         * localized, the localized version (matching the {@link java.util.Locale}of the current
038         * {@link IPage page}) is returned.
039         * 
040         * @throws ApplicationRuntimeException
041         *             if the asset does not exist.
042         */
043    
044        public String buildURL();
045    
046        /**
047         * Accesses the localized version of the resource (if possible) and returns it as an input
048         * stream. A version of the resource localized to the current {@link IPage page}is returned.
049         * 
050         * @throws ApplicationRuntimeException
051         *             if the asset does not exist, or can't be read.
052         */
053    
054        public InputStream getResourceAsStream();
055    
056        /**
057         * Returns the underlying location of the asset.
058         */
059    
060        public Resource getResourceLocation();
061    }