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 }