001: /*
002: JSPWiki - a JSP-based WikiWiki clone.
003:
004: Copyright (C) 2001-2002 Janne Jalkanen (Janne.Jalkanen@iki.fi)
005:
006: This program is free software; you can redistribute it and/or modify
007: it under the terms of the GNU Lesser General Public License as published by
008: the Free Software Foundation; either version 2.1 of the License, or
009: (at your option) any later version.
010:
011: This program is distributed in the hope that it will be useful,
012: but WITHOUT ANY WARRANTY; without even the implied warranty of
013: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
014: GNU Lesser General Public License for more details.
015:
016: You should have received a copy of the GNU Lesser General Public License
017: along with this program; if not, write to the Free Software
018: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
019: */
020: package com.ecyrd.jspwiki.providers;
021:
022: import java.io.InputStream;
023: import java.io.IOException;
024:
025: import java.util.Collection;
026: import java.util.Date;
027: import java.util.List;
028:
029: import com.ecyrd.jspwiki.*;
030: import com.ecyrd.jspwiki.attachment.Attachment;
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: * @author Erik Bunn
044: * @author Janne Jalkanen
045: */
046: public interface WikiAttachmentProvider extends WikiProvider {
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: public void putAttachmentData(Attachment att, InputStream data)
056: throws ProviderException, IOException;
057:
058: /**
059: * Get attachment data.
060: *
061: * @param att The attachment
062: * @return An InputStream which you contains the raw data of the object. It's your
063: * responsibility to close it.
064: * @throws ProviderException If the attachment cannot be found
065: * @throws IOException If the attachment cannot be opened
066: */
067:
068: public InputStream getAttachmentData(Attachment att)
069: throws ProviderException, IOException;
070:
071: /**
072: * Lists all attachments attached to a page.
073: *
074: * @param page The page to list the attachments from.
075: * @return A collection of Attachment objects. May be empty, but never null.
076: * @throws ProviderException If something goes wrong when listing the attachments.
077: */
078:
079: public Collection listAttachments(WikiPage page)
080: throws ProviderException;
081:
082: /**
083: * Finds attachments based on the query.
084: * @param query An array of QueryItem objects to search for
085: * @return A Collection of Attachment objects. May be empty, but never null.
086: */
087: public Collection findAttachments(QueryItem[] query);
088:
089: /**
090: * Lists changed attachments since given date. Can also be used to fetch
091: * a list of all pages.
092: * <P>
093: * This is different from WikiPageProvider, where you basically get a list
094: * of all pages, then sort them locally. However, since some providers
095: * can be more efficient in locating recently changed files (like any database)
096: * than our non-optimized Java
097: * code, it makes more sense to fetch the whole list this way.
098: * <P>
099: * To get all files, call this with Date(0L);
100: *
101: * @param timestamp List all files from this date onward.
102: * @return A List of Attachment objects, in most-recently-changed first order.
103: * @throws ProviderException If something goes wrong.
104: */
105: public List listAllChanged(Date timestamp) throws ProviderException;
106:
107: /**
108: * Returns info about an attachment.
109: *
110: * @param page The parent page
111: * @param name The name of the attachment
112: * @param version The version of the attachment (it's okay to use WikiPage.LATEST_VERSION to find the latest one)
113: * @return An attachment object
114: * @throws ProviderException If the attachment cannot be found or some other error occurs.
115: */
116: public Attachment getAttachmentInfo(WikiPage page, String name,
117: int version) throws ProviderException;
118:
119: /**
120: * Returns version history. Each element should be
121: * an Attachment.
122: *
123: * @param att The attachment for which to find the version history for.
124: * @return A List of Attachment objects.
125: */
126: public List getVersionHistory(Attachment att);
127:
128: /**
129: * Removes a specific version from the repository. The implementations
130: * should really do no more security checks, since that is the domain
131: * of the AttachmentManager. Just delete it as efficiently as you can.
132: *
133: * @since 2.0.19.
134: *
135: * @param att Attachment to be removed. The version field is checked, and thus
136: * only that version is removed.
137: *
138: * @throws ProviderException If the attachment cannot be removed for some reason.
139: */
140:
141: public void deleteVersion(Attachment att) throws ProviderException;
142:
143: /**
144: * Removes an entire page from the repository. The implementations
145: * should really do no more security checks, since that is the domain
146: * of the AttachmentManager. Just delete it as efficiently as you can. You should also
147: * delete any auxiliary files and directories that belong to this attachment,
148: * IF they were created
149: * by this provider.
150: *
151: * @since 2.0.17.
152: *
153: * @param att Attachment to delete.
154: *
155: * @throws ProviderException If the page could not be removed for some reason.
156: */
157: public void deleteAttachment(Attachment att)
158: throws ProviderException;
159:
160: /**
161: * Move all the attachments for a given page so that they are attached to a
162: * new page.
163: *
164: * @param oldParent Name of the page we are to move the attachments from.
165: * @param newParent Name of the page we are to move the attachments to.
166: *
167: * @throws ProviderException If the attachments could not be moved for some
168: * reason.
169: */
170: public void moveAttachmentsForPage(String oldParent,
171: String newParent) throws ProviderException;
172: }
|