001    // Copyright 2010 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.tapestry5.services.assets;
016    
017    import java.io.IOException;
018    
019    import javax.servlet.http.HttpServletResponse;
020    
021    import org.apache.tapestry5.Asset;
022    import org.apache.tapestry5.SymbolConstants;
023    import org.apache.tapestry5.internal.services.AssetDispatcher;
024    import org.apache.tapestry5.services.Request;
025    import org.apache.tapestry5.services.Response;
026    
027    /**
028     * Handler for asset requests, which expose some kind of {@link Asset} to
029     * the user agent (i.e., the client web browser). Starting in Tapestry 5.2,
030     * asset paths are more structured, consisting of four parts:
031     * <ul>
032     * <li><code>/assets/</code> -- the root path for all assets
033     * <li>
034     * <em>application version</em> -- the application version, as defined by the
035     * {@link SymbolConstants#APPLICATION_VERSION} symbol
036     * <li><em>handler id</em> -- a handler for this part of the asset path (defined by contributions to the
037     * <code>AssetDispatcher</code> service)
038     * <li><em>extra path</em> -- additional path beyond the handler id, used to identify the specific resource
039     * </ul>
040     * <p>
041     * So, an example path might be <code>/assets/1.0.1/corelib/components/select.png</code>. The handler id would be
042     * <code>corelib</code>, and the extra path would be <code>components/select.png</code>.
043     * 
044     * @since 5.2.0
045     * @see AssetDispatcher
046     */
047    public interface AssetRequestHandler
048    {
049        /**
050         * Given a request targeted (via the handler id) to the specific handler, process the request.
051         * The handler is responsible for processing the request, sending back either a bytestream
052         * (via {@link Response#getOutputStream(String)}) or an error response
053         * (via {@link Response#sendError(int, String)}). It is the handler's responsibility to allow
054         * for client-side caching (possibly sending an {@link HttpServletResponse#SC_NOT_MODIFIED} response).
055         * <p>
056         * The handler should return true if it provided a response. If the handler returns false, this indicates that the
057         * extra path did not identify a known asset (virtual or otherwise) and the AssetDispatcher service should send a
058         * {@link HttpServletResponse#SC_NOT_FOUND} response.
059         * 
060         * @param request
061         *            incoming asset request
062         * @param response
063         *            used to send a response to client
064         * @param extraPath
065         *            additional path to identify the specific asset
066         * @return true if request handler, false if asset not found
067         */
068        boolean handleAssetRequest(Request request, Response response, String extraPath) throws IOException;
069    }