Package org.apache.wiki.attachment

## Interface AttachmentManager

All Known Implementing Classes:
  `DefaultAttachmentManager`

    public interface AttachmentManager

Provides facilities for handling attachments. All attachment handling goes through this class.

The AttachmentManager provides a facade towards the current WikiAttachmentProvider that is in use. It is created by the Engine as a singleton object, and can be requested through the Engine.

Since:
  1.9.28

### Field Summary

Fields
`static java.lang.String` `PROP_ALLOWEDEXTENSIONS` A space-separated list of attachment types which can be uploaded
`static java.lang.String` `PROP_FORBIDDENEXTENSIONS` A space-separated list of attachment types which cannot be uploaded
`static java.lang.String` `PROP_FORCEDOWNLOAD` A space-separated list of attachment types which will never open in the browser.
`static java.lang.String` `PROP_MAXSIZE` The maximum size of attachments that can be uploaded.
`static java.lang.String` `PROP_PROVIDER` The property name for defining the attachment provider class name.
`static java.lang.String` `PROP_PROVIDER_DEPRECATED` Deprecated.

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
`boolean` `attachmentsEnabled()` Returns true, if attachments are enabled and running.
`void` `deleteAttachment​(Attachment att)` Deletes all versions of the given attachment.
`void` `deleteVersion​(Attachment att)` Deletes the given attachment version.
`boolean` `forceDownload​(java.lang.String name)` Check if attachement link should force a download iso opening the attachment in the browser.
`java.util.Collection<Attachment>` `getAllAttachments()` Returns a collection of Attachments, containing each and every attachment that is in this Wiki.
`default Attachment` `getAttachmentInfo​(java.lang.String name)` Gets info on a particular attachment, latest version.
`default Attachment` `getAttachmentInfo​(java.lang.String name, int version)` Gets info on a particular attachment with the given version.
`default Attachment` `getAttachmentInfo​(Context context, java.lang.String attachmentname)` Figures out the full attachment name from the context and attachment name.
`Attachment` `getAttachmentInfo​(Context context, java.lang.String attachmentname, int version)` Figures out the full attachment name from the context and attachment name.
`java.lang.String` `getAttachmentInfoName​(Context context, java.lang.String attachmentname)` Figures out the full attachment name from the context and attachment name.
`default java.io.InputStream` `getAttachmentStream​(Attachment att)` Finds a (real) attachment from the repository as an `InputStream`.
`java.io.InputStream` `getAttachmentStream​(Context ctx, Attachment att)` Returns an attachment stream using the particular WikiContext.
`AttachmentProvider` `getCurrentProvider()` Returns the current attachment provider.
`DynamicAttachment` `getDynamicAttachment​(java.lang.String name)` Finds a DynamicAttachment.
`java.util.List<Attachment>` `getVersionHistory​(java.lang.String attachmentName)` Returns a list of versions of the attachment.
`default boolean` `hasAttachments​(Page wikipage)` Returns true, if the page has any attachments at all.
`java.util.List<Attachment>` `listAttachments​(Page wikipage)` Returns the list of attachments associated with a given wiki page.
`default void` `storeAttachment​(Attachment att, java.io.File source)` Stores an attachment that lives in the given file.
`void` `storeAttachment​(Attachment att, java.io.InputStream in)` Stores an attachment directly from a stream.
`void` `storeDynamicAttachment​(Context ctx, DynamicAttachment att)` Stores a dynamic attachment.
`static java.lang.String` `validateFileName​(java.lang.String filename)` Validates the filename and makes sure it is legal.

### Field Detail

#### PROP_PROVIDER

    static final java.lang.String PROP_PROVIDER

The property name for defining the attachment provider class name.

See Also:
  Constant Field Values

#### PROP_PROVIDER_DEPRECATED

    @Deprecated
    static final java.lang.String PROP_PROVIDER_DEPRECATED

Deprecated.
The property name for defining the attachment provider class name.

See Also:
  Constant Field Values

#### PROP_MAXSIZE

    static final java.lang.String PROP_MAXSIZE

The maximum size of attachments that can be uploaded.

