001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.jetspeed.page;
019:
020: import javax.security.auth.Subject;
021:
022: import org.apache.jetspeed.om.common.SecurityConstraint;
023: import org.apache.jetspeed.om.common.SecurityConstraints;
024: import org.apache.jetspeed.om.folder.Folder;
025: import org.apache.jetspeed.om.folder.FolderNotFoundException;
026: import org.apache.jetspeed.om.folder.InvalidFolderException;
027: import org.apache.jetspeed.om.folder.MenuDefinition;
028: import org.apache.jetspeed.om.folder.MenuExcludeDefinition;
029: import org.apache.jetspeed.om.folder.MenuIncludeDefinition;
030: import org.apache.jetspeed.om.folder.MenuOptionsDefinition;
031: import org.apache.jetspeed.om.folder.MenuSeparatorDefinition;
032: import org.apache.jetspeed.om.page.ContentPage;
033: import org.apache.jetspeed.om.page.Fragment;
034: import org.apache.jetspeed.om.page.Link;
035: import org.apache.jetspeed.om.page.Page;
036: import org.apache.jetspeed.om.page.PageSecurity;
037: import org.apache.jetspeed.om.page.SecurityConstraintsDef;
038: import org.apache.jetspeed.om.preference.FragmentPreference;
039: import org.apache.jetspeed.page.document.DocumentException;
040: import org.apache.jetspeed.page.document.DocumentNotFoundException;
041: import org.apache.jetspeed.page.document.FailedToDeleteDocumentException;
042: import org.apache.jetspeed.page.document.FailedToUpdateDocumentException;
043: import org.apache.jetspeed.page.document.NodeException;
044: import org.apache.jetspeed.page.document.NodeSet;
045: import org.apache.jetspeed.page.document.UnsupportedDocumentTypeException;
046:
047: /**
048: * This service is responsible for loading and saving Pages into
049: * the selected persistent store.
050: *
051: * @version $Id: PageManager.java 516448 2007-03-09 16:25:47Z ate $
052: */
053: public interface PageManager {
054: /** The name of the service */
055: public String SERVICE_NAME = "PageManager";
056:
057: /**
058: * <p>
059: * getConstraintsEnabled
060: * </p>
061: *
062: * @return enabled indicator
063: */
064: public boolean getConstraintsEnabled();
065:
066: /**
067: * <p>
068: * getPermissionsEnabled
069: * </p>
070: *
071: * @return enabled indicator
072: */
073: public boolean getPermissionsEnabled();
074:
075: /**
076: * Creates a new empty Page instance
077: *
078: * @return a newly created Page object
079: */
080: public Page newPage(String path);
081:
082: /**
083: * Create a new empty Folder instance
084: *
085: * @return a newly created Folder object
086: */
087: public Folder newFolder(String path);
088:
089: /**
090: * Creates a new empty Link instance
091: *
092: * @return a newly created Link object
093: */
094: public Link newLink(String path);
095:
096: /**
097: * Creates a new empty PageSecurity instance
098: *
099: * @return a newly created PageSecurity object
100: */
101: public PageSecurity newPageSecurity();
102:
103: /**
104: * Creates a new empty Layout Fragment instance
105: *
106: * @return a newly created Fragment object
107: */
108: public Fragment newFragment();
109:
110: /**
111: * Creates a new empty Portlet Fragment instance
112: *
113: * @return a newly created Fragment object
114: */
115: public Fragment newPortletFragment();
116:
117: /**
118: * newFolderMenuDefinition - creates a new empty menu definition
119: *
120: * @return a newly created MenuDefinition object to be used in Folder
121: */
122: public MenuDefinition newFolderMenuDefinition();
123:
124: /**
125: * newFolderMenuExcludeDefinition - creates a new empty menu exclude definition
126: *
127: * @return a newly created MenuExcludeDefinition object to be used in Folder
128: */
129: public MenuExcludeDefinition newFolderMenuExcludeDefinition();
130:
131: /**
132: * newFolderMenuIncludeDefinition - creates a new empty menu include definition
133: *
134: * @return a newly created MenuIncludeDefinition object to be used in Folder
135: */
136: public MenuIncludeDefinition newFolderMenuIncludeDefinition();
137:
138: /**
139: * newFolderMenuOptionsDefinition - creates a new empty menu options definition
140: *
141: * @return a newly created MenuOptionsDefinition object to be used in Folder
142: */
143: public MenuOptionsDefinition newFolderMenuOptionsDefinition();
144:
145: /**
146: * newFolderMenuSeparatorDefinition - creates a new empty menu separator definition
147: *
148: * @return a newly created MenuSeparatorDefinition object to be used in Folder
149: */
150: public MenuSeparatorDefinition newFolderMenuSeparatorDefinition();
151:
152: /**
153: * newPageMenuDefinition - creates a new empty menu definition
154: *
155: * @return a newly created MenuDefinition object to be used in Page
156: */
157: public MenuDefinition newPageMenuDefinition();
158:
159: /**
160: * newPageMenuExcludeDefinition - creates a new empty menu exclude definition
161: *
162: * @return a newly created MenuExcludeDefinition object to be used in Page
163: */
164: public MenuExcludeDefinition newPageMenuExcludeDefinition();
165:
166: /**
167: * newPageMenuIncludeDefinition - creates a new empty menu include definition
168: *
169: * @return a newly created MenuIncludeDefinition object to be used in Page
170: */
171: public MenuIncludeDefinition newPageMenuIncludeDefinition();
172:
173: /**
174: * newPageMenuOptionsDefinition - creates a new empty menu options definition
175: *
176: * @return a newly created MenuOptionsDefinition object to be used in Page
177: */
178: public MenuOptionsDefinition newPageMenuOptionsDefinition();
179:
180: /**
181: * newPageMenuSeparatorDefinition - creates a new empty menu separator definition
182: *
183: * @return a newly created MenuSeparatorDefinition object to be used in Page
184: */
185: public MenuSeparatorDefinition newPageMenuSeparatorDefinition();
186:
187: /**
188: * newSecurityConstraints - creates a new empty security constraints definition
189: *
190: * @return a newly created SecurityConstraints object
191: */
192: public SecurityConstraints newSecurityConstraints();
193:
194: /**
195: * newFolderSecurityConstraint - creates a new security constraint definition
196: *
197: * @return a newly created SecurityConstraint object to be used in Folder
198: */
199: public SecurityConstraint newFolderSecurityConstraint();
200:
201: /**
202: * newPageSecurityConstraint - creates a new security constraint definition
203: *
204: * @return a newly created SecurityConstraint object to be used in Page
205: */
206: public SecurityConstraint newPageSecurityConstraint();
207:
208: /**
209: * newFragmentSecurityConstraint - creates a new security constraint definition
210: *
211: * @return a newly created SecurityConstraint object to be used in Fragment
212: */
213: public SecurityConstraint newFragmentSecurityConstraint();
214:
215: /**
216: * newLinkSecurityConstraint - creates a new security constraint definition
217: *
218: * @return a newly created SecurityConstraint object to be used in Link
219: */
220: public SecurityConstraint newLinkSecurityConstraint();
221:
222: /**
223: * newPageSecuritySecurityConstraint - creates a new security constraint definition
224: *
225: * @return a newly created SecurityConstraint object to be used in PageSecurity
226: */
227: public SecurityConstraint newPageSecuritySecurityConstraint();
228:
229: /**
230: * newSecurityConstraintsDef - creates a new security constraints definition
231: *
232: * @return a newly created SecurityConstraintsDef object
233: */
234: public SecurityConstraintsDef newSecurityConstraintsDef();
235:
236: /**
237: * newFragmentPreference - creates a new fragment preference
238: *
239: * @return a newly created FragmentPreference
240: */
241: public FragmentPreference newFragmentPreference();
242:
243: /**
244: * <p>
245: * getPage
246: * </p>
247: *
248: * Returns a Page based on its path
249: *
250: * @param path
251: * @throws PageNotFoundException if the page cannot be found
252: * @throws NodeException
253: */
254: public Page getPage(String path) throws PageNotFoundException,
255: NodeException;
256:
257: /**
258: * <p>
259: * ContentPage
260: * </p>
261: *
262: * Returns a PSML document suitable for use in content
263: * rendering, for the given key
264: *
265: * @see ContentPage
266: * @see Fragment
267: * @param locator The locator descriptor of the document to be retrieved.
268: * @throws PageNotFoundException if the page cannot be found
269: * @throws NodeException
270: */
271: public ContentPage getContentPage(String path)
272: 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,
286: UnsupportedDocumentTypeException, NodeException;
287:
288: /**
289: * <p>
290: * getPageSecurity
291: * </p>
292: *
293: * Returns the PageSecurity document
294: *
295: * @throws DocumentNotFoundException if the document cannot be found
296: * @throws UnsupportedDocumentTypeException
297: * @throws NodeException
298: */
299: public PageSecurity getPageSecurity()
300: throws DocumentNotFoundException,
301: UnsupportedDocumentTypeException, NodeException;
302:
303: /**
304: * <p>
305: * getFolder
306: * </p>
307: *
308: * Locates a folder for the given path.
309: *
310: * @param folderPath
311: * @return <code>Folder</code> object represented by the <code>folderPath</code>
312: * @throws FolderNotFoundException
313: * @throws NodeException
314: * @throws InvalidFolderException
315: */
316: public Folder getFolder(String folderPath)
317: throws FolderNotFoundException, InvalidFolderException,
318: NodeException;
319:
320: /**
321: * <p>
322: * getFolders
323: * </p>
324: *
325: * Locates folders within a specified parent folder.
326: * Returned documents are filtered according to security
327: * constraints and/or permissions.
328: *
329: * @see org.apache.jetspeed.om.folder.Folder#getFolders(org.apache.jetspeed.om.folder.Folder)
330: *
331: * @param folder The parent folder.
332: * @return A <code>NodeSet</code> containing all sub-folders
333: * directly under this folder.
334: * @throws DocumentException
335: */
336: public NodeSet getFolders(Folder folder) throws DocumentException;
337:
338: /**
339: * <p>
340: * getFolder
341: * </p>
342: *
343: * Locates folders within a specified parent folder.
344: * Returned documents are filtered according to security
345: * constraints and/or permissions.
346: *
347: * @see org.apache.jetspeed.om.folder.Folder#getFolder(org.apache.jetspeed.om.folder.Folder,java.lang.String)
348: *
349: * @param folder The parent folder.
350: * @param name The name of folder to retrieve.
351: * @return A Folder referenced by this folder.
352: * @throws FolderNotFoundException
353: * @throws DocumentException
354: */
355: public Folder getFolder(Folder folder, String name)
356: throws FolderNotFoundException, DocumentException;
357:
358: /**
359: * <p>
360: * getPages
361: * </p>
362: *
363: * Locates documents within a specified parent folder.
364: * Returned documents are filtered according to security
365: * constraints and/or permissions.
366: *
367: * @see org.apache.jetspeed.om.folder.Folder#getPages(org.apache.jetspeed.om.folder.Folder)
368: *
369: * @param folder The parent folder.
370: * @return A <code>NodeSet</code> of all the Pages referenced
371: * by this Folder.
372: * @throws NodeException
373: */
374: public NodeSet getPages(Folder folder) throws NodeException;
375:
376: /**
377: * <p>
378: * getPage
379: * </p>
380: *
381: * Locates documents within a specified parent folder.
382: * Returned documents are filtered according to security
383: * constraints and/or permissions.
384: *
385: * @see org.apache.jetspeed.om.folder.Folder#getPage(org.apache.jetspeed.om.folder.Folder,java.lang.String)
386: *
387: * @param folder The parent folder.
388: * @param name The name of page to retrieve.
389: * @return A Page referenced by this folder.
390: * @throws PageNotFoundException if the Page requested could not be found.
391: * @throws NodeException
392: */
393: public Page getPage(Folder folder, String name)
394: throws PageNotFoundException, NodeException;
395:
396: /**
397: * <p>
398: * getLinks
399: * </p>
400: *
401: * @see org.apache.jetspeed.om.folder.Folder#getLinks(org.apache.jetspeed.om.folder.Folder)
402: *
403: * Locates documents within a specified parent folder.
404: * Returned documents are filtered according to security
405: * constraints and/or permissions.
406: *
407: * @param folder The parent folder.
408: * @return NodeSet of all the Links referenced by this Folder.
409: * @throws NodeException
410: */
411: public NodeSet getLinks(Folder folder) throws NodeException;
412:
413: /**
414: * <p>
415: * getLink
416: * </p>
417: *
418: * Locates documents within a specified parent folder.
419: * Returned documents are filtered according to security
420: * constraints and/or permissions.
421: *
422: * @see org.apache.jetspeed.om.folder.Folder#getLink(org.apache.jetspeed.om.folder.Folder,java.lang.String)
423: *
424: * @param folder The parent folder.
425: * @param name The name of page to retrieve.
426: * @return A Link referenced by this folder.
427: * @throws DocumentNotFoundException if the document requested could not be found.
428: * @throws NodeException
429: */
430: public Link getLink(Folder folder, String name)
431: throws DocumentNotFoundException, NodeException;
432:
433: /**
434: * <p>
435: * getPageSecurity
436: * </p>
437: *
438: * Locates documents within a specified parent folder.
439: * Returned documents are filtered according to security
440: * constraints and/or permissions.
441: *
442: * @see org.apache.jetspeed.om.folder.Folder#getPageSecurity(org.apache.jetspeed.om.folder.Folder)
443: *
444: * @param folder The parent folder.
445: * @return A PageSecurity referenced by this folder.
446: * @throws DocumentNotFoundException if the document requested could not be found.
447: * @throws NodeException
448: */
449: public PageSecurity getPageSecurity(Folder folder)
450: throws DocumentNotFoundException, NodeException;
451:
452: /**
453: * <p>
454: * getAll
455: * </p>
456: *
457: * Locates folders and documents within a specified parent folder.
458: * Returned folders and documents are filtered according to
459: * security constraints and/or permissions.
460: *
461: * @see org.apache.jetspeed.om.folder.Folder#getAll(org.apache.jetspeed.om.folder.Folder)
462: *
463: * @param folder The parent folder.
464: * @return A <code>NodeSet</code> containing all sub-folders
465: * and documents directly under this folder.
466: * @throws DocumentException
467: */
468: public NodeSet getAll(Folder folder) throws DocumentException;
469:
470: /** Update a page in persistent storage
471: *
472: * @param page The page to be updated.
473: */
474: public void updatePage(Page page) throws NodeException,
475: PageNotUpdatedException;
476:
477: /** Remove a document.
478: *
479: * @param page The page to be removed.
480: */
481: public void removePage(Page page) throws NodeException,
482: PageNotRemovedException;
483:
484: /** Update a folder and all child folders
485: * and documents in persistent storage
486: *
487: * @param folder The folder to be updated.
488: */
489: public void updateFolder(Folder folder) throws NodeException,
490: FolderNotUpdatedException;
491:
492: /** Update a folder in persistent storage
493: *
494: * @param folder The folder to be updated.
495: * @param deep Flag to control recursive deep updates.
496: */
497: public void updateFolder(Folder folder, boolean deep)
498: throws NodeException, FolderNotUpdatedException;
499:
500: /** Remove a folder.
501: *
502: * @param page The folder to be removed.
503: */
504: public void removeFolder(Folder folder) throws NodeException,
505: FolderNotRemovedException;
506:
507: /** Update a link in persistent storage
508: *
509: * @param link The link to be updated.
510: */
511: public void updateLink(Link link) throws NodeException,
512: LinkNotUpdatedException;
513:
514: /** Remove a link.
515: *
516: * @param link The link to be removed.
517: */
518: public void removeLink(Link link) throws NodeException,
519: LinkNotRemovedException;
520:
521: /** Update a page security document in persistent storage
522: *
523: * @param pageSecurity The document to be updated.
524: */
525: public void updatePageSecurity(PageSecurity pageSecurity)
526: throws NodeException, FailedToUpdateDocumentException;
527:
528: /** Remove a page security document.
529: *
530: * @param pageSecurity The document to be removed.
531: */
532: public void removePageSecurity(PageSecurity pageSecurity)
533: throws NodeException, FailedToDeleteDocumentException;
534:
535: /**
536: * addListener - add page manager event listener
537: *
538: * @param listener page manager event listener
539: */
540: public void addListener(PageManagerEventListener listener);
541:
542: /**
543: * removeListener - remove page manager event listener
544: *
545: * @param listener page manager event listener
546: */
547: public void removeListener(PageManagerEventListener listener);
548:
549: /**
550: * reset - force subsequent refresh from persistent store
551: */
552: public void reset();
553:
554: /**
555: * Copy the source page creating and returning a new copy of the page
556: * with the same portlet and fragment collection as the source
557: * All fragments are created with new fragment ids
558: *
559: * @param source The source Page object to be copied
560: * @param path a PSML normalized path to the new page to be created
561: * @return a new Page object copied from the source, with new fragment ids
562: */
563: public Page copyPage(Page source, String path) throws NodeException;
564:
565: /**
566: * Copy the source link creating and returning a new copy of the link
567: *
568: * @param source The source Link object to be copied
569: * @param path a PSML normalized path to the new link to be created
570: * @return a new Link object copied from the source
571: */
572: public Link copyLink(Link source, String path) throws NodeException;
573:
574: /**
575: * Copy the source folder creating and returning a new copy of the folder
576: * with the same content as the source
577: * All subobjects are created with new ids
578: *
579: * @param source The source Folder object to be copied
580: * @param path a PSML normalized path to the new folder to be created
581: * @return a new Folder object copied from the source, with new subobject ids
582: */
583: public Folder copyFolder(Folder source, String path)
584: throws NodeException;
585:
586: /**
587: * Copy the source fragment creating and returning a new copy of the fragment
588: * with the parameter collection as the source
589: * The fragment is created with a new fragment id
590: *
591: * @param source The source Fragment object to be copied
592: * @param the new fragment name, can be the same as source fragment name
593: * @return a new Fragment object copied from the source
594: */
595: public Fragment copyFragment(Fragment source, String name)
596: throws NodeException;
597:
598: /**
599: * Copy the source page security (both global constraints and constraint references)
600: * creating and returning a new copy of the page security definition.
601: *
602: * @param source The source PageSecurity definitions
603: * @return the new page security object
604: * @throws NodeException
605: */
606: public PageSecurity copyPageSecurity(PageSecurity source)
607: throws NodeException;
608:
609: /**
610: * Deep copy a folder. Copies a folder and all subcontents including
611: * other folders, subpages, links, menus, security, fragments.
612: *
613: * @param source source folder
614: * @param dest destination folder
615: * @param owner set owner of the new folder(s), or null for no owner
616: */
617: public void deepCopyFolder(Folder srcFolder,
618: String destinationPath, String owner) throws NodeException;
619:
620: /**
621: * Retrieve a page for the given user name and page name
622: *
623: * @param userName
624: * @param pageName
625: * @return
626: * @throws PageNotFoundException
627: * @throws NodeException
628: */
629: public Page getUserPage(String userName, String pageName)
630: throws PageNotFoundException, NodeException;
631:
632: /**
633: * Retrieve a user's folder
634: *
635: * @param userName
636: * @return
637: * @throws FolderNotFoundException
638: * @throws InvalidFolderException
639: * @throws NodeException
640: */
641: public Folder getUserFolder(String userName)
642: throws FolderNotFoundException, InvalidFolderException,
643: NodeException;
644:
645: /**
646: * Check if a folder exists for the given folder name
647: *
648: * @param folderName
649: * @return
650: */
651: public boolean folderExists(String folderName);
652:
653: /**
654: * Check if a page exists for the given page name
655: *
656: * @param pageName
657: * @return
658: */
659: public boolean pageExists(String pageName);
660:
661: /**
662: * Check if a link exists for the given link name
663: *
664: * @param linkName
665: * @return
666: */
667: public boolean linkExists(String linkName);
668:
669: /**
670: * Check if the root folder exists for a given user
671: *
672: * @param userName
673: * @return
674: */
675: public boolean userFolderExists(String userName);
676:
677: /**
678: * Check if a page exists for the given user
679: *
680: * @param userName
681: * @param pageName
682: * @return
683: */
684: public boolean userPageExists(String userName, String pageName);
685:
686: /**
687: * Creates a user's home page from the roles of the current user.
688: * The use case: when a portal is setup to use shared pages, but then
689: * the user attempts to customize. At this point, we create the new page(s) for the user.
690: *
691: * @param subject The full user Java Security subject.
692: */
693: public void createUserHomePagesFromRoles(Subject subject)
694: throws NodeException;
695:
696: /**
697: *
698: * @param pages
699: * @return
700: * @throws NodeException
701: */
702: public int addPages(Page[] pages) throws NodeException;
703:
704: /**
705: * For a given security constraint definition name, and the given action(s),
706: * make a constraint check for the current user subject
707: *
708: * @param securityConstraintName the name of the security constraint definition
709: * @param actions one or more portlet actions (view,edit,help,..)
710: * @return
711: */
712: public boolean checkConstraint(String securityConstraintName,
713: String actions);
714: }
|