com.liferay.portal.kernel.portlet.Route Maven / Gradle / Ivy
/**
* Copyright (c) 2000-present Liferay, Inc. All rights reserved.
*
* This library is free software; you can redistribute it and/or modify it under
* the terms of the GNU Lesser General Public License as published by the Free
* Software Foundation; either version 2.1 of the License, or (at your option)
* any later version.
*
* This library is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
* details.
*/
package com.liferay.portal.kernel.portlet;
import aQute.bnd.annotation.ProviderType;
import com.liferay.portal.kernel.util.StringParser;
import java.util.Map;
import java.util.Set;
/**
* Represents a single friendly URL pattern and provides the ability to either
* parse a friendly URL path or generate a friendly URL from a parameter map.
*
* @author Connor McKay
* @author Brian Wing Shun Chan
* @see Router
* @see com.liferay.portlet.RouteImpl
* @see StringParser
*/
@ProviderType
public interface Route {
/**
* Adds a generated parameter to this route.
*
*
* A generated parameter is never part of the URL, but is constructed from
* one or more "virtual parameters" using a pattern string. When a URL is
* parsed, the virtual parameters are populated from the URL, and the
* generated parameter is then built from its constituent virtual
* parameters.
*
*
*
* When a URL is generated, the opposite process occurs. The generated
* parameter must have its value passed in through the parameter map. This
* value is parsed using the pattern string, and the virtual parameters are
* populated and made available for use in the route pattern string. The
* value of the generated parameter will not be available in the route
* pattern; only the values of the virtual parameters may be used.
*
*
*
* The following is an example route definition that uses a generated
* parameter to remove the .jsp extension of the current page from the URL.
*
*
*
*
*
* <route>
* <pattern>/{jspPageName}/{id:\d+}</pattern>
* <generated-parameter name="jspPage">{jspPageName}.jsp</generated-parameter>
* </route>
*
*
*
* @param name the name of the generated parameter
* @param pattern the pattern string of the generated parameter
*/
public void addGeneratedParameter(String name, String pattern);
/**
* Adds an ignored parameter to this route.
*
*
* An ignored parameter never appears in the query string regardless of its
* value. Ignored parameters have no effect on the parsing of URLs.
*
*
* @param name the name of the ignored parameter
*/
public void addIgnoredParameter(String name);
/**
* Adds an implicit parameter to this route.
*
*
* An implicit parameter applies in both stages of a route's lifecycle, URL
* parsing and URL generation. When a URL is parsed, the implicit parameters
* will be copied onto the parameter map. When a URL is generated from a
* parameter map, all the implicit parameters will be checked against the
* parameters in the map. If any do not match or are missing from the
* parameter map, this route will not be used for generating the URL.
*
*
*
* Implicit parameters are matched after all virtual parameters have been
* populated, and therefore should not match against the value of a
* generated parameter, as it will not be available.
*
*
*
* The most common use of implicit parameters is to specify a parameter that
* is included statically in the route pattern. For instance, if a custom
* route is specified for the JSP page "view_profile.jsp", the routes
* definition could look like the following:
*
*
*
*
*
* <route>
* <pattern>/profile/view/{id:\d+}</pattern>
* <implicit-parameter name="jspPage">view_profile.jsp</implicit-parameter>
* </route>
*
*
*
*
* Since the jspPage is specified with a implicit-parameter, this route will
* only be used to generate URLs if the jspPage is set to
* "view_profile.jsp". Likewise, when a URL in this format is recognized,
* the jspPage will automatically be set to "view_profile.jsp".
*
*
* @param name the name of the implicit parameter
* @param value the value of the implicit parameter
*/
public void addImplicitParameter(String name, String value);
/**
* Adds an overridden parameter to this route.
*
*
* An overridden parameter is one that should always be set to a certain
* value when a URL is parsed. Overridden parameters have no effect on the
* generating of URLs.
*
*
*
* If a implicit parameter and an overridden parameter share the same name,
* the overridden parameter value will take precedence when a URL is parsed.
* When a URL is generated the implicit parameter value will be checked
* against the parameter map as usual.
*
*
* @param name the name of the overridden parameter
* @param value the value of the overridden parameter
*/
public void addOverriddenParameter(String name, String value);
/**
* Returns the generated parameters for this route.
*
* @return the generated parameter names and string parsers
* @see #addGeneratedParameter(String, String)
*/
public Map getGeneratedParameters();
/**
* Returns the ignored parameters for this route.
*
* @return the ignored parameter names
* @see #addIgnoredParameter(String)
*/
public Set getIgnoredParameters();
/**
* Returns the implicit parameters for this route.
*
* @return the implicit parameter names and values
* @see #addImplicitParameter(String, String)
*/
public Map getImplicitParameters();
/**
* Returns the overridden parameters for this route.
*
* @return the overridden parameter names and values
* @see #addOverriddenParameter(String, String)
*/
public Map getOverriddenParameters();
public String getPattern();
/**
* Generates a URL from the parameter map if this route is appropriate.
*
*
* A route is appropriate if:
*
*
*
* -
* The values given in
parameters for the route's generated
* parameters match their patterns
*
* -
* The route's implicit parameters all match
parameters
*
* -
* Every fragment in the route pattern has a matching value in
*
parameters
*
*
*
* @param parameters the parameter map
* @return the URL path, or null if this route is not
* appropriate
*/
public String parametersToUrl(Map parameters);
/**
* Populates the parameter map with values parsed from the URL if this route
* matches.
*
*
* Generated parameters will be built and added to parameters
* if possible. If the pattern for a virtual parameter in the generated
* parameter does not match its pattern in the route, that generated
* parameter may not be build.
*
*
*
* Virtual parameters will not be present in parameters.
*
*
* @param url the URL path
* @param parameters the parameter map. If this route does not match, the
* parameter map will not be modified.
* @return true if the route matches; false
* otherwise
*/
public boolean urlToParameters(String url, Map parameters);
}