com.liferay.portal.kernel.portlet

Interface Route

@ProviderType
public interface Route

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, Brian Wing Shun Chan

See Also:

Router, com.liferay.portlet.RouteImpl, StringParser

Method Summary

Modifier and Type	Method and Description
void	addGeneratedParameter(java.lang.String name, java.lang.String pattern) Adds a generated parameter to this route.
void	addIgnoredParameter(java.lang.String name) Adds an ignored parameter to this route.
void	addImplicitParameter(java.lang.String name, java.lang.String value) Adds an implicit parameter to this route.
void	addOverriddenParameter(java.lang.String name, java.lang.String value) Adds an overridden parameter to this route.
java.util.Map<java.lang.String,StringParser>	getGeneratedParameters() Returns the generated parameters for this route.
java.util.Set<java.lang.String>	getIgnoredParameters() Returns the ignored parameters for this route.
java.util.Map<java.lang.String,java.lang.String>	getImplicitParameters() Returns the implicit parameters for this route.
java.util.Map<java.lang.String,java.lang.String>	getOverriddenParameters() Returns the overridden parameters for this route.
java.lang.String	getPattern()
java.lang.String	parametersToUrl(java.util.Map<java.lang.String,java.lang.String> parameters) Generates a URL from the parameter map if this route is appropriate.
boolean	urlToParameters(java.lang.String url, java.util.Map<java.lang.String,java.lang.String> parameters) Populates the parameter map with values parsed from the URL if this route matches.

Method Detail

addGeneratedParameter

void addGeneratedParameter(java.lang.String name,
                           java.lang.String pattern)

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>
 
 

Parameters:

name - the name of the generated parameter

pattern - the pattern string of the generated parameter

addIgnoredParameter

void addIgnoredParameter(java.lang.String name)

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.

Parameters:

name - the name of the ignored parameter

addImplicitParameter

void addImplicitParameter(java.lang.String name,
                          java.lang.String value)

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".

Parameters:

name - the name of the implicit parameter

value - the value of the implicit parameter

addOverriddenParameter

void addOverriddenParameter(java.lang.String name,
                            java.lang.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.

Parameters:

name - the name of the overridden parameter

value - the value of the overridden parameter

getGeneratedParameters

java.util.Map<java.lang.String,StringParser> getGeneratedParameters()

Returns the generated parameters for this route.

Returns:

the generated parameter names and string parsers

See Also:

addGeneratedParameter(String, String)

getIgnoredParameters

java.util.Set<java.lang.String> getIgnoredParameters()

Returns the ignored parameters for this route.

Returns:

the ignored parameter names

See Also:

addIgnoredParameter(String)

getImplicitParameters

java.util.Map<java.lang.String,java.lang.String> getImplicitParameters()

Returns the implicit parameters for this route.

Returns:

the implicit parameter names and values

See Also:

addImplicitParameter(String, String)

getOverriddenParameters

java.util.Map<java.lang.String,java.lang.String> getOverriddenParameters()

Returns the overridden parameters for this route.

Returns:

the overridden parameter names and values

See Also:

addOverriddenParameter(String, String)

getPattern

java.lang.String getPattern()

parametersToUrl

java.lang.String parametersToUrl(java.util.Map<java.lang.String,java.lang.String> parameters)

Generates a URL from the parameter map if this route is appropriate.

A route is appropriate if:

1. The values given in parameters for the route's generated parameters match their patterns
2. The route's implicit parameters all match parameters
3. Every fragment in the route pattern has a matching value in parameters

Parameters:

parameters - the parameter map

Returns:

the URL path, or null if this route is not appropriate

urlToParameters

boolean urlToParameters(java.lang.String url,
                        java.util.Map<java.lang.String,java.lang.String> 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.

Parameters:

url - the URL path

parameters - the parameter map. If this route does not match, the parameter map will not be modified.

Returns:

true if the route matches; false otherwise