001    /**
002     * Copyright (c) 2000-present Liferay, Inc. All rights reserved.
003     *
004     * This library is free software; you can redistribute it and/or modify it under
005     * the terms of the GNU Lesser General Public License as published by the Free
006     * Software Foundation; either version 2.1 of the License, or (at your option)
007     * any later version.
008     *
009     * This library is distributed in the hope that it will be useful, but WITHOUT
010     * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
011     * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
012     * details.
013     */
014    
015    package com.liferay.portal.kernel.portlet.bridges.mvc;
016    
017    import javax.portlet.PortletException;
018    import javax.portlet.ResourceRequest;
019    import javax.portlet.ResourceResponse;
020    
021    /**
022     * Provides an interface to allow the portlet to serve a resource. This
023     * interface can only be used when the portlet is based on {@link MVCPortlet}.
024     *
025     * <p>
026     * The resource command to be invoked is determined by two factors:
027     * </p>
028     *
029     * <ul>
030     * <li>
031     * The portlet name that the resource URL is referring to.
032     * </li>
033     * <li>
034     * The <code>ResourceID</code> of the resource request.
035     * </li>
036     * </ul>
037     *
038     * <p>
039     * Implementations of this interface must be OSGi components that are registered
040     * in the OSGi Registry with the following properties:
041     * </p>
042     *
043     * <ul>
044     * <li>
045     * <code>javax.portlet.name</code>: The portlet name associated to this resource
046     * command.
047     * </li>
048     * <li>
049     * <code>mvc.command.name</code>: the command name that matches the
050     * <code>ResourceID</code> of the resource request. This name cannot contain any
051     * comma (<code>,</code>).
052     * </li>
053     * </ul>
054     *
055     * <p>
056     * The method {@link MVCPortlet#serveResource(ResourceRequest,
057     * ResourceResponse)} searches the OSGi Registry for the resource command that
058     * matches both the resource request's portlet name with the property
059     * <code>javax.portlet.name</code> and the resource request's
060     * <code>ResourceID</code> with the property <code>mvc.command.name</code>.
061     * </p>
062     *
063     * <p>
064     * In general, only one resource command is executed per portlet resource URL.
065     * If the ResourceID of the resource request is, however, a comma separated list
066     * of multiple names, {@link MVCPortlet} finds the resource commands and invokes
067     * them sequentially in the order they're specified in the list.
068     * </p>
069     *
070     * <p>
071     * When there are multiple resource commands registered for the same portlet
072     * name and with the same command name, only the resource command with the
073     * highest service ranking is invoked.
074     * </p>
075     *
076     * <p>
077     * {@link BaseMVCResourceCommand} is an abstract class that implements this
078     * interface and can be extended to simplify using resource commands.
079     * </p>
080     *
081     * @author Sergio Gonz??lez
082     */
083    public interface MVCResourceCommand extends MVCCommand {
084    
085            public static final MVCResourceCommand EMPTY = new MVCResourceCommand() {
086    
087                    @Override
088                    public boolean serveResource(
089                            ResourceRequest resourceRequest,
090                            ResourceResponse resourceResponse) {
091    
092                            return false;
093                    }
094    
095            };
096    
097            /**
098             * Invoked by {@link MVCPortlet} to allow the portlet to serve a resource.
099             *
100             * @param  resourceRequest the resource request
101             * @param  resourceResponse the resource response
102             * @return <code>true</code> if an error occurs in serving the resource;
103             *         <code>false</code> otherwise
104             */
105            public boolean serveResource(
106                            ResourceRequest resourceRequest, ResourceResponse resourceResponse)
107                    throws PortletException;
108    
109    }