001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/portal/tags/sakai_2-4-1/portal-api/api/src/java/org/sakaiproject/portal/api/Portal.java $
003: * $Id: Portal.java 29143 2007-04-19 01:10:38Z ajpoland@iupui.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006, 2007 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.portal.api;
021:
022: import java.io.IOException;
023: import java.util.List;
024: import java.util.Map;
025:
026: import javax.servlet.ServletContext;
027: import javax.servlet.http.HttpServletRequest;
028: import javax.servlet.http.HttpServletResponse;
029:
030: import org.sakaiproject.site.api.Site;
031: import org.sakaiproject.site.api.ToolConfiguration;
032: import org.sakaiproject.tool.api.ActiveTool;
033: import org.sakaiproject.tool.api.Placement;
034: import org.sakaiproject.tool.api.Session;
035: import org.sakaiproject.tool.api.ToolException;
036:
037: /**
038: * This interface represents a portal and is used mainly by portal handlers that
039: * will not know the details of the portal implimentation.
040: *
041: * @author ieb
042: * @since Sakai 2.4
043: * @version $Rev: 29143 $
044: */
045: public interface Portal {
046:
047: /**
048: * Error response modes.
049: */
050: public static final int ERROR_SITE = 0;
051:
052: public static final int ERROR_GALLERY = 1;
053:
054: public static final int ERROR_WORKSITE = 2;
055:
056: /**
057: * Parameter value to allow anonymous users of gallery mode to be sent to
058: * the gateway site as anonymous user (like the /portal URL) instead of
059: * making them log in (like worksite, site, and tool URLs).
060: */
061: public static final String PARAM_FORCE_LOGIN = "force.login";
062:
063: public static final String PARAM_FORCE_LOGOUT = "force.logout";
064:
065: /**
066: * ThreadLocal attribute set while we are processing an error.
067: */
068: public static final String ATTR_ERROR = "org.sakaiproject.portal.error";
069:
070: /**
071: * Session attribute root for storing a site's last page visited - just
072: * append the site id.
073: */
074: public static final String ATTR_SITE_PAGE = "sakai.portal.site.";
075:
076: /**
077: * The default portal name is none is specified.
078: */
079: public static final String DEFAULT_PORTAL_CONTEXT = "charon";
080:
081: /**
082: * Configuration option to enable/disable state reset on navigation change
083: */
084: public static final String CONFIG_AUTO_RESET = "portal.experimental.auto.reset";
085:
086: /**
087: * Names of tool config/registration attributes that control the rendering
088: * of the tool's titlebar
089: */
090: public static final String TOOLCONFIG_SHOW_RESET_BUTTON = "reset.button";
091:
092: public static final String TOOLCONFIG_SHOW_HELP_BUTTON = "help.button";
093:
094: public static final String TOOLCONFIG_HELP_DOCUMENT_ID = "help.id";
095:
096: public static final String TOOLCONFIG_HELP_DOCUMENT_URL = "help.url";
097:
098: /**
099: * prepare the response and send it to the render engine
100: *
101: * @param rcontext
102: * @param res
103: * @param template
104: * @param contentType
105: * @throws IOException
106: */
107: void sendResponse(PortalRenderContext rcontext,
108: HttpServletResponse res, String template, String contentType)
109: throws IOException;
110:
111: /**
112: * get the placement for the request
113: *
114: * @param req
115: * @param res
116: * @param session
117: * @param placementId
118: * @param doPage
119: * @return
120: * @throws ToolException
121: */
122: String getPlacement(HttpServletRequest req,
123: HttpServletResponse res, Session session,
124: String placementId, boolean doPage) throws ToolException;
125:
126: /**
127: * perform login
128: *
129: * @param req
130: * @param res
131: * @param session
132: * @param returnPath
133: * @param skipContainer
134: * @throws ToolException
135: */
136: void doLogin(HttpServletRequest req, HttpServletResponse res,
137: Session session, String returnPath, boolean skipContainer)
138: throws ToolException;
139:
140: /**
141: * Process a logout
142: *
143: * @param req
144: * Request object
145: * @param res
146: * Response object
147: * @param session
148: * Current session
149: * @param returnPath
150: * if not null, the path to use for the end-user browser redirect
151: * after the logout is complete. Leave null to use the configured
152: * logged out URL.
153: * @throws ToolException
154: */
155: void doLogout(HttpServletRequest req, HttpServletResponse res,
156: Session session, String returnPath) throws ToolException;
157:
158: /**
159: * get a new render context from the render engine
160: *
161: * @param siteType
162: * @param title
163: * @param skin
164: * @param request
165: * @return
166: */
167: PortalRenderContext startPageContext(String siteType, String title,
168: String skin, HttpServletRequest request);
169:
170: /**
171: * perform a redirect if logged out
172: *
173: * @param res
174: * @return
175: * @throws IOException
176: */
177: boolean redirectIfLoggedOut(HttpServletResponse res)
178: throws IOException;
179:
180: /**
181: * get the portal page URL base on the tool supplied
182: *
183: * @param siteTool
184: * @return
185: */
186: String getPortalPageUrl(ToolConfiguration siteTool);
187:
188: /**
189: * populate the model with error status
190: *
191: * @param req
192: * @param res
193: * @param session
194: * @param mode
195: * @throws ToolException
196: * @throws IOException
197: */
198: void doError(HttpServletRequest req, HttpServletResponse res,
199: Session session, int mode) throws ToolException,
200: IOException;
201:
202: /**
203: * forward to a portal url
204: *
205: * @param tool
206: * @param req
207: * @param res
208: * @param siteTool
209: * @param skin
210: * @param toolContextPath
211: * @param toolPathInfo
212: * @throws IOException
213: * @throws ToolException
214: */
215: void forwardPortal(ActiveTool tool, HttpServletRequest req,
216: HttpServletResponse res, ToolConfiguration siteTool,
217: String skin, String toolContextPath, String toolPathInfo)
218: throws ToolException, IOException;
219:
220: /**
221: * setup in preparation for a forward
222: *
223: * @param req
224: * @param res
225: * @param p
226: * @param skin
227: */
228: void setupForward(HttpServletRequest req, HttpServletResponse res,
229: Placement p, String skin) throws ToolException;
230:
231: /**
232: * include the model section that relates to the bottom of the page.
233: *
234: * @param rcontext
235: */
236: void includeBottom(PortalRenderContext rcontext);
237:
238: /**
239: * work out the type of the site based on the site id.
240: *
241: * @param siteId
242: * @return
243: */
244: String calcSiteType(String siteId);
245:
246: /**
247: * include the part od the view tree needed to render login
248: *
249: * @param rcontext
250: * @param req
251: * @param session
252: */
253: void includeLogin(PortalRenderContext rcontext,
254: HttpServletRequest req, Session session);
255:
256: /**
257: * forward the request to a tool
258: *
259: * @param tool
260: * @param req
261: * @param res
262: * @param siteTool
263: * @param skin
264: * @param toolContextPath
265: * @param toolPathInfo
266: * @throws ToolException
267: */
268: void forwardTool(ActiveTool tool, HttpServletRequest req,
269: HttpServletResponse res, Placement placement, String skin,
270: String toolContextPath, String toolPathInfo)
271: throws ToolException;
272:
273: /**
274: * get the site id for the user
275: *
276: * @param userId
277: * @return
278: */
279: String getUserEidBasedSiteId(String userId);
280:
281: /**
282: * convert sites into a map for the view tree
283: *
284: * @param req
285: * @param mySites
286: * @param prefix
287: * @param currentSiteId
288: * @param myWorkspaceSiteId
289: * @param includeSummary
290: * @param expandSite
291: * @param resetTools
292: * @param doPages
293: * @param toolContextPath
294: * @param loggedIn
295: * @return
296: */
297: List<Map> convertSitesToMaps(HttpServletRequest req, List mySites,
298: String prefix, String currentSiteId,
299: String myWorkspaceSiteId, boolean includeSummary,
300: boolean expandSite, boolean resetTools, boolean doPages,
301: String toolContextPath, boolean loggedIn);
302:
303: /**
304: * convert a single site into a map
305: *
306: * @param req
307: * @param s
308: * @param prefix
309: * @param currentSiteId
310: * @param myWorkspaceSiteId
311: * @param includeSummary
312: * @param expandSite
313: * @param resetTools
314: * @param doPages
315: * @param toolContextPath
316: * @param loggedIn
317: * @return
318: */
319: Map convertSiteToMap(HttpServletRequest req, Site s, String prefix,
320: String currentSiteId, String myWorkspaceSiteId,
321: boolean includeSummary, boolean expandSite,
322: boolean resetTools, boolean doPages,
323: String toolContextPath, boolean loggedIn);
324:
325: /**
326: * populate the view tree for the model
327: *
328: * @param req
329: * @param res
330: * @param session
331: * @param siteId
332: * @param toolId
333: * @param toolContextPath
334: * @param prefix
335: * @param doPages
336: * @param resetTools
337: * @param includeSummary
338: * @param expandSite
339: * @return
340: * @throws ToolException
341: * @throws IOException
342: */
343: PortalRenderContext includePortal(HttpServletRequest req,
344: HttpServletResponse res, Session session, String siteId,
345: String toolId, String toolContextPath, String prefix,
346: boolean doPages, boolean resetTools,
347: boolean includeSummary, boolean expandSite)
348: throws ToolException, IOException;
349:
350: /**
351: * include the tool part of the view tree
352: *
353: * @param res
354: * @param req
355: * @param placement
356: * @return
357: * @throws IOException
358: */
359: Map includeTool(HttpServletResponse res, HttpServletRequest req,
360: ToolConfiguration placement) throws IOException;
361:
362: /**
363: * Get the context name of the portal. This is the name used to identify the
364: * portal implimentation in the portal service and to other parts of the
365: * system. Typically portals will be registered with the portal service
366: * using a name and render engines and PortalHandlers will connect to named
367: * portals.
368: *
369: * @return
370: */
371: String getPortalContext();
372:
373: /**
374: * Get the servlet context associated with the portal
375: *
376: * @return
377: */
378: ServletContext getServletContext();
379:
380: }
|