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.ActionRequest;
018    import javax.portlet.ActionResponse;
019    import javax.portlet.PortletException;
020    
021    /**
022     * Provides an interface to allow the portlet to process a particular action
023     * request. This interface can only be used when the portlet is based on {@link
024     * MVCPortlet}.
025     *
026     * <p>
027     * The action command to be invoked is determined by two factors:
028     * </p>
029     *
030     * <ul>
031     * <li>
032     * The portlet name that the action URL refers to.
033     * </li>
034     * <li>
035     * The parameter value <code>ActionRequest.ACTION_NAME</code> of the action URL.
036     * </li>
037     * </ul>
038     *
039     * <p>
040     * Implementations of this interface must be OSGi components that are registered
041     * in the OSGi Registry with the following properties:
042     * </p>
043     *
044     * <ul>
045     * <li>
046     * <code>javax.portlet.name</code>: The portlet name associated to this action
047     * command.
048     * </li>
049     * <li>
050     * <code>mvc.command.name</code>: the command name to match with the parameter
051     * value <code>ActionRequest.ACTION_NAME</code>. This name cannot contain any
052     * comma (<code>,</code>).
053     * </li>
054     * </ul>
055     *
056     * <p>
057     * The method {@link MVCPortlet#processAction(ActionRequest, ActionResponse)}
058     * searches the OSGi Registry for the action command that matches both the
059     * portlet name with the property <code>javax.portlet.name</code> and the
060     * parameter value <code>ActionRequest.ACTION_NAME</code> with the property
061     * <code>mvc.command.name</code>.
062     * </p>
063     *
064     * <p>
065     * In general, only one action command is executed per portlet action URL. If
066     * the parameter value <code>ActionRequest.ACTION_NAME</code> is, however, a
067     * comma separated list of names, {@link MVCPortlet} finds the matching action
068     * commands and invokes them sequentially in the order they're specified in the
069     * list.
070     * </p>
071     *
072     * <p>
073     * When there are multiple action commands registered for the same portlet name
074     * and with the same command name, only the action command with the highest
075     * service ranking is invoked.
076     * </p>
077     *
078     * <p>
079     * {@link BaseMVCActionCommand} is an abstract class that implements this
080     * interface and can be extended to simplify using action commands.
081     * </p>
082     *
083     * @author Michael C. Han
084     */
085    public interface MVCActionCommand extends MVCCommand {
086    
087            public static final MVCActionCommand EMPTY = new MVCActionCommand() {
088    
089                    @Override
090                    public boolean processAction(
091                            ActionRequest actionRequest, ActionResponse actionResponse) {
092    
093                            return false;
094                    }
095    
096            };
097    
098            /**
099             * Invoked by {@link MVCPortlet} to allow the portlet to process an action
100             * request.
101             *
102             * @param  actionRequest the action request
103             * @param  actionResponse the action response
104             * @return <code>true</code> if an error occurs in processing the action
105             *         request; <code>false</code> otherwise
106             */
107            public boolean processAction(
108                            ActionRequest actionRequest, ActionResponse actionResponse)
109                    throws PortletException;
110    
111    }