@PublicApi public interface

AttachmentManager

com.atlassian.jira.issue.AttachmentManager
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

Manages all attachment related tasks in JIRA, which involves retrieving an attachment, creating an attachment and deleting an attachment.

Summary

Constants
String THUMBS_SUBDIR The name of the issue-specific sub-directory in which its attachment thumbnails are stored.
Public Methods
boolean attachmentsEnabled()
Determine if attachments have been enabled in JIRA and if the attachments directory exists.
Either<AttachmentError, ChangeItemBean> convertTemporaryAttachment(ConvertTemporaryAttachmentParams params)
Converts temporary attachment into real attachment.
@Deprecated List<ChangeItemBean> convertTemporaryAttachments(ApplicationUser user, Issue issue, List<Long> selectedAttachments, TemporaryAttachmentsMonitor temporaryAttachmentsMonitor)
This method is deprecated. Use convertTemporaryAttachments(com.atlassian.jira.user.ApplicationUser, Issue, java.util.List, com.atlassian.jira.web.action.issue.TemporaryAttachmentsMonitor) instead. Since v6.0.
Either<AttachmentError, Attachment> copyAttachment(Attachment attachment, ApplicationUser author, String newIssueKey)
Copy an attachment to another issue.
Map<Long, Either<AttachmentError, Attachment>> copyAttachments(Issue issue, ApplicationUser author, String newIssueKey)
Copy Issue attachments to another issue.
Attachment createAttachment(GenericValue issue, ApplicationUser author, String mimetype, String filename, Long filesize, Map<String, Object> attachmentProperties, Date createdTime)
This method is deprecated. Use #createAttachment(File, String, String, User, Issue, Map, Date) instead. Since v5.0.
ChangeItemBean createAttachment(File file, String filename, String contentType, ApplicationUser author, GenericValue issue, Map<String, Object> attachmentProperties, Date createdTime)
This method is deprecated. Use #createAttachment(File, String, String, User, Issue, Map, Date) instead. Since v5.0.
ChangeItemBean createAttachment(File file, String filename, String contentType, ApplicationUser author, GenericValue issue, Boolean zip, Boolean thumbnailable, Map<String, Object> attachmentProperties, Date createdTime)
This method is deprecated. Use #createAttachment(File, String, String, User, Issue, Map, Date) instead. Since v5.0.
ChangeItemBean createAttachment(CreateAttachmentParamsBean createAttachmentParamsBean)
Create an attachment both on disk, and in the database.
ChangeItemBean createAttachment(File file, String filename, String contentType, ApplicationUser author, Issue issue, Map<String, Object> attachmentProperties, Date createdTime)
This method is deprecated. Use createAttachment(com.atlassian.jira.issue.attachment.CreateAttachmentParamsBean) instead. Since v6.0.
ChangeItemBean createAttachment(File file, String filename, String contentType, ApplicationUser author, Issue issue, Boolean zip, Boolean thumbnailable, Map<String, Object> attachmentProperties, Date createdTime)
This method is deprecated. Use createAttachment(com.atlassian.jira.issue.attachment.CreateAttachmentParamsBean) instead. Since v6.0.
ChangeItemBean createAttachment(File file, String filename, String contentType, ApplicationUser author, Issue issue)
This method is deprecated. Use createAttachment(com.atlassian.jira.issue.attachment.CreateAttachmentParamsBean) instead. Since v6.0.
ChangeItemBean createAttachment(File file, String filename, String contentType, ApplicationUser author, GenericValue issue)
This method is deprecated. Use #createAttachment(File, String, String, User, Issue) instead. Since v5.0.
Attachment createAttachmentCopySourceFile(File file, String filename, String contentType, String attachmentAuthor, Issue issue, Map<String, Object> attachmentProperties, Date createdTime)
This method is deprecated. Use createAttachment(com.atlassian.jira.issue.attachment.CreateAttachmentParamsBean) instead. Since v6.0.
TemporaryAttachmentId createTemporaryAttachment(InputStream stream, long size)
Creates new temporary attachment which may be later converted into real attachment.
void deleteAttachment(Attachment attachment)
Delete an attachment from the database and from the attachment store.
@Internal void deleteAttachmentDirectory(Issue issue)
This method is deprecated. This will no longer be exposed by AttachmentManager.
void deleteTemporaryAttachment(TemporaryAttachmentId temporaryAttachmentId)
Removes temporary attachment with given id
Attachment getAttachment(Long id)
Get a single attachment by its ID.
List<Attachment> getAttachments(Issue issue, Comparator<? super Attachment> comparator)
Get a list of all attachments for a certain issue, sorted according to the specified comparator.
List<Attachment> getAttachments(Issue issue)
Get a list of all attachments for a certain issue.
boolean isScreenshotAppletEnabled()
Determine if screenshot applet has been enabled in JIRA.
boolean isScreenshotAppletSupportedByOS()
Determine if the screenshot applet is supported by the user's operating system.
void moveAttachments(Issue oldIssue, String newIssueKey)
Move Issue attachments to a new directory.
Attachment setThumbnailable(Attachment attachment, boolean thumbnailable)
Stores the thumbnailble flag for this attachment
Attachment setZip(Attachment attachment, boolean zip)
Stores the zip flag for this attachment
<T> T streamAttachmentContent(Attachment attachment, InputStreamConsumer<T> consumer)
Get binary content of the attachment
@Deprecated AttachmentsBulkOperationResult<ChangeItemBean> tryConvertTemporaryAttachments(ApplicationUser user, Issue issue, List<Long> selectedAttachments, TemporaryAttachmentsMonitor temporaryAttachmentsMonitor)
This method is deprecated. Use convertTemporaryAttachments(ApplicationUser, Issue, List) instead. Since v6.4.
Either<AttachmentError, ChangeItemBean> tryCreateAttachment(CreateAttachmentParamsBean params)
Create an attachment.

