001 /*
002 Licensed to the Apache Software Foundation (ASF) under one
003 or more contributor license agreements. See the NOTICE file
004 distributed with this work for additional information
005 regarding copyright ownership. The ASF licenses this file
006 to you under the Apache License, Version 2.0 (the
007 "License"); you may not use this file except in compliance
008 with the License. You may obtain a copy of the License at
009
010 http://www.apache.org/licenses/LICENSE-2.0
011
012 Unless required by applicable law or agreed to in writing,
013 software distributed under the License is distributed on an
014 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 KIND, either express or implied. See the License for the
016 specific language governing permissions and limitations
017 under the License.
018 */
019 package org.apache.wiki.providers;
020
021 import java.util.List;
022 import java.util.Collection;
023 import java.util.Date;
024
025 import org.apache.wiki.*;
026 import org.apache.wiki.api.exceptions.ProviderException;
027 import org.apache.wiki.search.QueryItem;
028
029 /**
030 * Each Wiki page provider should implement this interface.
031 * <P>
032 * You can build whatever page providers based on this, just
033 * leave the unused methods do something useful.
034 * <P>
035 * WikiPageProvider uses Strings and ints to refer to pages. This may
036 * be a bit odd, since WikiAttachmentProviders all use Attachment
037 * instead of name/version. We will perhaps modify these in the
038 * future. In the mean time, name/version is quite sufficient.
039 * <P>
040 * FIXME: In reality we should have an AbstractWikiPageProvider,
041 * which would provide intelligent backups for subclasses.
042 *
043 */
044 public interface WikiPageProvider
045 extends WikiProvider
046 {
047 /**
048 * Attempts to save the page text for page "page". Note that the
049 * provider creates a new version regardless of what the version
050 * parameter of the WikiPage is.
051 *
052 * @param page The WikiPage to save
053 * @param text The text to save.
054 * @throws ProviderException If something goes wrong.
055 */
056 void putPageText( WikiPage page, String text )
057 throws ProviderException;
058
059 /**
060 * Return true, if page exists.
061 *
062 * @param page The page name.
063 * @return true, if the page exists; false otherwise.
064 */
065
066 boolean pageExists( String page );
067
068 /**
069 * Return true, if page with a particular version exists.
070 *
071 * @param page The page name to check for
072 * @param version The version to check
073 * @return True, if page exists; false otherwise.
074 */
075
076 public boolean pageExists(String page, int version);
077
078 /**
079 * Finds pages based on the query. Only applicable to providers
080 * which implement the FastSearch interface. Otherwise JSPWiki
081 * will use its internal cache.
082 * <p>
083 * This method should really be a part of the FastSearch IF.
084 *
085 * @param query An array of QueryItems to match
086 * @return A Collection of WikiPages.
087 */
088 Collection findPages( QueryItem[] query );
089
090 /**
091 * Returns info about the page.
092 *
093 * @return A filled WikiPage.
094 * @param page The page name
095 * @param version The version number
096 * @throws ProviderException If something goes wrong.
097 */
098 WikiPage getPageInfo( String page, int version )
099 throws ProviderException;
100
101 /**
102 * Returns all pages. Each element in the returned
103 * Collection should be a WikiPage.
104 *
105 * @return A collection of WikiPages
106 * @throws ProviderException If something goes wrong.
107 */
108
109 Collection getAllPages()
110 throws ProviderException;
111
112 /**
113 * Gets a list of recent changes.
114 *
115 * @param date The date to check from
116 * @return A Collection of WikiPages
117 * @since 1.6.4
118 */
119
120 Collection getAllChangedSince( Date date );
121
122 /**
123 * Gets the number of pages.
124 *
125 * @return The number of pages in the repository
126 * @throws ProviderException If something goes wrong
127 * @since 1.6.4
128 */
129
130 int getPageCount()
131 throws ProviderException;
132
133 /**
134 * Returns version history. Each element should be
135 * a WikiPage.
136 *
137 * @param page The name of the page to get the history from.
138 * @return A collection of WikiPages.
139 * @throws ProviderException If something goes wrong.
140 */
141
142 List getVersionHistory( String page )
143 throws ProviderException;
144
145 /**
146 * Gets a specific version out of the repository.
147 *
148 * @param page Name of the page to fetch.
149 * @param version Version of the page to fetch.
150 *
151 * @return The content of the page, or null, if the page does not exist.
152 * @throws ProviderException If something goes wrong.
153 */
154
155 String getPageText( String page, int version )
156 throws ProviderException;
157
158 /**
159 * Removes a specific version from the repository. The implementations
160 * should really do no more security checks, since that is the domain
161 * of the PageManager. Just delete it as efficiently as you can.
162 *
163 * @since 2.0.17.
164 *
165 * @param pageName Name of the page to be removed.
166 * @param version Version of the page to be removed. May be LATEST_VERSION.
167 *
168 * @throws ProviderException If the page cannot be removed for some reason.
169 */
170
171 void deleteVersion( String pageName, int version )
172 throws ProviderException;
173
174 /**
175 * Removes an entire page from the repository. The implementations
176 * should really do no more security checks, since that is the domain
177 * of the PageManager. Just delete it as efficiently as you can. You should also
178 * delete any auxiliary files that belong to this page, IF they were created
179 * by this provider.
180 *
181 * <P>The reason why this is named differently from
182 * deleteVersion() (logically, this method should be an
183 * overloaded version) is that I want to be absolutely sure I
184 * don't accidentally use the wrong method. With overloading
185 * something like that happens sometimes...
186 *
187 * @since 2.0.17.
188 *
189 * @param pageName Name of the page to be removed completely.
190 *
191 * @throws ProviderException If the page could not be removed for some reason.
192 */
193 void deletePage( String pageName )
194 throws ProviderException;
195
196
197 /**
198 * Move a page
199 *
200 * @param from Name of the page to move.
201 * @param to New name of the page.
202 *
203 * @throws ProviderException If the page could not be moved for some reason.
204 */
205 void movePage(String from, String to)
206 throws ProviderException;
207
208 }
209
210
211
212