See Also:
  Constant Field Values

#### PROP_ALLOWEDEXTENSIONS

    static final java.lang.String PROP_ALLOWEDEXTENSIONS

A space-separated list of attachment types which can be uploaded

See Also:
  Constant Field Values

#### PROP_FORBIDDENEXTENSIONS

    static final java.lang.String PROP_FORBIDDENEXTENSIONS

A space-separated list of attachment types which cannot be uploaded

See Also:
  Constant Field Values

#### PROP_FORCEDOWNLOAD

    static final java.lang.String PROP_FORCEDOWNLOAD

A space-separated list of attachment types which will never open in the browser.

See Also:
  Constant Field Values

### Method Detail

#### attachmentsEnabled

    boolean attachmentsEnabled()

Returns true, if attachments are enabled and running.

Returns:
  A boolean value indicating whether attachment functionality is enabled.

#### getAttachmentInfo

    default Attachment getAttachmentInfo​(java.lang.String name)
                                  throws ProviderException

Gets info on a particular attachment, latest version.

Parameters:
  `name` - A full attachment name.
Returns:
  Attachment, or null, if no such attachment exists.
Throws:
  `ProviderException` - If something goes wrong.

#### getAttachmentInfo

    default Attachment getAttachmentInfo​(java.lang.String name,
                                         int version)
                                  throws ProviderException

Gets info on a particular attachment with the given version.

Parameters:
  `name` - A full attachment name.
  `version` - A version number.
Returns:
  Attachment, or null, if no such attachment or version exists.
Throws:
  `ProviderException` - If something goes wrong.

#### getAttachmentInfo

    default Attachment getAttachmentInfo​(Context context,
                                         java.lang.String attachmentname)
                                  throws ProviderException

Figures out the full attachment name from the context and attachment name.

Parameters:
  `context` - The current WikiContext
  `attachmentname` - The file name of the attachment.
Returns:
  Attachment, or null, if no such attachment exists.
Throws:
  `ProviderException` - If something goes wrong.

#### getAttachmentInfo

    Attachment getAttachmentInfo​(Context context,
                                 java.lang.String attachmentname,
                                 int version)
                          throws ProviderException

Figures out the full attachment name from the context and attachment name.

Parameters:
  `context` - The current WikiContext
  `attachmentname` - The file name of the attachment.
  `version` - A particular version.
Returns:
  Attachment, or null, if no such attachment or version exists.
Throws:
  `ProviderException` - If something goes wrong.

#### getAttachmentInfoName

    java.lang.String getAttachmentInfoName​(Context context,
                                           java.lang.String attachmentname)

Figures out the full attachment name from the context and attachment name.

Parameters:
  `context` - The current WikiContext
  `attachmentname` - The file name of the attachment.
Returns:
  Attachment, or null, if no such attachment exists.

#### listAttachments

    java.util.List<Attachment> listAttachments​(Page wikipage)
                                        throws ProviderException

Returns the list of attachments associated with a given wiki page. If there are no attachments, returns an empty Collection.

Parameters:
  `wikipage` - The wiki page from which you are seeking attachments for.
Returns:
  a valid collection of attachments.
Throws:
  `ProviderException` - If there was something wrong in the backend.

#### hasAttachments

    default boolean hasAttachments​(Page wikipage)

Returns true, if the page has any attachments at all. This is a convenience method.

Parameters:
  `wikipage` - The wiki page from which you are seeking attachments for.
Returns:
  True, if the page has attachments, else false.

#### forceDownload

    boolean forceDownload​(java.lang.String name)

Check if attachement link should force a download iso opening the attachment in the browser.

Parameters:
  `name` - Name of attachment to be checked
Returns:
  true, if the attachment should be downloaded when clicking the link
Since:
  2.11.0 M4

#### getAttachmentStream

    default java.io.InputStream getAttachmentStream​(Attachment att)
                                             throws java.io.IOException,
                                                    ProviderException

Finds a (real) attachment from the repository as an `InputStream`.

Parameters:
  `att` - Attachment
Returns:
  An InputStream to read from. May return null, if attachments are disabled.
