001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/portal/tags/sakai_2-4-1/portal-api/api/src/java/org/sakaiproject/portal/api/PortalService.java $
003: * $Id: PortalService.java 29143 2007-04-19 01:10:38Z ajpoland@iupui.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2005, 2006 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.util.Iterator;
023: import java.util.Map;
024:
025: import javax.servlet.http.HttpServletRequest;
026:
027: /**
028: * Portal Service acts as a focus for all Portal based activities, the service implementation
029: * should act as a holder to enable the varous webapps to communicate with one annother.
030: *
031: * @author ieb
032: * @since Sakai 2.4
033: * @version $Rev: 29143 $
034: */
035: public interface PortalService {
036: /**
037: * A portal request scope attribute that reprenset the placement id of the
038: * current request. It should be a string, and should be implimented where
039: * the request is portlet dispatched.
040: */
041: public static final String PLACEMENT_ATTRIBUTE = PortalService.class
042: .getName()
043: + "_placementid";
044:
045: /**
046: * this is the property in the tool config that defines the portlet context
047: * of tool. At the moment we assume that this is in the read-only properties
048: * of the tool, but there could be a generic tool placement that enabled any
049: * portlet to be mounted
050: */
051: public static final String TOOL_PORTLET_CONTEXT_PATH = "portlet-context";
052:
053: /**
054: * this is the property in the tool config that defines the name of the
055: * portlet application
056: */
057: public static final String TOOL_PORTLET_APP_NAME = "portlet-app-name";
058:
059: /**
060: * this is the property in the tool config that defines the name of the
061: * portlet
062: */
063: public static final String TOOL_PORTLET_NAME = "portlet-name";
064:
065: /**
066: * ste the state of the portal reset flag.
067: *
068: * @param state
069: */
070: void setResetState(String state);
071:
072: /**
073: * Returns a parameter map suitable for appending to a portal URL,
074: * representing that the URL state of a tool being shown with the specified
075: * placementId will be equal to the URLstub. URLstub may contain anchor
076: * state, which the portal implementation may honour if it is capable. The
077: * Map may also include the encoded state of other placements if they are
078: * being shown in the current render state.
079: */
080: Map<String, String[]> encodeToolState(String placementId,
081: String URLstub);
082:
083: /**
084: * Inverts the operation of encodeToolState, and returns the URL stub which
085: * was supplied for the supplied placementId. Will return <code>null</code>
086: * if there was no special state registered.
087: */
088: String decodeToolState(Map<String, String[]> params,
089: String placementId);
090:
091: /**
092: * get the state of the state of the portal reset flag
093: *
094: * @return
095: */
096: String getResetState();
097:
098: /**
099: * get the StoredState object that is used to hold initial request state on
100: * direct access to a portlet state or on GET or POST that requires other
101: * initial actions.
102: *
103: * @return
104: */
105: StoredState getStoredState();
106:
107: /**
108: * Was a reset requested
109: *
110: * @param req
111: * @return
112: */
113: boolean isResetRequested(HttpServletRequest req);
114:
115: /**
116: * set the StoredState of the request for later retrieval
117: *
118: * @param storedstate
119: */
120: void setStoredState(StoredState storedstate);
121:
122: /**
123: * Is the direct URL mechnism enabled in the configation file.
124: *
125: * @return
126: */
127: boolean isEnableDirect();
128:
129: /**
130: * Get the parameter used to communicate reset state operations on the URL
131: *
132: * @return
133: */
134: String getResetStateParam();
135:
136: /**
137: * Create a new Stored State
138: *
139: * @param marker
140: * the mark within the URL
141: * @param replacement
142: * and the replacement text on restoration
143: * @return
144: */
145: StoredState newStoredState(String marker, String replacement);
146:
147: /**
148: * Get an Iterator of Portlet Application Descriptors from the whole of the
149: * application
150: *
151: * @return
152: */
153: Iterator<PortletApplicationDescriptor> getRegisteredApplications();
154:
155: /**
156: * get a render engine possibly based on the request
157: *
158: * @param context -
159: * the context from whcih to take the render engine.
160: * @param request
161: * @return
162: */
163: PortalRenderEngine getRenderEngine(String context,
164: HttpServletRequest request);
165:
166: /**
167: * add a render engine to the available render engines.
168: *
169: * @param context -
170: * the context to rengister the render engine in, as there may be
171: * more than one portal in a sakai instance, you need to register the
172: * render engine against a context. The context should match the
173: * context used by the portal to retrieve its render engine. This is
174: * dependant on the Portal implementation details.
175: * @param vengine
176: * the render engine implementation to register with the portal
177: * service
178: */
179: void addRenderEngine(String context, PortalRenderEngine vengine);
180:
181: /**
182: * remove a render engine from the avaialble render engines
183: *
184: * @param context -
185: * the context to deregister the render engine from, as there may be
186: * more than one portal in a sakai instance, you need to deregister
187: * the render engine from a context. The context should match the
188: * context used by the portal to retrieve its render engine. This is
189: * dependant on the Portal implementation details.
190: * @param vengine
191: */
192: void removeRenderEngine(String context, PortalRenderEngine vengine);
193:
194: /**
195: * Add a PortalHandler to the portal Handler map for the named context.
196: *
197: * @param portal
198: * @param handler
199: */
200: void addHandler(Portal portal, PortalHandler handler);
201:
202: /**
203: * Remove the Portal Handler identitied by the URL fragment associated with
204: * the portal Context
205: *
206: * @param portal
207: * @param urlFragment
208: */
209: void removeHandler(Portal portal, String urlFragment);
210:
211: /**
212: * Get the PortalHandler map for the portal Context.
213: *
214: * @param portal
215: * @return
216: */
217: Map<String, PortalHandler> getHandlerMap(Portal portal);
218:
219: /**
220: * Add a portal to the portal service
221: *
222: * @param portal
223: */
224: void removePortal(Portal portal);
225:
226: /**
227: * Remove a portal from the portal service this should perform all the
228: * necessary cleanup
229: *
230: * @param portal
231: */
232: void addPortal(Portal portal);
233:
234: /**
235: * Get the implimentation of the StylableService from the portal impl
236: *
237: * @return
238: */
239: StyleAbleProvider getStylableService();
240:
241: }
|