1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 package org.apache.jetspeed.page;
19
20 import javax.security.auth.Subject;
21
22 import org.apache.jetspeed.om.common.SecurityConstraint;
23 import org.apache.jetspeed.om.common.SecurityConstraints;
24 import org.apache.jetspeed.om.folder.Folder;
25 import org.apache.jetspeed.om.folder.FolderNotFoundException;
26 import org.apache.jetspeed.om.folder.InvalidFolderException;
27 import org.apache.jetspeed.om.folder.MenuDefinition;
28 import org.apache.jetspeed.om.folder.MenuExcludeDefinition;
29 import org.apache.jetspeed.om.folder.MenuIncludeDefinition;
30 import org.apache.jetspeed.om.folder.MenuOptionsDefinition;
31 import org.apache.jetspeed.om.folder.MenuSeparatorDefinition;
32 import org.apache.jetspeed.om.page.ContentPage;
33 import org.apache.jetspeed.om.page.Fragment;
34 import org.apache.jetspeed.om.page.Link;
35 import org.apache.jetspeed.om.page.Page;
36 import org.apache.jetspeed.om.page.PageSecurity;
37 import org.apache.jetspeed.om.page.SecurityConstraintsDef;
38 import org.apache.jetspeed.om.preference.FragmentPreference;
39 import org.apache.jetspeed.page.document.DocumentException;
40 import org.apache.jetspeed.page.document.DocumentNotFoundException;
41 import org.apache.jetspeed.page.document.FailedToDeleteDocumentException;
42 import org.apache.jetspeed.page.document.FailedToUpdateDocumentException;
43 import org.apache.jetspeed.page.document.NodeException;
44 import org.apache.jetspeed.page.document.NodeSet;
45 import org.apache.jetspeed.page.document.UnsupportedDocumentTypeException;
46
47
48 /***
49 * This service is responsible for loading and saving Pages into
50 * the selected persistent store.
51 *
52 * @version $Id: PageManager.java 516448 2007-03-09 16:25:47Z ate $
53 */
54 public interface PageManager
55 {
56 /*** The name of the service */
57 public String SERVICE_NAME = "PageManager";
58
59 /***
60 * <p>
61 * getConstraintsEnabled
62 * </p>
63 *
64 * @return enabled indicator
65 */
66 public boolean getConstraintsEnabled();
67
68 /***
69 * <p>
70 * getPermissionsEnabled
71 * </p>
72 *
73 * @return enabled indicator
74 */
75 public boolean getPermissionsEnabled();
76
77 /***
78 * Creates a new empty Page instance
79 *
80 * @return a newly created Page object
81 */
82 public Page newPage(String path);
83
84 /***
85 * Create a new empty Folder instance
86 *
87 * @return a newly created Folder object
88 */
89 public Folder newFolder(String path);
90
91 /***
92 * Creates a new empty Link instance
93 *
94 * @return a newly created Link object
95 */
96 public Link newLink(String path);
97
98 /***
99 * Creates a new empty PageSecurity instance
100 *
101 * @return a newly created PageSecurity object
102 */
103 public PageSecurity newPageSecurity();
104
105 /***
106 * Creates a new empty Layout Fragment instance
107 *
108 * @return a newly created Fragment object
109 */
110 public Fragment newFragment();
111
112 /***
113 * Creates a new empty Portlet Fragment instance
114 *
115 * @return a newly created Fragment object
116 */
117 public Fragment newPortletFragment();
118
119 /***
120 * newFolderMenuDefinition - creates a new empty menu definition
121 *
122 * @return a newly created MenuDefinition object to be used in Folder
123 */
124 public MenuDefinition newFolderMenuDefinition();
125
126 /***
127 * newFolderMenuExcludeDefinition - creates a new empty menu exclude definition
128 *
129 * @return a newly created MenuExcludeDefinition object to be used in Folder
130 */
131 public MenuExcludeDefinition newFolderMenuExcludeDefinition();
132
133 /***
134 * newFolderMenuIncludeDefinition - creates a new empty menu include definition
135 *
136 * @return a newly created MenuIncludeDefinition object to be used in Folder
137 */
138 public MenuIncludeDefinition newFolderMenuIncludeDefinition();
139
140 /***
141 * newFolderMenuOptionsDefinition - creates a new empty menu options definition
142 *
143 * @return a newly created MenuOptionsDefinition object to be used in Folder
144 */
145 public MenuOptionsDefinition newFolderMenuOptionsDefinition();
146
147 /***
148 * newFolderMenuSeparatorDefinition - creates a new empty menu separator definition
149 *
150 * @return a newly created MenuSeparatorDefinition object to be used in Folder
151 */
152 public MenuSeparatorDefinition newFolderMenuSeparatorDefinition();
153
154 /***
155 * newPageMenuDefinition - creates a new empty menu definition
156 *
157 * @return a newly created MenuDefinition object to be used in Page
158 */
159 public MenuDefinition newPageMenuDefinition();
160
161 /***
162 * newPageMenuExcludeDefinition - creates a new empty menu exclude definition
163 *
164 * @return a newly created MenuExcludeDefinition object to be used in Page
165 */
166 public MenuExcludeDefinition newPageMenuExcludeDefinition();
167
168 /***
169 * newPageMenuIncludeDefinition - creates a new empty menu include definition
170 *
171 * @return a newly created MenuIncludeDefinition object to be used in Page
172 */
173 public MenuIncludeDefinition newPageMenuIncludeDefinition();
174
175 /***
176 * newPageMenuOptionsDefinition - creates a new empty menu options definition
177 *
178 * @return a newly created MenuOptionsDefinition object to be used in Page
179 */
180 public MenuOptionsDefinition newPageMenuOptionsDefinition();
181
182 /***
183 * newPageMenuSeparatorDefinition - creates a new empty menu separator definition
184 *
185 * @return a newly created MenuSeparatorDefinition object to be used in Page
186 */
187 public MenuSeparatorDefinition newPageMenuSeparatorDefinition();
188
189 /***
190 * newSecurityConstraints - creates a new empty security constraints definition
191 *
192 * @return a newly created SecurityConstraints object
193 */
194 public SecurityConstraints newSecurityConstraints();
195
196 /***
197 * newFolderSecurityConstraint - creates a new security constraint definition
198 *
199 * @return a newly created SecurityConstraint object to be used in Folder
200 */
201 public SecurityConstraint newFolderSecurityConstraint();
202
203 /***
204 * newPageSecurityConstraint - creates a new security constraint definition
205 *
206 * @return a newly created SecurityConstraint object to be used in Page
207 */
208 public SecurityConstraint newPageSecurityConstraint();
209
210 /***
211 * newFragmentSecurityConstraint - creates a new security constraint definition
212 *
213 * @return a newly created SecurityConstraint object to be used in Fragment
214 */
215 public SecurityConstraint newFragmentSecurityConstraint();
216
217 /***
218 * newLinkSecurityConstraint - creates a new security constraint definition
219 *
220 * @return a newly created SecurityConstraint object to be used in Link
221 */
222 public SecurityConstraint newLinkSecurityConstraint();
223
224 /***
225 * newPageSecuritySecurityConstraint - creates a new security constraint definition
226 *
227 * @return a newly created SecurityConstraint object to be used in PageSecurity
228 */
229 public SecurityConstraint newPageSecuritySecurityConstraint();
230
231 /***
232 * newSecurityConstraintsDef - creates a new security constraints definition
233 *
234 * @return a newly created SecurityConstraintsDef object
235 */
236 public SecurityConstraintsDef newSecurityConstraintsDef();
237
238 /***
239 * newFragmentPreference - creates a new fragment preference
240 *
241 * @return a newly created FragmentPreference
242 */
243 public FragmentPreference newFragmentPreference();
244
245 /***
246 * <p>
247 * getPage
248 * </p>
249 *
250 * Returns a Page based on its path
251 *
252 * @param path
253 * @throws PageNotFoundException if the page cannot be found
254 * @throws NodeException
255 */
256 public Page getPage(String path) throws PageNotFoundException, NodeException;
257
258 /***
259 * <p>
260 * ContentPage
261 * </p>
262 *
263 * Returns a PSML document suitable for use in content
264 * rendering, for the given key
265 *
266 * @see ContentPage
267 * @see Fragment
268 * @param locator The locator descriptor of the document to be retrieved.
269 * @throws PageNotFoundException if the page cannot be found
270 * @throws NodeException
271 */
272 public ContentPage getContentPage(String path) throws PageNotFoundException, NodeException;
273
274 /***
275 * <p>
276 * getLink
277 * </p>
278 *
279 * Returns a Link document for the given path
280 *
281 * @param name The path of the document to be retrieved.
282 * @throws PageNotFoundException if the page cannot be found
283 * @throws NodeException
284 */
285 public Link getLink(String name) throws DocumentNotFoundException, UnsupportedDocumentTypeException, NodeException;
286
287 /***
288 * <p>
289 * getPageSecurity
290 * </p>
291 *
292 * Returns the PageSecurity document
293 *
294 * @throws DocumentNotFoundException if the document cannot be found
295 * @throws UnsupportedDocumentTypeException
296 * @throws NodeException
297 */
298 public PageSecurity getPageSecurity() throws DocumentNotFoundException, UnsupportedDocumentTypeException, NodeException;
299
300 /***
301 * <p>
302 * getFolder
303 * </p>
304 *
305 * Locates a folder for the given path.
306 *
307 * @param folderPath
308 * @return <code>Folder</code> object represented by the <code>folderPath</code>
309 * @throws FolderNotFoundException
310 * @throws NodeException
311 * @throws InvalidFolderException
312 */
313 public Folder getFolder(String folderPath) throws FolderNotFoundException, InvalidFolderException, NodeException;
314
315 /***
316 * <p>
317 * getFolders
318 * </p>
319 *
320 * Locates folders within a specified parent folder.
321 * Returned documents are filtered according to security
322 * constraints and/or permissions.
323 *
324 * @see org.apache.jetspeed.om.folder.Folder#getFolders(org.apache.jetspeed.om.folder.Folder)
325 *
326 * @param folder The parent folder.
327 * @return A <code>NodeSet</code> containing all sub-folders
328 * directly under this folder.
329 * @throws DocumentException
330 */
331 public NodeSet getFolders(Folder folder) throws DocumentException;
332
333 /***
334 * <p>
335 * getFolder
336 * </p>
337 *
338 * Locates folders within a specified parent folder.
339 * Returned documents are filtered according to security
340 * constraints and/or permissions.
341 *
342 * @see org.apache.jetspeed.om.folder.Folder#getFolder(org.apache.jetspeed.om.folder.Folder,java.lang.String)
343 *
344 * @param folder The parent folder.
345 * @param name The name of folder to retrieve.
346 * @return A Folder referenced by this folder.
347 * @throws FolderNotFoundException
348 * @throws DocumentException
349 */
350 public Folder getFolder(Folder folder, String name) throws FolderNotFoundException, DocumentException;
351
352 /***
353 * <p>
354 * getPages
355 * </p>
356 *
357 * Locates documents within a specified parent folder.
358 * Returned documents are filtered according to security
359 * constraints and/or permissions.
360 *
361 * @see org.apache.jetspeed.om.folder.Folder#getPages(org.apache.jetspeed.om.folder.Folder)
362 *
363 * @param folder The parent folder.
364 * @return A <code>NodeSet</code> of all the Pages referenced
365 * by this Folder.
366 * @throws NodeException
367 */
368 public NodeSet getPages(Folder folder) throws NodeException;
369
370 /***
371 * <p>
372 * getPage
373 * </p>
374 *
375 * Locates documents within a specified parent folder.
376 * Returned documents are filtered according to security
377 * constraints and/or permissions.
378 *
379 * @see org.apache.jetspeed.om.folder.Folder#getPage(org.apache.jetspeed.om.folder.Folder,java.lang.String)
380 *
381 * @param folder The parent folder.
382 * @param name The name of page to retrieve.
383 * @return A Page referenced by this folder.
384 * @throws PageNotFoundException if the Page requested could not be found.
385 * @throws NodeException
386 */
387 public Page getPage(Folder folder, String name) throws PageNotFoundException, NodeException;
388
389 /***
390 * <p>
391 * getLinks
392 * </p>
393 *
394 * @see org.apache.jetspeed.om.folder.Folder#getLinks(org.apache.jetspeed.om.folder.Folder)
395 *
396 * Locates documents within a specified parent folder.
397 * Returned documents are filtered according to security
398 * constraints and/or permissions.
399 *
400 * @param folder The parent folder.
401 * @return NodeSet of all the Links referenced by this Folder.
402 * @throws NodeException
403 */
404 public NodeSet getLinks(Folder folder) throws NodeException;
405
406 /***
407 * <p>
408 * getLink
409 * </p>
410 *
411 * Locates documents within a specified parent folder.
412 * Returned documents are filtered according to security
413 * constraints and/or permissions.
414 *
415 * @see org.apache.jetspeed.om.folder.Folder#getLink(org.apache.jetspeed.om.folder.Folder,java.lang.String)
416 *
417 * @param folder The parent folder.
418 * @param name The name of page to retrieve.
419 * @return A Link referenced by this folder.
420 * @throws DocumentNotFoundException if the document requested could not be found.
421 * @throws NodeException
422 */
423 public Link getLink(Folder folder, String name) throws DocumentNotFoundException, NodeException;
424
425 /***
426 * <p>
427 * getPageSecurity
428 * </p>
429 *
430 * Locates documents within a specified parent folder.
431 * Returned documents are filtered according to security
432 * constraints and/or permissions.
433 *
434 * @see org.apache.jetspeed.om.folder.Folder#getPageSecurity(org.apache.jetspeed.om.folder.Folder)
435 *
436 * @param folder The parent folder.
437 * @return A PageSecurity referenced by this folder.
438 * @throws DocumentNotFoundException if the document requested could not be found.
439 * @throws NodeException
440 */
441 public PageSecurity getPageSecurity(Folder folder) throws DocumentNotFoundException, NodeException;
442
443 /***
444 * <p>
445 * getAll
446 * </p>
447 *
448 * Locates folders and documents within a specified parent folder.
449 * Returned folders and documents are filtered according to
450 * security constraints and/or permissions.
451 *
452 * @see org.apache.jetspeed.om.folder.Folder#getAll(org.apache.jetspeed.om.folder.Folder)
453 *
454 * @param folder The parent folder.
455 * @return A <code>NodeSet</code> containing all sub-folders
456 * and documents directly under this folder.
457 * @throws DocumentException
458 */
459 public NodeSet getAll(Folder folder) throws DocumentException;
460
461 /*** Update a page in persistent storage
462 *
463 * @param page The page to be updated.
464 */
465 public void updatePage(Page page) throws NodeException, PageNotUpdatedException;
466
467 /*** Remove a document.
468 *
469 * @param page The page to be removed.
470 */
471 public void removePage(Page page) throws NodeException, PageNotRemovedException;
472
473 /*** Update a folder and all child folders
474 * and documents in persistent storage
475 *
476 * @param folder The folder to be updated.
477 */
478 public void updateFolder(Folder folder) throws NodeException, FolderNotUpdatedException;
479
480 /*** Update a folder in persistent storage
481 *
482 * @param folder The folder to be updated.
483 * @param deep Flag to control recursive deep updates.
484 */
485 public void updateFolder(Folder folder, boolean deep) throws NodeException, FolderNotUpdatedException;
486
487 /*** Remove a folder.
488 *
489 * @param page The folder to be removed.
490 */
491 public void removeFolder(Folder folder) throws NodeException, FolderNotRemovedException;
492
493 /*** Update a link in persistent storage
494 *
495 * @param link The link to be updated.
496 */
497 public void updateLink(Link link) throws NodeException, LinkNotUpdatedException;
498
499 /*** Remove a link.
500 *
501 * @param link The link to be removed.
502 */
503 public void removeLink(Link link) throws NodeException, LinkNotRemovedException;
504
505 /*** Update a page security document in persistent storage
506 *
507 * @param pageSecurity The document to be updated.
508 */
509 public void updatePageSecurity(PageSecurity pageSecurity) throws NodeException, FailedToUpdateDocumentException;
510
511 /*** Remove a page security document.
512 *
513 * @param pageSecurity The document to be removed.
514 */
515 public void removePageSecurity(PageSecurity pageSecurity) throws NodeException, FailedToDeleteDocumentException;
516
517 /***
518 * addListener - add page manager event listener
519 *
520 * @param listener page manager event listener
521 */
522 public void addListener(PageManagerEventListener listener);
523
524 /***
525 * removeListener - remove page manager event listener
526 *
527 * @param listener page manager event listener
528 */
529 public void removeListener(PageManagerEventListener listener);
530
531 /***
532 * reset - force subsequent refresh from persistent store
533 */
534 public void reset();
535
536 /***
537 * Copy the source page creating and returning a new copy of the page
538 * with the same portlet and fragment collection as the source
539 * All fragments are created with new fragment ids
540 *
541 * @param source The source Page object to be copied
542 * @param path a PSML normalized path to the new page to be created
543 * @return a new Page object copied from the source, with new fragment ids
544 */
545 public Page copyPage(Page source, String path)
546 throws NodeException;
547
548 /***
549 * Copy the source link creating and returning a new copy of the link
550 *
551 * @param source The source Link object to be copied
552 * @param path a PSML normalized path to the new link to be created
553 * @return a new Link object copied from the source
554 */
555 public Link copyLink(Link source, String path)
556 throws NodeException;
557
558 /***
559 * Copy the source folder creating and returning a new copy of the folder
560 * with the same content as the source
561 * All subobjects are created with new ids
562 *
563 * @param source The source Folder object to be copied
564 * @param path a PSML normalized path to the new folder to be created
565 * @return a new Folder object copied from the source, with new subobject ids
566 */
567 public Folder copyFolder(Folder source, String path)
568 throws NodeException;
569
570 /***
571 * Copy the source fragment creating and returning a new copy of the fragment
572 * with the parameter collection as the source
573 * The fragment is created with a new fragment id
574 *
575 * @param source The source Fragment object to be copied
576 * @param the new fragment name, can be the same as source fragment name
577 * @return a new Fragment object copied from the source
578 */
579 public Fragment copyFragment(Fragment source, String name)
580 throws NodeException;
581
582 /***
583 * Copy the source page security (both global constraints and constraint references)
584 * creating and returning a new copy of the page security definition.
585 *
586 * @param source The source PageSecurity definitions
587 * @return the new page security object
588 * @throws NodeException
589 */
590 public PageSecurity copyPageSecurity(PageSecurity source)
591 throws NodeException;
592
593 /***
594 * Deep copy a folder. Copies a folder and all subcontents including
595 * other folders, subpages, links, menus, security, fragments.
596 *
597 * @param source source folder
598 * @param dest destination folder
599 * @param owner set owner of the new folder(s), or null for no owner
600 */
601 public void deepCopyFolder(Folder srcFolder, String destinationPath, String owner)
602 throws NodeException;
603
604 /***
605 * Retrieve a page for the given user name and page name
606 *
607 * @param userName
608 * @param pageName
609 * @return
610 * @throws PageNotFoundException
611 * @throws NodeException
612 */
613 public Page getUserPage(String userName, String pageName)
614 throws PageNotFoundException, NodeException;
615
616 /***
617 * Retrieve a user's folder
618 *
619 * @param userName
620 * @return
621 * @throws FolderNotFoundException
622 * @throws InvalidFolderException
623 * @throws NodeException
624 */
625 public Folder getUserFolder(String userName)
626 throws FolderNotFoundException, InvalidFolderException, NodeException;
627
628 /***
629 * Check if a folder exists for the given folder name
630 *
631 * @param folderName
632 * @return
633 */
634 public boolean folderExists(String folderName);
635
636 /***
637 * Check if a page exists for the given page name
638 *
639 * @param pageName
640 * @return
641 */
642 public boolean pageExists(String pageName);
643
644 /***
645 * Check if a link exists for the given link name
646 *
647 * @param linkName
648 * @return
649 */
650 public boolean linkExists(String linkName);
651
652 /***
653 * Check if the root folder exists for a given user
654 *
655 * @param userName
656 * @return
657 */
658 public boolean userFolderExists(String userName);
659
660 /***
661 * Check if a page exists for the given user
662 *
663 * @param userName
664 * @param pageName
665 * @return
666 */
667 public boolean userPageExists(String userName, String pageName);
668
669 /***
670 * Creates a user's home page from the roles of the current user.
671 * The use case: when a portal is setup to use shared pages, but then
672 * the user attempts to customize. At this point, we create the new page(s) for the user.
673 *
674 * @param subject The full user Java Security subject.
675 */
676 public void createUserHomePagesFromRoles(Subject subject)
677 throws NodeException;
678
679 /***
680 *
681 * @param pages
682 * @return
683 * @throws NodeException
684 */
685 public int addPages(Page[] pages)
686 throws NodeException;
687
688 /***
689 * For a given security constraint definition name, and the given action(s),
690 * make a constraint check for the current user subject
691 *
692 * @param securityConstraintName the name of the security constraint definition
693 * @param actions one or more portlet actions (view,edit,help,..)
694 * @return
695 */
696 public boolean checkConstraint(String securityConstraintName, String actions);
697 }