001: /* Copyright 2002 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: import java.util.Enumeration;
009:
010: import javax.servlet.http.HttpServletRequest;
011:
012: import org.jasig.portal.PortalException;
013: import org.jasig.portal.UserPreferences;
014: import org.jasig.portal.layout.node.IUserLayoutNodeDescription;
015: import org.jasig.portal.security.IPerson;
016: import org.w3c.dom.Document;
017: import org.xml.sax.ContentHandler;
018:
019: /**
020: * An interface for abstracting operations performed on the user layout.
021: *
022: * @author Peter Kharchenko {@link <a href="mailto:pkharchenko@interactivebusiness.com"">pkharchenko@interactivebusiness.com"</a>}
023: * @author <a href="mailto:mvi@immagic.com">Michael Ivanov</a>
024: * @version 1.1
025: */
026: public interface IUserLayoutManager {
027: /**
028: * Gets a user layout (with appropriate markings).
029: *
030: * @return the user layout
031: * @exception PortalException if an error occurs
032: */
033: public IUserLayout getUserLayout() throws PortalException;
034:
035: /**
036: * Sets a user layout (with appropriate markings).
037: *
038: * @param userLayout the user layout
039: * @exception PortalException if an error occurs
040: */
041: public void setUserLayout(IUserLayout userLayout)
042: throws PortalException;
043:
044: /**
045: * Output user layout (with appropriate markings) into
046: * a <code>ContentHandler</code>
047: *
048: * @param ch a <code>ContentHandler</code> value
049: * @exception PortalException if an error occurs
050: */
051: public void getUserLayout(ContentHandler ch) throws PortalException;
052:
053: /**
054: * Output subtree of a user layout (with appropriate markings) defined by a particular node into
055: * a <code>ContentHandler</code>
056: *
057: * @param nodeId a <code>String</code> a node determining a user layout subtree.
058: * @param ch a <code>ContentHandler</code> value
059: * @exception PortalException if an error occurs
060: */
061: public void getUserLayout(String nodeId, ContentHandler ch)
062: throws PortalException;
063:
064: /**
065: * Set a user layout store implementation.
066: *
067: * @param ls an <code>IUserLayoutStore</code> value
068: */
069: public void setLayoutStore(IUserLayoutStore ls);
070:
071: /**
072: * Signal manager to load a user layout from a database
073: *
074: * @exception PortalException if an error occurs
075: */
076: public void loadUserLayout() throws PortalException;
077:
078: /**
079: * Signal manager to persist user layout to a database
080: *
081: * @exception PortalException if an error occurs
082: */
083: public void saveUserLayout() throws PortalException;
084:
085: /**
086: * Obtain a description of a node (channel or a folder) in a given user layout.
087: *
088: * @param nodeId a <code>String</code> channel subscribe id or folder id.
089: * @return an <code>UserLayoutNodeDescription</code> value
090: * @exception PortalException if an error occurs
091: */
092: public IUserLayoutNodeDescription getNode(String nodeId)
093: throws PortalException;
094:
095: /**
096: * Add a new node to a current user layout.
097: *
098: * @param node an <code>UserLayoutNodeDescription</code> value of a node to be added (Id doesn't have to be set)
099: * @param parentId a <code>String</code> id of a folder to which the new node (channel or folder) should be added.
100: * @param nextSiblingId a <code>String</code> an id of a sibling node (channel or folder) prior to which the new node should be inserted.
101: * @return an <code>UserLayoutNodeDescription</code> value with a newly determined Id.
102: * @exception PortalException if an error occurs
103: */
104: public IUserLayoutNodeDescription addNode(
105: IUserLayoutNodeDescription node, String parentId,
106: String nextSiblingId) throws PortalException;
107:
108: /**
109: * Move a node (channel or folder) from one location to another.
110: *
111: * @param nodeId a <code>String</code> value of a node Id.
112: * @param parentId a <code>String</code> id of a folder to which the node should be moved.
113: * @param nextSiblingId a <code>String</code> id of a sibling node (folder or channel) prior to which the node should be placed. (<code>null</code> to append at the end)
114: * @return a <code>boolean</code> value noting if the operation was successful
115: * @exception PortalException if an error occurs
116: */
117: public boolean moveNode(String nodeId, String parentId,
118: String nextSiblingId) throws PortalException;
119:
120: /**
121: * Delete a node (folder or a channel) from a user layout.
122: *
123: * @param nodeId a <code>String</code> id (channel subscribe id or folder id)
124: * @return a <code>boolean</code> value noting if the operation was successful
125: * @exception PortalException if an error occurs
126: */
127: public boolean deleteNode(String nodeId) throws PortalException;
128:
129: /**
130: * Update a given node.
131: *
132: * @param node an <code>UserLayoutNodeDescription</code> value with a valid id.
133: * @return a <code>boolean</code> value noting if the operation was successful
134: * @exception PortalException if an error occurs
135: */
136: public boolean updateNode(IUserLayoutNodeDescription node)
137: throws PortalException;
138:
139: /**
140: * Test if a particular node can be added at a given location.
141: *
142: * @param node an <code>UserLayoutNodeDescription</code> value describing the node to be added.
143: * @param parentId a <code>String</code> id of a parent to which the node to be added.
144: * @param nextSiblingId a <code>String</code> id of a sibling prior to which the node to be inserted. (<code>null</code> to append at the end)
145: * @return a <code>boolean</code> value
146: * @exception PortalException if an error occurs
147: */
148: public boolean canAddNode(IUserLayoutNodeDescription node,
149: String parentId, String nextSiblingId)
150: throws PortalException;
151:
152: /**
153: * Test if a particular node can be moved to a given location.
154: *
155: * @param nodeId a <code>String</code> id of a node to be moved.
156: * @param parentId a <code>String</code> id of a parent to which the node to be moved.
157: * @param nextSiblingId a <code>String</code> id of a sibling prior to which the node is to be inserted (<code>null</code> to append at the end)
158: * @return a <code>boolean</code> value
159: * @exception PortalException if an error occurs
160: */
161: public boolean canMoveNode(String nodeId, String parentId,
162: String nextSiblingId) throws PortalException;
163:
164: /**
165: * Tests if a particular node can be deleted.
166: *
167: * @param nodeId a <code>String</code> node id.
168: * @return a <code>boolean</code> value
169: * @exception PortalException if an error occurs
170: */
171: public boolean canDeleteNode(String nodeId) throws PortalException;
172:
173: /**
174: * Test if a certain node can be updated.
175: *
176: * @param node a <code>IUserLayoutNodeDescription</code> node id.
177: * @return a <code>boolean</code> value
178: * @exception PortalException if an error occurs
179: */
180: public boolean canUpdateNode(IUserLayoutNodeDescription node)
181: throws PortalException;
182:
183: /**
184: * Ask manager to output markings at the locations where a given node can be added.
185: * The marks will appear next time <code>getUserLayout</code> method is called.
186: *
187: * @param node an <code>UserLayoutNodeDescription</code> value or <code>null</code> to stop outputting add markings.
188: * @exception PortalException if an error occurs
189: */
190: public void markAddTargets(IUserLayoutNodeDescription node)
191: throws PortalException;
192:
193: /**
194: * Ask manager to output markings at the locations where a given node can be moved.
195: * The marks will appear next time <code>getUserLayout</code> method is called.
196: *
197: * @param nodeId a <code>String</code> value or <code>null</code> to stop outputting move markings.
198: * @exception PortalException if an error occurs
199: */
200: public void markMoveTargets(String nodeId) throws PortalException;
201:
202: /**
203: * Returns an Id of a parent user layout node.
204: * The user layout root node always has ID= {@link IUserLayout#ROOT_NODE_NAME}
205: *
206: * @param nodeId a <code>String</code> value
207: * @return a <code>String</code> value
208: * @exception PortalException if an error occurs
209: */
210: public String getParentId(String nodeId) throws PortalException;
211:
212: /**
213: * Returns a list of child node Ids for a given node.
214: *
215: * @param nodeId a <code>String</code> value
216: * @return a <code>List</code> of <code>String</code> child node Ids.
217: * @exception PortalException if an error occurs
218: */
219: public Enumeration getChildIds(String nodeId)
220: throws PortalException;
221:
222: /**
223: * Determine an Id of a next sibling node.
224: *
225: * @param nodeId a <code>String</code> value
226: * @return a <code>String</code> Id value of a next sibling node, or <code>null</code> if this is the last sibling.
227: * @exception PortalException if an error occurs
228: */
229: public String getNextSiblingId(String nodeId)
230: throws PortalException;
231:
232: /**
233: * Determine an Id of a previous sibling node.
234: *
235: * @param nodeId a <code>String</code> value
236: * @return a <code>String</code> Id value of a previous sibling node, or <code>null</code> if this is the first sibling.
237: * @exception PortalException if an error occurs
238: */
239: public String getPreviousSiblingId(String nodeId)
240: throws PortalException;
241:
242: /**
243: * Return a cache key, uniqly corresponding to the composition and the structure of the user layout.
244: *
245: * @return a <code>String</code> value
246: * @exception PortalException if an error occurs
247: */
248: public String getCacheKey() throws PortalException;
249:
250: /**
251: * Register a layout event listener
252: *
253: * @param l a <code>LayoutEventListener</code> object
254: * @return a <code>boolean</code> success status
255: */
256: public boolean addLayoutEventListener(LayoutEventListener l);
257:
258: /**
259: * Remove a registered layout event listener.
260: *
261: * @param l a <code>LayoutEventListener</code> object
262: * @return a <code>boolean</code> success status
263: */
264: public boolean removeLayoutEventListener(LayoutEventListener l);
265:
266: // This method should be removed whenever it becomes possible
267: public Document getUserLayoutDOM() throws PortalException;
268:
269: /**
270: * Returns a layout Id associated with this manager/
271: *
272: * @return an <code>int</code> layout Id value;
273: */
274: public int getLayoutId();
275:
276: /**
277: * Returns a subscription id using the supplied functional name.
278: *
279: * @param fname the functional name to lookup
280: * @return a <code>String</code> subscription id
281: */
282: public String getSubscribeId(String fname) throws PortalException;
283:
284: /**
285: * Returns an id of the root folder.
286: *
287: * @return a <code>String</code> value
288: */
289: public String getRootFolderId();
290:
291: /**
292: * Returns the depth of a node in the layout tree.
293: *
294: * @param nodeId a <code>String</code> value
295: * @return a depth value
296: * @exception PortalException if an error occurs
297: */
298: public int getDepth(String nodeId) throws PortalException;
299:
300: /**
301: * A factory method to create an empty <code>IUserLayoutNodeDescription</code> instance
302: *
303: * @param nodeType a node type constant from <code>IUserLayoutNodeDescription</code> interface
304: * @return an <code>IUserLayoutNodeDescription</code> instance
305: * @exception PortalException if the error occurs.
306: */
307: public IUserLayoutNodeDescription createNodeDescription(int nodeType)
308: throws PortalException;
309:
310: /**
311: * Allows layout manager specific handling of user request parameter
312: * processing potentially including passing of specific parameters to the
313: * structure and theme transformations via the user preferences object.
314: */
315: public void processLayoutParameters(IPerson person,
316: UserPreferences userPrefs, HttpServletRequest req)
317: throws PortalException;
318: }
|