View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.jetspeed.page.document;
18  
19  import org.apache.jetspeed.om.folder.Folder;
20  import org.apache.jetspeed.om.folder.FolderNotFoundException;
21  import org.apache.jetspeed.om.folder.InvalidFolderException;
22  
23  /***
24   * <p>
25   * FolderHandler
26   * </p>
27   * <p>
28   *  
29   * </p>
30   * @author <a href="mailto:weaver@apache.org">Scott T. Weaver</a>
31   * @version $Id: FolderHandler.java 553584 2007-07-05 18:09:45Z taylor $
32   *
33   */
34  public interface FolderHandler
35  {
36      /***
37       * 
38       * <p>
39       * getFolder
40       * </p>
41       * <p>
42       *  Locates a folder given using the <code>path</code> argument.  This should behave
43       *  as <code>getFolder("folder/subfolder, true);</code>
44       * </p>
45       *
46       * @param path fully-quallified path to a folder
47       * @return Folder represented by the <code>path</code> argument.  Never returns <code>null</code>
48       * @throws DocumentException if there was an error processing the request.
49       * @throws InvalidFolderException
50       * @throws NodeException
51       * @throws DocumentNotFoundException If there is no folder at the <code>path</code> specified.
52       */
53      Folder getFolder(String path) throws FolderNotFoundException, InvalidFolderException, NodeException;
54      
55      /***
56       * 
57       * <p>
58       * updateFolder
59       * </p>
60       * <p>
61       *  Updates the folder specified with the <code>folder</code> argument.
62       * </p>
63       *
64       * @param folder folder to update
65       */
66      void updateFolder(Folder folder) throws FailedToUpdateFolderException;
67      
68      /***
69       * 
70       * <p>
71       * removeFolder
72       * </p>
73       * <p>
74       *  Removes the folder specified with the <code>folder</code> argument.
75       * </p>
76       *
77       * @param folder folder to update
78       */
79      void removeFolder(Folder folder) throws FailedToDeleteFolderException;
80      
81      /***
82       * 
83       * <p>
84       * getFolder
85       * </p>
86       * <p>
87       *  Locates a folder given using the <code>path</code> argument.  
88       * </p>
89       *
90       * @param path fully-quallified path to a folder
91       * @param fromCache whether or not to check the cache first before checking the underlying folder
92       * repository.
93       * @return Folder represented by the <code>path</code> argument.  Never returns <code>null</code>
94       * @throws DocumentException if there was an error processing the request.
95       * @throws InvalidFolderException
96       * @throws NodeException
97       * @throws DocumentNotFoundException If there is no folder at the <code>path</code> specified.
98       */
99      Folder getFolder(String path, boolean fromCache) throws FolderNotFoundException, InvalidFolderException, NodeException;
100     
101     /***
102      * 
103      * <p>
104      * getFolders
105      * </p>
106      *
107      * @param path Path from which to locate child folders
108      * @return NodeSet of sub-folders located under the <code>path</code> argument.
109      * @throws FolderNotFoundException if folder under the <code>path</code> does not actually
110      * exist
111      * @throws DocumentException if an error is encountered reading the folders.
112      * @throws InvalidFolderException
113      * @throws NodeException
114      */
115     NodeSet getFolders( String path ) throws FolderNotFoundException, InvalidFolderException, NodeException;
116     
117     /***
118      * 
119      * <p>
120      * list
121      * </p>
122      * <p>
123      *  generates a list of document names, relative to the <code>folderPath</code> argument
124      * of the type indicated by the <code>documentType</code> argument.
125      * </p>
126      * @param folderPath folder path to search under
127      * @param documentType document type to filter on.
128      * @return a <code>String[]</code> of child document names relative to the <code>folderPath</code>
129      * argument and matching the <code>documentType</code> argument.
130      * @throws FolderNotFoundException if the <code>folderPath</code> does not exsit.
131      */
132     String[] list(String folderPath, String documentType) throws FolderNotFoundException;
133     
134     String[] listAll(String folderPath) throws FolderNotFoundException;
135 
136     /***
137      * <p>
138      * getNodes
139      * </p>
140      * <p>
141      * Returns a set of nodes relative to the <code>folder</code> argument of the type
142      * indicated by the <code>documentType</code> argument. The <code>folder</code> argument
143      * may include regular expressions if indicated by the <code>regex</code> argument. The
144      * returned set is unordered.
145      * </p>
146      *
147      * @param path Path from which to locate documents
148      * @param regexp Flag indicating whether regexp should be expanded in path
149      * @param documentType document type to filter on.
150      * @return NodeSet of documents and folders located under the <code>path</code> argument.
151      * @throws FolderNotFoundException if folder under the <code>path</code> does not actually exist.
152      * @throws DocumentException if an error is encountered reading the folders.
153      * @throws InvalidFolderException
154      * @throws NodeException
155      */
156     NodeSet getNodes(String path, boolean regexp, String documentType) throws FolderNotFoundException, InvalidFolderException, NodeException;
157     
158     /***
159      * Returns true if the path is a folder
160      * 
161      * @param path
162      * @return
163      */
164     boolean isFolder(String path);
165     
166 }