001    /**
002     * Copyright (c) 2000-2013 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;
016    
017    import java.util.Map;
018    
019    /**
020     * Contains a list of the available routes and handles conversion of URLs to
021     * parameter maps and vice versa.
022     *
023     * <p>
024     * The priority of a route is based on when it was added to the router. The
025     * first route has the highest priority and a URL path will always be matched
026     * against it first. If the first route does not match, the second will be
027     * tried, continuing until either a match is found or all the routes have been
028     * tested.
029     * </p>
030     *
031     * <p>
032     * When choosing the order in which to place a list of routes, the general rule
033     * is to sort the routes from least general to most general. The simplest way of
034     * determining the generality of a route is by counting the number of capturing
035     * fragments in it.
036     * </p>
037     *
038     * @author Connor McKay
039     * @author Brian Wing Shun Chan
040     * @see    Route
041     * @see    DefaultFriendlyURLMapper
042     */
043    public interface Router {
044    
045            /**
046             * Generates a new route from its pattern string.
047             *
048             * @param  pattern the route pattern string
049             * @return the generated route
050             */
051            public Route addRoute(String pattern);
052    
053            /**
054             * Generates a URL from the parameter map using the available routes.
055             *
056             * @param  parameters the parameter map
057             * @return the URL path, or <code>null</code> if an applicable route was not
058             *         found
059             */
060            public String parametersToUrl(Map<String, String> parameters);
061    
062            /**
063             * Parses a URL into a parameter map using the available routes.
064             *
065             * @param  url the URL to be parsed
066             * @param  parameters the parameter map to be populated
067             * @return <code>true</code> if a match was found and
068             *         <code>parameters</code> was populated; <code>false</code>
069             *         otherwise
070             */
071            public boolean urlToParameters(String url, Map<String, String> parameters);
072    
073    }