Constants

public static final String THUMBS_SUBDIR

The name of the issue-specific sub-directory in which its attachment thumbnails are stored.

Constant Value: "thumbs"

Public Methods

public boolean attachmentsEnabled ()

Determine if attachments have been enabled in JIRA and if the attachments directory exists.

Returns
  • true if enabled, false otherwise

public Either<AttachmentError, ChangeItemBean> convertTemporaryAttachment (ConvertTemporaryAttachmentParams params)

Converts temporary attachment into real attachment.

Parameters
params Parameters describing
Returns
  • Attachment error if conversion failed or a ChangeItemBean with all the changes to the issue.

@Deprecated public List<ChangeItemBean> convertTemporaryAttachments (ApplicationUser user, Issue issue, List<Long> selectedAttachments, TemporaryAttachmentsMonitor temporaryAttachmentsMonitor)

This method is deprecated.
Use convertTemporaryAttachments(com.atlassian.jira.user.ApplicationUser, Issue, java.util.List, com.atlassian.jira.web.action.issue.TemporaryAttachmentsMonitor) instead. Since v6.0.

Converts a set of provided temporary attachments to real attachments attached to an issue. This method will also clean up any temporary attachments still linked to the issue via the TemporaryAttachmentsMonitor.

Parameters
user The user performing the action
issue The issue attachments should be linked to
selectedAttachments The temporary attachment ids to convert as selected by the user
temporaryAttachmentsMonitor TemporaryAttachmentsMonitor containing information about all temporary attachments
Returns
  • A list of ChangeItemBeans for any attachments that got created
Throws
AttachmentException If there were problems with the Attachment itself

public Either<AttachmentError, Attachment> copyAttachment (Attachment attachment, ApplicationUser author, String newIssueKey)

Copy an attachment to another issue.

Parameters
attachment the attachment to copy to a new issue
author the user that will own the new attachment
newIssueKey the key of the issue that the attachment will be copied to
Returns
  • either the new attachment or an error

public Map<Long, Either<AttachmentError, Attachment>> copyAttachments (Issue issue, ApplicationUser author, String newIssueKey)

Copy Issue attachments to another issue.

Parameters
issue the issue attachments will be copied from
author the user that will own the new attachments
newIssueKey the key of the issue that the attachment will be copied to
Returns
  • a map that contains the result of the operation for each attachment of the original issue. The key for each entry is the id of an attachment that belongs to the original issue, and the value is either the related new attachment that belongs to the new issue, or an AttachmentError that explains why that attachment couldn't be copied.