Throws:
  `java.io.IOException` - If the stream cannot be opened
  `ProviderException` - If the backend fails due to some other reason.

#### getAttachmentStream

    java.io.InputStream getAttachmentStream​(Context ctx,
                                            Attachment att)
                                     throws ProviderException,
                                            java.io.IOException

Returns an attachment stream using the particular WikiContext. This method should be used instead of `getAttachmentStream(Attachment)`, since it also allows the DynamicAttachments to function.

Parameters:
  `ctx` - The Wiki Context
  `att` - The Attachment to find
Returns:
  An InputStream. May return null, if attachments are disabled. You must take care of closing it.
Throws:
  `ProviderException` - If the backend fails due to some reason
  `java.io.IOException` - If the stream cannot be opened

#### storeDynamicAttachment

    void storeDynamicAttachment​(Context ctx,
                                DynamicAttachment att)

Stores a dynamic attachment. Unlike storeAttachment(), this just stores the attachment in the memory.

Parameters:
  `ctx` - A WikiContext
  `att` - An attachment to store

#### getDynamicAttachment

    DynamicAttachment getDynamicAttachment​(java.lang.String name)

Finds a DynamicAttachment. Normally, you should just use `getAttachmentInfo(String)` , since that will find also `DynamicAttachment`s.

Parameters:
  `name` - The name of the attachment to look for
Returns:
  An Attachment, or null.
See Also:
  `getAttachmentInfo(String)`

#### storeAttachment

    default void storeAttachment​(Attachment att,
                                 java.io.File source)
                          throws java.io.IOException,
                                 ProviderException

Stores an attachment that lives in the given file. If the attachment did not exist previously, this method will create it. If it did exist, it stores a new version.

Parameters:
  `att` - Attachment to store this under.
  `source` - A file to read from.
Throws:
  `java.io.IOException` - If writing the attachment failed.
  `ProviderException` - If something else went wrong.

#### storeAttachment

    void storeAttachment​(Attachment att,
                         java.io.InputStream in)
                  throws java.io.IOException,
                         ProviderException

Stores an attachment directly from a stream. If the attachment did not exist previously, this method will create it. If it did exist, it stores a new version.

Parameters:
  `att` - Attachment to store this under.
  `in` - InputStream from which the attachment contents will be read.
Throws:
  `java.io.IOException` - If writing the attachment failed.
  `ProviderException` - If something else went wrong.

#### getVersionHistory

    java.util.List<Attachment> getVersionHistory​(java.lang.String attachmentName)
                                          throws ProviderException

Returns a list of versions of the attachment.

Parameters:
  `attachmentName` - A fully qualified name of the attachment.
Returns:
  A list of Attachments. May return null, if attachments are disabled.
Throws:
  `ProviderException` - If the provider fails for some reason.

#### getAllAttachments

    java.util.Collection<Attachment> getAllAttachments()
                                                throws ProviderException

Returns a collection of Attachments, containing each and every attachment that is in this Wiki.

Returns:
  A collection of attachments. If attachments are disabled, will return an empty collection.
Throws:
  `ProviderException` - If something went wrong with the backend

#### getCurrentProvider

    AttachmentProvider getCurrentProvider()

Returns the current attachment provider.

Returns:
  The current provider. May be null, if attachments are disabled.

#### deleteVersion

    void deleteVersion​(Attachment att)
                throws ProviderException

Deletes the given attachment version.

Parameters:
  `att` - The attachment to delete
Throws:
  `ProviderException` - If something goes wrong with the backend.

#### deleteAttachment

    void deleteAttachment​(Attachment att)
                   throws ProviderException

Deletes all versions of the given attachment.

Parameters:
  `att` - The Attachment to delete.
Throws:
  `ProviderException` - if something goes wrong with the backend.

#### validateFileName

    static java.lang.String validateFileName​(java.lang.String filename)
                                      throws WikiException

Validates the filename and makes sure it is legal. It trims and splits and replaces bad characters.

Parameters:
  `filename` - file name to validate.
Returns:
  A validated name with annoying characters replaced.
Throws:
  `WikiException` - If the filename is not legal (e.g. empty)