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 */ 019package org.apache.wiki.api.providers; 020 021import org.apache.wiki.api.core.Page; 022import org.apache.wiki.api.exceptions.ProviderException; 023import org.apache.wiki.api.search.QueryItem; 024import org.apache.wiki.api.search.SearchResult; 025 026import java.util.Collection; 027import java.util.Date; 028import java.util.List; 029 030 031/** 032 * Each Wiki page provider should implement this interface. 033 * <P> 034 * You can build whatever page providers based on this. Every method has to be implemented, but the ones a provider has no use for should 035 * behave as if there was nothing to report instead of failing: return an empty collection, a version history that holds only the latest 036 * version, or do nothing for a version that is not kept. The file providers in jspwiki-main work this way. 037 * <P> 038 * WikiPageProvider uses Strings and ints to refer to pages. This may be a bit odd, since WikiAttachmentProviders all use Attachment 039 * instead of name/version. We will perhaps modify these in the future. In the mean time, name/version is quite sufficient. 040 * <P> 041 * FIXME: In reality we should have an AbstractWikiPageProvider, which would provide intelligent backups for subclasses. 042 */ 043public interface PageProvider extends WikiProvider { 044 045 /** 046 * Attempts to save the page text for page "page". Note that the provider creates a new version regardless of what the version 047 * parameter of the WikiPage is. 048 * 049 * @param page The WikiPage to save 050 * @param text The text to save. 051 * @throws ProviderException If something goes wrong. 052 */ 053 void putPageText( Page page, String text ) throws ProviderException; 054 055 /** 056 * Return true, if page exists. 057 * 058 * @param page The page name. 059 * @return true, if the page exists; false otherwise. 060 */ 061 boolean pageExists( String page ); 062 063 /** 064 * Return true, if page with a particular version exists. 065 * 066 * @param page The page name to check for 067 * @param version The version to check 068 * @return True, if page exists; false otherwise. 069 */ 070 boolean pageExists( String page, int version ); 071 072 /** 073 * Finds pages based on the query. Only applicable to providers which implement the FastSearch interface. Otherwise JSPWiki 074 * will use its internal cache. 075 * <p> 076 * This method should really be a part of the FastSearch IF. 077 * 078 * @param query An array of QueryItems to match 079 * @return A Collection of WikiPages. 080 */ 081 Collection< SearchResult > findPages( QueryItem[] query ); 082 083 /** 084 * Returns info about the page. 085 * 086 * @return A filled WikiPage. 087 * @param page The page name 088 * @param version The version number 089 * @throws ProviderException If something goes wrong. 090 */ 091 Page getPageInfo( String page, int version ) throws ProviderException; 092 093 /** 094 * Returns all pages. Each element in the returned Collection should be a WikiPage. 095 * 096 * @return A collection of WikiPages 097 * @throws ProviderException If something goes wrong. 098 */ 099 Collection< Page > getAllPages() throws ProviderException; 100 101 /** 102 * Gets a list of recent changes. 103 * 104 * @param date The date to check from 105 * @return A Collection of WikiPages 106 * @since 1.6.4 107 */ 108 Collection< Page > getAllChangedSince( Date date ); 109 110 /** 111 * Gets the number of pages. 112 * 113 * @return The number of pages in the repository 114 * @throws ProviderException If something goes wrong 115 * @since 1.6.4 116 */ 117 int getPageCount() throws ProviderException; 118 119 /** 120 * Returns version history. Each element should be a WikiPage. 121 * 122 * @param page The name of the page to get the history from. 123 * @return A collection of WikiPages. 124 * @throws ProviderException If something goes wrong. 125 */ 126 List< Page > getVersionHistory( String page ) throws ProviderException; 127 128 /** 129 * Gets a specific version out of the repository. 130 * 131 * @param page Name of the page to fetch. 132 * @param version Version of the page to fetch. 133 * @return The content of the page, or null, if the page does not exist. 134 * @throws ProviderException If something goes wrong. 135 */ 136 String getPageText( String page, int version ) throws ProviderException; 137 138 /** 139 * Removes a specific version from the repository. The implementations should really do no more security checks, since that is the 140 * domain of the PageManager. Just delete it as efficiently as you can. 141 * 142 * @since 2.0.17. 143 * @param pageName Name of the page to be removed. 144 * @param version Version of the page to be removed. May be LATEST_VERSION. 145 * @throws ProviderException If the page cannot be removed for some reason. 146 */ 147 void deleteVersion( String pageName, int version ) throws ProviderException; 148 149 /** 150 * Removes an entire page from the repository. The implementations should really do no more security checks, since that is the domain 151 * of the PageManager. Just delete it as efficiently as you can. You should also delete any auxiliary files that belong to this page, 152 * IF they were created by this provider. 153 * 154 * <P>The reason why this is named differently from deleteVersion() (logically, this method should be an overloaded version) is that 155 * I want to be absolutely sure I don't accidentally use the wrong method. With overloading something like that happens sometimes... 156 * 157 * @since 2.0.17. 158 * @param pageName Name of the page to be removed completely. 159 * @throws ProviderException If the page could not be removed for some reason. 160 */ 161 void deletePage( String pageName ) throws ProviderException; 162 163 /** 164 * Move a page 165 * 166 * @param from Name of the page to move. 167 * @param to New name of the page. 168 * @throws ProviderException If the page could not be moved for some reason. 169 */ 170 void movePage( String from, String to ) throws ProviderException; 171 172}