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.io.InputStream;
022 import java.io.IOException;
023 import java.util.Collection;
024 import java.util.Date;
025 import java.util.List;
026
027 import org.apache.wiki.*;
028 import org.apache.wiki.api.exceptions.ProviderException;
029 import org.apache.wiki.attachment.Attachment;
030 import org.apache.wiki.search.QueryItem;
031
032 /**
033 * Defines an attachment provider - a class which is capable of saving
034 * binary data as attachments.
035 * <P>
036 * The difference between this class and WikiPageProvider is that there
037 * PageProviders handle Unicode text, whereas we handle binary data.
038 * While there are quite a lot of similarities in how we handle
039 * things, many providers can really use just one. In addition,
040 * since binary files can be really large, we rely on
041 * Input/OutputStreams.
042 *
043 */
044 public interface WikiAttachmentProvider
045 extends WikiProvider
046 {
047 /**
048 * Put new attachment data.
049 *
050 * @param att Attachment object to add new data to
051 * @param data The stream from which the provider should read the data
052 * @throws IOException If writing fails
053 * @throws ProviderException If there are other errors.
054 */
055 void putAttachmentData( Attachment att, InputStream data )
056 throws ProviderException,
057 IOException;
058
059 /**
060 * Get attachment data.
061 *
062 * @param att The attachment
063 * @return An InputStream which you contains the raw data of the object. It's your
064 * responsibility to close it.
065 * @throws ProviderException If the attachment cannot be found
066 * @throws IOException If the attachment cannot be opened
067 */
068
069 InputStream getAttachmentData( Attachment att )
070 throws ProviderException,
071 IOException;
072
073 /**
074 * Lists all attachments attached to a page.
075 *
076 * @param page The page to list the attachments from.
077 * @return A collection of Attachment objects. May be empty, but never null.
078 * @throws ProviderException If something goes wrong when listing the attachments.
079 */
080
081 Collection listAttachments( WikiPage page )
082 throws ProviderException;
083
084 /**
085 * Finds attachments based on the query.
086 * @param query An array of QueryItem objects to search for
087 * @return A Collection of Attachment objects. May be empty, but never null.
088 */
089 Collection findAttachments( QueryItem[] query );
090
091 /**
092 * Lists changed attachments since given date. Can also be used to fetch
093 * a list of all pages.
094 * <P>
095 * This is different from WikiPageProvider, where you basically get a list
096 * of all pages, then sort them locally. However, since some providers
097 * can be more efficient in locating recently changed files (like any database)
098 * than our non-optimized Java
099 * code, it makes more sense to fetch the whole list this way.
100 * <P>
101 * To get all files, call this with Date(0L);
102 *
103 * @param timestamp List all files from this date onward.
104 * @return A List of Attachment objects, in most-recently-changed first order.
105 * @throws ProviderException If something goes wrong.
106 */
107 List listAllChanged( Date timestamp )
108 throws ProviderException;
109
110 /**
111 * Returns info about an attachment.
112 *
113 * @param page The parent page
114 * @param name The name of the attachment
115 * @param version The version of the attachment (it's okay to use WikiPage.LATEST_VERSION to find the latest one)
116 * @return An attachment object
117 * @throws ProviderException If the attachment cannot be found or some other error occurs.
118 */
119 Attachment getAttachmentInfo( WikiPage page, String name, int version )
120 throws ProviderException;
121
122 /**
123 * Returns version history. Each element should be
124 * an Attachment.
125 *
126 * @param att The attachment for which to find the version history for.
127 * @return A List of Attachment objects.
128 */
129 List getVersionHistory( Attachment att );
130
131 /**
132 * Removes a specific version from the repository. The implementations
133 * should really do no more security checks, since that is the domain
134 * of the AttachmentManager. Just delete it as efficiently as you can.
135 *
136 * @since 2.0.19.
137 *
138 * @param att Attachment to be removed. The version field is checked, and thus
139 * only that version is removed.
140 *
141 * @throws ProviderException If the attachment cannot be removed for some reason.
142 */
143
144 void deleteVersion( Attachment att )
145 throws ProviderException;
146
147 /**
148 * Removes an entire page from the repository. The implementations
149 * should really do no more security checks, since that is the domain
150 * of the AttachmentManager. Just delete it as efficiently as you can. You should also
151 * delete any auxiliary files and directories that belong to this attachment,
152 * IF they were created
153 * by this provider.
154 *
155 * @since 2.0.17.
156 *
157 * @param att Attachment to delete.
158 *
159 * @throws ProviderException If the page could not be removed for some reason.
160 */
161 void deleteAttachment( Attachment att )
162 throws ProviderException;
163
164 /**
165 * Move all the attachments for a given page so that they are attached to a
166 * new page.
167 *
168 * @param oldParent Name of the page we are to move the attachments from.
169 * @param newParent Name of the page we are to move the attachments to.
170 *
171 * @throws ProviderException If the attachments could not be moved for some
172 * reason.
173 */
174 void moveAttachmentsForPage( String oldParent,
175 String newParent )
176 throws ProviderException;
177 }
178
179