public Attachment createAttachment (GenericValue issue, ApplicationUser author, String mimetype, String filename, Long filesize, Map<String, Object> attachmentProperties, Date createdTime)

This method is deprecated.
Use #createAttachment(File, String, String, User, Issue, Map, Date) instead. Since v5.0.

Create an attachment in the database. Note that this does not create it on disk, nor does it create a change item.

Parameters
issue the issue that this attachment is attached to
author The user who created this attachment
mimetype mimetype
filename The desired filename for this attachment.
filesize filesize
attachmentProperties Attachment properties (a Map of String -> Object properties).
createdTime when the attachment was created
Returns
  • the Attachment

public ChangeItemBean createAttachment (File file, String filename, String contentType, ApplicationUser author, GenericValue issue, Map<String, Object> attachmentProperties, Date createdTime)

This method is deprecated.
Use #createAttachment(File, String, String, User, Issue, Map, Date) instead. Since v5.0.

Create an attachment both on disk, and in the database.

Parameters
file A file on a locally accessible filesystem
filename The desired filename for this attachment. This may be different to the filename on disk (for example with temp files used in file uploads)
contentType The desired contentType. Implementations of this interface can choose to override this value as appropriate
author The user who created this attachment
issue The issue that this attachment is attached to
attachmentProperties Attachment properties (a Map of String -> Object properties). These are optional, and are used to populate a PropertySet on the Attachment (getProperties(). Pass null to set no properties
createdTime the created time
Returns
Throws
AttachmentException if an error occurs while attempting to copy the file

public ChangeItemBean createAttachment (File file, String filename, String contentType, ApplicationUser author, GenericValue issue, Boolean zip, Boolean thumbnailable, Map<String, Object> attachmentProperties, Date createdTime)

This method is deprecated.
Use #createAttachment(File, String, String, User, Issue, Map, Date) instead. Since v5.0.

Create an attachment both on disk, and in the database.

Parameters
file A file on a locally accessible filesystem
filename The desired filename for this attachment. This may be different to the filename on disk (for example with temp files used in file uploads)
contentType The desired contentType. Implementations of this interface can choose to override this value as appropriate
author The user who created this attachment
issue The issue that this attachment is attached to
zip This file is a zip file. Null indicates that it is not know if this attachment is a zip file or not
thumbnailable This file is thumbnailable (e.g. a png image). Null indicates that it is not know if this attachment is thumbnailable or not
attachmentProperties Attachment properties (a Map of String -> Object properties). These are optional, and are used to populate a PropertySet on the Attachment (getProperties(). Pass null to set no properties
createdTime the created time
Returns
Throws
AttachmentException if an error occurs while attempting to copy the file

public ChangeItemBean createAttachment (CreateAttachmentParamsBean createAttachmentParamsBean)

Create an attachment both on disk, and in the database.

Parameters
createAttachmentParamsBean Parameters which describe created attachment
Returns
Throws
AttachmentException if an IO error occurs while attempting to copy the file
See Also

public ChangeItemBean createAttachment (File file, String filename, String contentType, ApplicationUser author, Issue issue, Map<String, Object> attachmentProperties, Date createdTime)

This method is deprecated.
Use createAttachment(com.atlassian.jira.issue.attachment.CreateAttachmentParamsBean) instead. Since v6.0.

Create an attachment both on disk, and in the database.

Parameters
file A file on a locally accessible filesystem
filename The desired filename for this attachment. This may be different to the filename on disk (for example with temp files used in file uploads)
contentType The desired contentType. Implementations of this interface can choose to override this value as appropriate
author The user who created this attachment
issue The issue that this file is to be attached to
attachmentProperties Attachment properties (a Map of String -> Object properties). These are optional, and are used to populate a PropertySet on the Attachment (getProperties(). Pass null to set no properties
createdTime the created time
Returns
Throws
AttachmentException if an IO error occurs while attempting to copy the file
See Also
  • #createAttachment(java.io.File, String, String, com.atlassian.crowd.embedded.api.User, Issue)

public ChangeItemBean createAttachment (File file, String filename, String contentType, ApplicationUser author, Issue issue, Boolean zip, Boolean thumbnailable, Map<String, Object> attachmentProperties, Date createdTime)

This method is deprecated.
Use createAttachment(com.atlassian.jira.issue.attachment.CreateAttachmentParamsBean) instead. Since v6.0.

Create an attachment both on disk, and in the database.

Parameters
file A file on a locally accessible filesystem
filename The desired filename for this attachment. This may be different to the filename on disk (for example with temp files used in file uploads)
contentType The desired contentType. Implementations of this interface can choose to override this value as appropriate
author The user who created this attachment
issue The issue that this file is to be attached to
zip This file is a zip file. Null indicates that it is not know if this attachment is a zip file or not
thumbnailable This file is thumbnailable (e.g. a png image). Null indicates that it is not know if this attachment is thumbnailable or not
attachmentProperties Attachment properties (a Map of String -> Object properties). These are optional, and are used to populate a PropertySet on the Attachment (getProperties(). Pass null to set no properties
createdTime the created time
Returns
Throws
AttachmentException if an IO error occurs while attempting to copy the file
See Also
  • #createAttachment(java.io.File, String, String, com.atlassian.crowd.embedded.api.User, Issue)

public ChangeItemBean createAttachment (File file, String filename, String contentType, ApplicationUser author, Issue issue)

This method is deprecated.
Use createAttachment(com.atlassian.jira.issue.attachment.CreateAttachmentParamsBean) instead. Since v6.0.

Same as the #createAttachment(File, String, String, User, Issue, Map, Date) method, except it submits no attachmentProperties and uses now() for the created time.

Parameters
file A file on a locally accessible filesystem
filename The desired filename for this attachment. This may be different to the filename on disk (for example with temp files used in file uploads)
contentType The desired contentType. Implementations of this interface can choose to override this value as appropriate
author The user who created this attachment
issue The issue that this attachment is attached to
Returns
Throws
AttachmentException if an IO error occurs while attempting to copy the file
See Also
  • #createAttachment(java.io.File, String, String, com.atlassian.crowd.embedded.api.User, Issue, java.util.Map, java.util.Date)

public ChangeItemBean createAttachment (File file, String filename, String contentType, ApplicationUser author, GenericValue issue)

This method is deprecated.
Use #createAttachment(File, String, String, User, Issue) instead. Since v5.0.

Same as the #createAttachment(java.io.File, String, String, User, org.ofbiz.core.entity.GenericValue, java.util.Map, java.util.Date) method, except it submits no attachmentProperties and uses now() for the created time.

Parameters
file A file on a locally accessible filesystem
filename The desired filename for this attachment. This may be different to the filename on disk (for example with temp files used in file uploads)
contentType The desired contentType. Implementations of this interface can choose to override this value as appropriate
author The user who created this attachment
issue The issue that this attachment is attached to
Returns
Throws
AttachmentException if an error occurs while attempting to copy the file

public Attachment createAttachmentCopySourceFile (File file, String filename, String contentType, String attachmentAuthor, Issue issue, Map<String, Object> attachmentProperties, Date createdTime)

This method is deprecated.
Use createAttachment(com.atlassian.jira.issue.attachment.CreateAttachmentParamsBean) instead. Since v6.0.

Create an attachment both on disk, and in the database by copying the provided file instead of moving it.

Parameters
file A file on a locally accessible filesystem, this will be copied, not moved.
filename The desired filename for this attachment. This may be different to the filename on disk (for example with temp files used in file uploads)
contentType The desired contentType. Implementations of this interface can choose to override this value as appropriate
attachmentAuthor The username of the user who created this attachment, this is not validated so it must be a valid username
issue The id of the issue that this attachment is attached to
attachmentProperties Attachment properties (a Map of String -> Object properties). These are optional, and are used to populate a PropertySet on the Attachment (getProperties(). Pass null to set no properties
createdTime when the attachment was created
Returns
  • the Attachment
Throws
AttachmentException if any errors occur.

public TemporaryAttachmentId createTemporaryAttachment (InputStream stream, long size)

Creates new temporary attachment which may be later converted into real attachment.

Parameters
stream Stream with temporary attachment content
size Size of temporary attachment
Returns
  • TemporaryAttachmentId which identifies created attachment

public void deleteAttachment (Attachment attachment)

Delete an attachment from the database and from the attachment store.

Parameters
attachment the Attachment
Throws
RemoveException if the attachment cannot be removed from the attachment store

@Internal public void deleteAttachmentDirectory (Issue issue)

@Internal

This method is an internal implementation detail and will change without notice.

Clients that depend on @Internal classes and interfaces can not expect to be compatible with any version other than the version they were compiled against (even minor version and milestone releases may break binary compatibility with respect to @Internal elements).

This method is deprecated.
This will no longer be exposed by AttachmentManager.

Delete the attachment directory from disk if the directory is empty.

Parameters
issue the issue whose attachment directory we wish to delete.
Throws
RemoveException if the directory can not be removed or is not empty.

public void deleteTemporaryAttachment (TemporaryAttachmentId temporaryAttachmentId)

Removes temporary attachment with given id

Parameters
temporaryAttachmentId id of temporary attachment

public Attachment getAttachment (Long id)

Get a single attachment by its ID.

Parameters
id the Attachment ID
Returns
  • the Attachment can never be null as an exception is thrown if an attachment with the passed id does not exist.
Throws
DataAccessException if there is a problem accessing the database.
AttachmentNotFoundException thrown if an attachment with the passed id does not exist.

public List<Attachment> getAttachments (Issue issue, Comparator<? super Attachment> comparator)

Get a list of all attachments for a certain issue, sorted according to the specified comparator.

Parameters
issue the Issue
comparator used for sorting
Returns
Throws
DataAccessException if there is a problem accessing the database.

public List<Attachment> getAttachments (Issue issue)

Get a list of all attachments for a certain issue.

Parameters
issue the Issue
Returns
Throws
DataAccessException if there is a problem accessing the database.

public boolean isScreenshotAppletEnabled ()

Determine if screenshot applet has been enabled in JIRA.

Returns
  • true if enabled, false otherwise

public boolean isScreenshotAppletSupportedByOS ()

Determine if the screenshot applet is supported by the user's operating system.

Note. This always returns true now as we support screenshots on all our supported platforms

Returns
  • true if applet is supported by the user's OS, false otherwise

public void moveAttachments (Issue oldIssue, String newIssueKey)

Move Issue attachments to a new directory. This method is intended for Move/Bulk Move only.

Parameters
oldIssue the issue attachments will be moved from
newIssueKey the new issue key

public Attachment setThumbnailable (Attachment attachment, boolean thumbnailable)

Stores the thumbnailble flag for this attachment

Parameters
attachment The attachment
thumbnailable True if this attachment is thumnailable

public Attachment setZip (Attachment attachment, boolean zip)

Stores the zip flag for this attachment

Parameters
attachment The attachment
zip True if this attachment is a zip file

public T streamAttachmentContent (Attachment attachment, InputStreamConsumer<T> consumer)

Get binary content of the attachment

Parameters
attachment the attachment whose content to stream (required)
consumer the consumer of the stream (required)
Throws
NoAttachmentDataException if the attachment's contents cannot be found.
AttachmentReadException if a problem occurs when the consumer processes the attachment's contents.
IOException here for compatibility, but won't actually be thrown

@Deprecated public AttachmentsBulkOperationResult<ChangeItemBean> tryConvertTemporaryAttachments (ApplicationUser user, Issue issue, List<Long> selectedAttachments, TemporaryAttachmentsMonitor temporaryAttachmentsMonitor)

This method is deprecated.
Use convertTemporaryAttachments(ApplicationUser, Issue, List) instead. Since v6.4.

Converts a set of provided temporary attachments to real attachments attached to an issue. This method will also clean up any temporary attachments still linked to the issue via the TemporaryAttachmentsMonitor.

Parameters
user The user performing the action
issue The issue attachments should be linked to
selectedAttachments The temporary attachment ids to convert as selected by the user
temporaryAttachmentsMonitor TemporaryAttachmentsMonitor containing information about all temporary attachments
Returns
  • Object with ChangeItemBeans and optionally Errors if there were problems during attachment conversion

public Either<AttachmentError, ChangeItemBean> tryCreateAttachment (CreateAttachmentParamsBean params)

Create an attachment.

Parameters
params Parameters which describe created attachment
Returns
  • Either a ChangeItemBean with all the changes to the issue or the AttachmentError in case of any errors while attempting to create attachment.
See Also