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.ApplicationRuntimeException;
020    import org.apache.hivemind.Locatable;
021    import org.apache.hivemind.Resource;
022    
023    /**
024     * Representation of a asset (GIF, JPEG, etc.) that may be owned by a {@link IComponent}.
025     * <p>
026     * Assets may be completely external (i.e., on some other web site), contained by the
027     * {@link javax.servlet.ServletContext}, or stored somewhere in the classpath.
028     * <p>
029     * In the latter two cases, the resource may be localized.
030     * 
031     * @author Howard Lewis Ship
032     */
033    
034    public interface IAsset extends Locatable
035    {
036        /**
037         * Returns a URL for the asset, ready to be inserted into the output HTML. If the asset can be
038         * localized, the localized version (matching the {@link java.util.Locale}of the current
039         * {@link IPage page}) is returned.
040         * 
041         * @throws ApplicationRuntimeException
042         *             if the asset does not exist.
043         */
044    
045        String buildURL();
046    
047        /**
048         * Accesses the localized version of the resource (if possible) and returns it as an input
049         * stream. A version of the resource localized to the current {@link IPage page}is returned.
050         * 
051         * @throws ApplicationRuntimeException
052         *             if the asset does not exist, or can't be read.
053         */
054    
055        InputStream getResourceAsStream();
056    
057        /**
058         * Returns the underlying location of the asset.
059         */
060    
061        Resource getResourceLocation();
062    }