01: /**********************************************************************************
02: * $URL: https://source.sakaiproject.org/svn/tool/tags/sakai_2-4-1/tool-api/api/src/java/org/sakaiproject/tool/api/ToolURL.java $
03: * $Id: ToolURL.java 7523 2006-04-09 13:03:23Z ggolden@umich.edu $
04: ***********************************************************************************
05: *
06: * Copyright (c) 2005, 2006 The Sakai Foundation.
07: *
08: * Licensed under the Educational Community License, Version 1.0 (the "License");
09: * you may not use this file except in compliance with the License.
10: * You may obtain a copy of the License at
11: *
12: * http://www.opensource.org/licenses/ecl1.php
13: *
14: * Unless required by applicable law or agreed to in writing, software
15: * distributed under the License is distributed on an "AS IS" BASIS,
16: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17: * See the License for the specific language governing permissions and
18: * limitations under the License.
19: *
20: **********************************************************************************/package org.sakaiproject.tool.api;
21:
22: import java.util.Map;
23:
24: /**
25: * A ToolURL is used to create a URL and encode it appropriate to the context and placement of the tool.
26: *
27: * @author <a href="mailto:vgoenka@sungardsct.com">Vishal Goenka</a>
28: */
29: public interface ToolURL {
30: /**
31: * Property name to retrieve an instance of ToolURLManager from an HttpServletRequest
32: */
33: String MANAGER = "tool.url.manager";
34:
35: /**
36: * Property name to set the HttpServletRequest in a given thread context, to default to when it is not available to the caller. This allows calling ToolURLManager's create<Type>URL with a null HttpRequestServlet, if one has been set in the
37: * current thread context. We use the same attribute name as set in org.sakaiproject.util.RequestFilter to prevent having to depend on RequestFilter class only to get this attribute. Is this a bad idea??
38: */
39: String HTTP_SERVLET_REQUEST = "org.sakaiproject.util.RequestFilter.http_request";
40:
41: /**
42: * Set path for this URL. Path can either be absolute with respect to the server or relative to the servlet context in which this tool is placed.
43: *
44: * @param path
45: * path relative to the tool
46: */
47: void setPath(String path);
48:
49: /**
50: * Sets the given String parameter to this URL. This method replaces all parameters with the given key. An implementation of this interface may prefix the attribute names internally in order to preserve a unique namespace for the tool
51: *
52: * @param name
53: * the parameter name
54: * @param value
55: * the parameter value
56: */
57: void setParameter(String name, String value);
58:
59: /**
60: * Sets the given String array parameter to this URL. This method replaces all parameters with the given key. An implementation of this interface may prefix the attribute names internally in order to preserve a unique namespace for the tool
61: *
62: * @param name
63: * the parameter name
64: * @param values
65: * the parameter values
66: */
67: void setParameter(String name, String[] values);
68:
69: /**
70: * Sets a parameter map for this URL. All previously set parameters are cleared. An implementation of this interface may prefix the attribute names internally in order to preserve a unique namespace for the tool
71: *
72: * @param parameters
73: * Map containing parameter names as keys and parameter values as map values. The keys in the parameter map must be of type String. The values in the parameter map must be of type String array (String[]).
74: */
75: void setParameters(Map parameters);
76:
77: /**
78: * Returns the URL string representation to be embedded in the markup. Note that the returned String may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client.
79: *
80: * @return the encoded URL as a String
81: */
82: String toString();
83: }
|