001: /* Copyright 2001 The JA-SIG Collaborative. All rights reserved.
002: * See license distributed with this file and
003: * available online at http://www.uportal.org/license.html
004: */
005:
006: package org.jasig.portal.layout;
007:
008: /**
009: * Interface by which portal talks to the database
010: * @author George Lindholm
011: * @version $Revision: 35721 $
012: */
013:
014: import java.util.Hashtable;
015:
016: import org.jasig.portal.StructureStylesheetDescription;
017: import org.jasig.portal.StructureStylesheetUserPreferences;
018: import org.jasig.portal.ThemeStylesheetDescription;
019: import org.jasig.portal.ThemeStylesheetUserPreferences;
020: import org.jasig.portal.UserPreferences;
021: import org.jasig.portal.UserProfile;
022: import org.jasig.portal.security.IPerson;
023: import org.w3c.dom.Document;
024:
025: public interface IUserLayoutStore {
026:
027: /**
028: * Retreive a user layout document.
029: *
030: * @param Person an <code>IPerson</code> object specifying the user
031: * @param profile a user profile
032: * @return a <code>Document</code> containing user layout (conforms to userLayout.dtd)
033: * @exception Exception if an error occurs
034: */
035: public Document getUserLayout(IPerson Person, UserProfile profile)
036: throws Exception;
037:
038: /**
039: * Persist user layout document.
040: *
041: * @param Person an <code>IPerson</code> object specifying the user
042: * @param profile a user profile for which the layout is being stored
043: * @param layoutXML a <code>Document</code> containing user layout (conforming to userLayout.dtd)
044: * @param channelsAdded a boolean flag specifying if new channels have been added to the current user layout (for performance optimization purposes)
045: * @exception Exception if an error occurs
046: */
047: public void setUserLayout(IPerson Person, UserProfile profile,
048: Document layoutXML, boolean channelsAdded) throws Exception;
049:
050: // user profiles
051: /** Obtain user profile associated with a particular browser
052: *
053: * @param person User
054: * @param userAgent User-Agent header string
055: * @return user profile or <code>null</code> if no user profiles are associated with the given user agent.
056: */
057: public UserProfile getUserProfile(IPerson person, String userAgent)
058: throws Exception;
059:
060: /** update user profile
061: *
062: * @param person User
063: * @param profile profile update
064: */
065: public void updateUserProfile(IPerson person, UserProfile profile)
066: throws Exception;
067:
068: /** remove user profile from the database
069: *
070: * @param person User
071: * @param profileId profile id
072: */
073: public void deleteUserProfile(IPerson person, int profileId)
074: throws Exception;
075:
076: /**
077: * Creates a new user profile in the database.
078: * In the process, new profileId is assigned to the profile
079: *
080: * @param person User
081: * @param profile profile object (profile id in this object will be
082: * overwritten)
083: * @return profile object with the profile id set to the newly generated
084: * id
085: */
086: public UserProfile addUserProfile(IPerson person,
087: UserProfile profile) throws Exception;
088:
089: /** Obtains a user profile by profile id.
090: * @param person an <code>IPerson</code> object representing the user
091: * @param profileId profile id
092: */
093: public UserProfile getUserProfileById(IPerson person, int profileId)
094: throws Exception;
095:
096: /** retreive a list of profiles associated with a user
097: *
098: * @param person User
099: * @return a <code>Hashtable</code> mapping user profile ids (<code>Integer</code> objects) to the {@link UserProfile} objects
100: */
101: public Hashtable getUserProfileList(IPerson person)
102: throws Exception;
103:
104: // syste profiles
105: /** retreive a system profile associated with a given browser
106: *
107: * @param userAgent User-Agent header string
108: * @return profile object
109: */
110: public UserProfile getSystemProfile(String userAgent)
111: throws Exception;
112:
113: /** update system profile
114: *
115: * @param profile profile object
116: */
117: public void updateSystemProfile(UserProfile profile)
118: throws Exception;
119:
120: /** remove system profile from the database
121: *
122: * @param profileId profile id
123: */
124: public void deleteSystemProfile(int profileId) throws Exception;
125:
126: /** add a new system profile to the database. During this process, a new profile id will be assigned to the profile.
127: *
128: * @param profile profile object (profile id within will be overwritten)
129: * @return profile with an newly assigned id
130: */
131: public UserProfile addSystemProfile(UserProfile profile)
132: throws Exception;
133:
134: /** Obtain a system profile
135: * @param profileId system profile id
136: */
137: public UserProfile getSystemProfileById(int profileId)
138: throws Exception;
139:
140: /** obtain a list of system profiles
141: *
142: * @return a <code>Hashtable</code> mapping system profile ids (<code>Integer</code> objects) to the {@link UserProfile} objects
143: */
144: public Hashtable getSystemProfileList() throws Exception;
145:
146: /** establish a browser - user profile mapping
147: *
148: * @param person User
149: * @param userAgent User-Agent header string
150: * @param profileId profile id to which given user agent will be mapped
151: */
152: public void setUserBrowserMapping(IPerson person, String userAgent,
153: int profileId) throws Exception;
154:
155: /** establish system profile browser mapping
156: *
157: * @param userAgent User-Agent header string
158: * @param systemProfileId profile id of a profile to which given
159: * user-agent will be mapped
160: */
161: public void setSystemBrowserMapping(String userAgent,
162: int systemProfileId) throws Exception;
163:
164: /** Retreive the entire UserPreferences object
165: *
166: * @param person User
167: * @param profile profile
168: * @return user preferences
169: */
170: public UserPreferences getUserPreferences(IPerson person,
171: UserProfile profile) throws Exception;
172:
173: /** save user preferences
174: *
175: * @param person User
176: * @param up user preferences object
177: */
178: public void putUserPreferences(IPerson person, UserPreferences up)
179: throws Exception;
180:
181: /** Obtain structure stylesheet user preferences
182: *
183: * @param person User
184: * @param profileId profile id
185: * @param stylesheetId structure stylesheet id
186: * @return structure stylesheet user preferences. null is returned only if userId, profileId or stylesheet with an appropriate name do not exist. If all of the parameters are valid, but the user does not have any user preference settings associated with this stylesheet, return contains stylesheet preference object filled in with the defaults defined in stylesheet description.
187: */
188: public StructureStylesheetUserPreferences getStructureStylesheetUserPreferences(
189: IPerson person, int profileId, int stylesheetId)
190: throws Exception;
191:
192: /** Obtain theme stylesheet user preferences
193: *
194: * @param person User
195: * @param profileId profile id
196: * @param stylesheetId theme stylesheet id
197: * @return theme stylesheet user preferences. null is returned only if userId, profileId or stylesheet with an appropriate name do not exist. If all of the parameters are valid, but the user does not have any user preference settings associated with this stylesheet, return contains stylesheet preference object filled in with the defaults defined in stylesheet description.
198: */
199: public ThemeStylesheetUserPreferences getThemeStylesheetUserPreferences(
200: IPerson person, int profileId, int stylesheetId)
201: throws Exception;
202:
203: /** Save structure stylesheet user pferences
204: *
205: * @param person User
206: * @param profileId profile id
207: * @param fsup structure stylesheet user preferences
208: */
209: public void setStructureStylesheetUserPreferences(IPerson person,
210: int profileId, StructureStylesheetUserPreferences fsup)
211: throws Exception;
212:
213: /** Save theme stylesheet user preferences
214: *
215: * @param person User
216: * @param profileId profile id
217: * @param ssup structure stylesheet user preferneces
218: */
219: public void setThemeStylesheetUserPreferences(IPerson person,
220: int profileId, ThemeStylesheetUserPreferences ssup)
221: throws Exception;
222:
223: /* ChannelRegistry */
224: /**
225: * Generate an instance id for a channel being added to the user layout
226: *
227: * @param person an <code>IPerson</code> value
228: * @return a <code>String</code> value
229: * @exception Exception if an error occurs
230: */
231: public String generateNewChannelSubscribeId(IPerson person)
232: throws Exception;
233:
234: /**
235: * Generate a folder id for a folder being added to the user layout
236: *
237: * @param person an <code>IPerson</code> value
238: * @return a <code>String</code> value
239: * @exception Exception if an error occurs
240: */
241: public String generateNewFolderId(IPerson person) throws Exception;
242:
243: /**
244: * CoreStylesheetDescription
245: */
246: // functions that allow one to browse available core stylesheets in various ways
247: /** Obtain a list of all structure stylesheet registered in the portal
248: * that (given a proper theme stylesheet choice) can support a given mime type.
249: * Even though structure stylesheets themselves do not carry any mime type
250: * specification, the choice of available theme stylesheets determines if a certain
251: * structure is available for a given mime type.
252: *
253: * @param mimeType mime type that should be supported
254: * @return a <code>Hashtable</code> mapping stylesheet id (<code>Integer</code> objects) to {@link StructureStylesheetDescription} objects
255: */
256: public Hashtable getStructureStylesheetList(String mimeType)
257: throws Exception;
258:
259: /** Obtains a list of theme stylesheets available for a particular structure stylesheet.
260: *
261: * @param structureStylesheetId id of the structure stylehsset
262: * @return a <code>Hashtable</code> mapping stylesheet id (<code>Integer</code> objects) to {@link ThemeStylesheetDescription} objects
263: */
264: public Hashtable getThemeStylesheetList(int structureStylesheetId)
265: throws Exception;
266:
267: /**
268: * Obtain a list of strcture stylesheet descriptions registered on the system
269: * @return a <code>Hashtable</code> mapping stylesheet id (<code>Integer</code> objects) to {@link StructureStylesheetDescription} objects
270: * @exception Exception
271: */
272: public Hashtable getStructureStylesheetList() throws Exception;
273:
274: /**
275: * Obtain a list of theme stylesheet descriptions registered on the system
276: * @return a <code>Hashtable</code> mapping stylesheet id (<code>Integer</code> objects) to {@link ThemeStylesheetDescription} objects
277: * @exception Exception
278: */
279: public Hashtable getThemeStylesheetList() throws Exception;
280:
281: /** Obtains a list of mime types available on the installation
282: *
283: * @return Returns a hasbtale mapping mime type strings to their word
284: * descriptions (simple String)
285: */
286: public Hashtable getMimeTypeList() throws Exception;
287:
288: // functions that allow access to the entire CoreStylesheetDescription object.
289: // These functions are used when working with the stylesheet, and not for browsing purposes.
290: /** Obtains a complete description of the structure stylesheet
291: *
292: * @param stylesheetId id of the structure stylesheet
293: * @return a description of the structure stylesheet
294: */
295: public StructureStylesheetDescription getStructureStylesheetDescription(
296: int stylesheetId) throws Exception;
297:
298: /** Obtains a complete description of a theme stylesheet
299: *
300: * @param stylesheetId id of a theme stylesheet
301: * @return a description of a theme stylesheet
302: */
303: public ThemeStylesheetDescription getThemeStylesheetDescription(
304: int stylesheetId) throws Exception;
305:
306: // functions that allow to manage core stylesheet description collection
307: /** removes stylesheet description
308: *
309: * @param stylesheetId id of the stylesheet
310: */
311: public void removeStructureStylesheetDescription(int stylesheetId)
312: throws Exception;
313:
314: /** Removes theme stylesheet
315: *
316: * @param stylesheetId id of the stylesheet
317: */
318: public void removeThemeStylesheetDescription(int stylesheetId)
319: throws Exception;
320:
321: /** Registers new structure stylesheet with the portal database
322: *
323: * @param stylesheetDescriptionURI Location of the stylesheet description XML file
324: * @param stylesheetURI Location of the actual stylesshet XML file
325: * @return id assigned to the stylesheet or null if the operation failed
326: */
327: public Integer addStructureStylesheetDescription(
328: String stylesheetDescriptionURI, String stylesheetURI)
329: throws Exception;
330:
331: /**
332: * Updates an existing structure stylesheet description.
333: * @param stylesheetDescriptionURI Location of the stylesheet description XML file
334: * @param stylesheetURI Location of the actual stylesshet XML file
335: * @param stylesheetId the id of the existing stylesheet description
336: * @return true if the update successful
337: */
338: public boolean updateStructureStylesheetDescription(
339: String stylesheetDescriptionURI, String stylesheetURI,
340: int stylesheetId);
341:
342: /**
343: * Updates an existing theme stylesheet description.
344: * @param stylesheetDescriptionURI Location of the stylesheet description XML file
345: * @param stylesheetURI Location of the actual stylesshet XML file
346: * @param stylesheetId the id of the existing stylesheet description
347: * @return true if the update successful
348: */
349: public boolean updateThemeStylesheetDescription(
350: String stylesheetDescriptionURI, String stylesheetURI,
351: int stylesheetId) throws Exception;
352:
353: /** Registers a new theme stylesheet with the portal databases
354: *
355: * @param stylesheetDescriptionURI Location of the stylesheet description
356: * XML file
357: * @param stylesheetURI Location of the actual stylesheet XML file
358: * @return id assigned to the stylesheet or null if the operation failed
359: */
360: public Integer addThemeStylesheetDescription(
361: String stylesheetDescriptionURI, String stylesheetURI)
362: throws Exception;
363:
364: }
|