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