001/*
002 * Copyright 2002-2012 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.web.portlet;
018
019import javax.portlet.PortletRequest;
020
021/**
022 * Interface to be implemented by objects that define a mapping between
023 * requests and handler objects.
024 *
025 * <p>This class can be implemented by application developers, although this is not
026 * necessary, as {@link org.springframework.web.portlet.handler.PortletModeHandlerMapping},
027 * {@link org.springframework.web.portlet.handler.ParameterHandlerMapping} and
028 * {@link org.springframework.web.portlet.handler.PortletModeParameterHandlerMapping}
029 * are included in the framework. The first is the default if no HandlerMapping
030 * bean is registered in the portlet application context.
031 *
032 * <p>HandlerMapping implementations can support mapped interceptors but do not
033 * have to. A handler will always be wrapped in a {@link HandlerExecutionChain}
034 * instance, optionally accompanied by some {@link HandlerInterceptor} instances.
035 * The DispatcherPortlet will first call each HandlerInterceptor's
036 * {@code preHandle} method in the given order, finally invoking the handler
037 * itself if all {@code preHandle} methods have returned {@code true}.
038 *
039 * <p>The ability to parameterize this mapping is a powerful and unusual
040 * capability of this Portlet MVC framework. For example, it is possible to
041 * write a custom mapping based on session state, cookie state or many other
042 * variables. No other MVC framework seems to be equally flexible.
043 *
044 * <p>Note: Implementations can implement the {@link org.springframework.core.Ordered}
045 * interface to be able to specify a sorting order and thus a priority for getting
046 * applied by DispatcherPortlet. Non-Ordered instances get treated as lowest priority.
047 *
048 * @author John A. Lewis
049 * @author Juergen Hoeller
050 * @see org.springframework.core.Ordered
051 * @see org.springframework.web.portlet.handler.AbstractHandlerMapping
052 * @see org.springframework.web.portlet.handler.PortletModeHandlerMapping
053 * @see org.springframework.web.portlet.handler.ParameterHandlerMapping
054 * @see org.springframework.web.portlet.handler.PortletModeParameterHandlerMapping
055 */
056public interface HandlerMapping {
057
058        /**
059         * Return a handler and any interceptors for this request. The choice may be made
060         * on portlet mode, session state, or any factor the implementing class chooses.
061         * <p>The returned HandlerExecutionChain contains a handler Object, rather than
062         * even a tag interface, so that handlers are not constrained in any way.
063         * For example, a HandlerAdapter could be written to allow another framework's
064         * handler objects to be used.
065         * <p>Returns {@code null} if no match was found. This is not an error.
066         * The DispatcherPortlet will query all registered HandlerMapping beans to find
067         * a match, and only decide there is an error if none can find a handler.
068         * @param request current portlet request
069         * @return a HandlerExecutionChain instance containing handler object and
070         * any interceptors, or null if no mapping found
071         * @throws Exception if there is an internal error
072         */
073        HandlerExecutionChain getHandler(PortletRequest request) throws Exception;
074
075}