| /* |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| */ |
| package org.apache.wiki.api.providers; |
| |
| import org.apache.wiki.api.core.Attachment; |
| import org.apache.wiki.api.core.Page; |
| import org.apache.wiki.api.exceptions.ProviderException; |
| import org.apache.wiki.api.search.QueryItem; |
| |
| import java.io.IOException; |
| import java.io.InputStream; |
| import java.util.Collection; |
| import java.util.Date; |
| import java.util.List; |
| |
| |
| /** |
| * Defines an attachment provider - a class which is capable of saving binary data as attachments. |
| * <P> |
| * The difference between this class and WikiPageProvider is that there PageProviders handle Unicode text, whereas we handle binary data. |
| * While there are quite a lot of similarities in how we handle things, many providers can really use just one. In addition, |
| * since binary files can be really large, we rely on Input/OutputStreams. |
| */ |
| public interface AttachmentProvider extends WikiProvider { |
| |
| /** Property that supplies the directory used to store attachments. */ |
| String PROP_STORAGEDIR = "jspwiki.basicAttachmentProvider.storageDir"; |
| |
| /** |
| * Put new attachment data. |
| * |
| * @param att Attachment object to add new data to |
| * @param data The stream from which the provider should read the data |
| * @throws IOException If writing fails |
| * @throws ProviderException If there are other errors. |
| */ |
| void putAttachmentData( Attachment att, InputStream data ) throws ProviderException, IOException; |
| |
| /** |
| * Get attachment data. |
| * |
| * @param att The attachment |
| * @return An InputStream which contains the raw data of the object. It's your responsibility to close it. |
| * @throws ProviderException If the attachment cannot be found |
| * @throws IOException If the attachment cannot be opened |
| */ |
| InputStream getAttachmentData( Attachment att ) throws ProviderException, IOException; |
| |
| /** |
| * Lists all attachments attached to a page. |
| * |
| * @param page The page to list the attachments from. |
| * @return A collection of Attachment objects. May be empty, but never null. |
| * @throws ProviderException If something goes wrong when listing the attachments. |
| */ |
| List< Attachment > listAttachments( Page page ) throws ProviderException; |
| |
| /** |
| * Finds attachments based on the query. |
| * |
| * @param query An array of QueryItem objects to search for |
| * @return A Collection of Attachment objects. May be empty, but never null. |
| */ |
| Collection< Attachment > findAttachments( QueryItem[] query ); |
| |
| /** |
| * Lists changed attachments since given date. Can also be used to fetch a list of all pages. |
| * <P> |
| * This is different from WikiPageProvider, where you basically get a list of all pages, then sort them locally. However, since some |
| * providers can be more efficient in locating recently changed files (like any database) than our non-optimized Java code, it makes |
| * more sense to fetch the whole list this way. |
| * <P> |
| * To get all files, call this with Date(0L); |
| * |
| * @param timestamp List all files from this date onward. |
| * @return A List of Attachment objects, in most-recently-changed first order. |
| * @throws ProviderException If something goes wrong. |
| */ |
| List< Attachment > listAllChanged( Date timestamp ) throws ProviderException; |
| |
| /** |
| * Returns info about an attachment. |
| * |
| * @param page The parent page |
| * @param name The name of the attachment |
| * @param version The version of the attachment (it's okay to use WikiPage.LATEST_VERSION to find the latest one) |
| * @return An attachment object |
| * @throws ProviderException If the attachment cannot be found or some other error occurs. |
| */ |
| Attachment getAttachmentInfo( Page page, String name, int version ) throws ProviderException; |
| |
| /** |
| * Returns version history. Each element should be an Attachment. |
| * |
| * @param att The attachment for which to find the version history for. |
| * @return A List of Attachment objects. |
| */ |
| List< Attachment > getVersionHistory( Attachment att ); |
| |
| /** |
| * Removes a specific version from the repository. The implementations should really do no more security checks, since that is the |
| * domain of the AttachmentManager. Just delete it as efficiently as you can. |
| * |
| * @since 2.0.19. |
| * @param att Attachment to be removed. The version field is checked, and thus only that version is removed. |
| * @throws ProviderException If the attachment cannot be removed for some reason. |
| */ |
| void deleteVersion( Attachment att ) throws ProviderException; |
| |
| /** |
| * Removes an entire page from the repository. The implementations should really do no more security checks, since that is the domain |
| * of the AttachmentManager. Just delete it as efficiently as you can. You should also delete any auxiliary files and directories |
| * that belong to this attachment, IF they were created by this provider. |
| * |
| * @since 2.0.17. |
| * @param att Attachment to delete. |
| * @throws ProviderException If the page could not be removed for some reason. |
| */ |
| void deleteAttachment( Attachment att ) throws ProviderException; |
| |
| /** |
| * Move all the attachments for a given page so that they are attached to a new page. |
| * |
| * @param oldParent Name of the page we are to move the attachments from. |
| * @param newParent Name of the page we are to move the attachments to. |
| * @throws ProviderException If the attachments could not be moved for some reason. |
| */ |
| void moveAttachmentsForPage( String oldParent, String newParent ) throws ProviderException; |
| |
| } |
| |
| |