Package org.apache.wiki.api.providers

Interface AttachmentProvider

  • All Superinterfaces:
    WikiProvider
    All Known Implementing Classes:
    BasicAttachmentProvider, CachingAttachmentProvider, WikiAttachmentAdapterProvider
    public interface AttachmentProvider
extends WikiProvider
    Defines an attachment provider - a class which is capable of saving binary data as attachments.

    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.

    • Method Detail

      • putAttachmentData

        void putAttachmentData​(Attachment att,
                       java.io.InputStream data)
                throws ProviderException,
                       java.io.IOException
        Put new attachment data.
        Parameters:
        att - Attachment object to add new data to
        data - The stream from which the provider should read the data
        Throws:
        java.io.IOException - If writing fails
        ProviderException - If there are other errors.

      • getAttachmentData

        java.io.InputStream getAttachmentData​(Attachment att)
                               throws ProviderException,
                                      java.io.IOException
        Get attachment data.
        Parameters:
        att - The attachment
        Returns:
        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
        java.io.IOException - If the attachment cannot be opened

      • listAttachments

        java.util.List<Attachment> listAttachments​(Page page)
                                    throws ProviderException
        Lists all attachments attached to a page.
        Parameters:
        page - The page to list the attachments from.
        Returns:
        A collection of Attachment objects. May be empty, but never null.
        Throws:
        ProviderException - If something goes wrong when listing the attachments.

      • findAttachments

        java.util.Collection<Attachment> findAttachments​(QueryItem[] query)
        Finds attachments based on the query.
        Parameters:
        query - An array of QueryItem objects to search for
        Returns:
        A Collection of Attachment objects. May be empty, but never null.

      • listAllChanged

        java.util.List<Attachment> listAllChanged​(java.util.Date timestamp)
                                   throws ProviderException
        Lists changed attachments since given date. Can also be used to fetch a list of all pages.

        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.

        To get all files, call this with Date(0L);

        Parameters:
        timestamp - List all files from this date onward.
        Returns:
        A List of Attachment objects, in most-recently-changed first order.
        Throws:
        ProviderException - If something goes wrong.

      • getAttachmentInfo

        Attachment getAttachmentInfo​(Page page,
                             java.lang.String name,
                             int version)
                      throws ProviderException
        Returns info about an attachment.
        Parameters:
        page - The parent page
        name - The name of the attachment
        version - The version of the attachment (it's okay to use WikiPage.LATEST_VERSION to find the latest one)
        Returns:
        An attachment object
        Throws:
        ProviderException - If the attachment cannot be found or some other error occurs.

      • getVersionHistory

        java.util.List<Attachment> getVersionHistory​(Attachment att)
        Returns version history. Each element should be an Attachment.
        Parameters:
        att - The attachment for which to find the version history for.
        Returns:
        A List of Attachment objects.

      • deleteVersion

        void deleteVersion​(Attachment att)
            throws ProviderException
        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.
        Parameters:
        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.
        Since:
        2.0.19.

      • deleteAttachment

        void deleteAttachment​(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.
        Parameters:
        att - Attachment to delete.
        Throws:
        ProviderException - If the page could not be removed for some reason.
        Since:
        2.0.17.

      • moveAttachmentsForPage

        void moveAttachmentsForPage​(java.lang.String oldParent,
                            java.lang.String newParent)
                     throws ProviderException
        Move all the attachments for a given page so that they are attached to a new page.
        Parameters:
        oldParent - Name of the page we are to move the attachments from.
        newParent - Name of the page we are to move the attachments to.
        Throws:
        ProviderException - If the attachments could not be moved for some reason.