com.stiltsoft.jira.attachcategory.facade

Interface SmartAttachmentsFacade

public interface SmartAttachmentsFacade

Smart Attachments Public API

Method Summary

Modifier and Type	Method and Description
void	addAttachmentsToCategory(com.atlassian.jira.issue.Issue issue, int categoryId, java.util.List<com.atlassian.jira.issue.attachment.Attachment> attachments, com.atlassian.jira.user.ApplicationUser user) Places attachments within the category.
void	addDocumentRevision(com.atlassian.jira.issue.Issue issue, int documentId, com.atlassian.jira.issue.attachment.Attachment attachment, com.atlassian.jira.user.ApplicationUser user) Adds a new revision to the document.
void	addTempAttachmentsToCategory(com.atlassian.jira.issue.Issue issue, int categoryId, java.util.List<TempAttachment> tempAttachments) Adds names of temporary attachments to the category prior to their actual upload.
com.atlassian.jira.issue.attachment.Attachment	archiveAttachments(com.atlassian.jira.issue.Issue issue, int categoryId, java.lang.String archiveName, java.util.List<com.atlassian.jira.issue.attachment.Attachment> attachments, java.util.List<java.lang.Integer> documentIds, com.atlassian.jira.user.ApplicationUser user) Creates a ZIP archive with attachments.
Scheme	copyScheme(int schemeId, java.lang.String name, com.atlassian.jira.user.ApplicationUser user) Creates a copy of the category scheme.
Document	createDocument(com.atlassian.jira.issue.Issue issue, int categoryId, java.lang.String name, java.util.List<com.atlassian.jira.issue.attachment.Attachment> attachments, com.atlassian.jira.user.ApplicationUser user) Creates a new document from attachments.
Scheme	createScheme(java.lang.String name, com.atlassian.jira.user.ApplicationUser user) Creates a new category scheme.
void	deleteDocument(int documentId) Converts the document (with revisions) to generic attachments.
boolean	deleteScheme(Scheme scheme) Deletes the scheme.
CategoryConfig	generateNewConfigCategory(java.lang.String name) Generates a new category.
TempAttachment	generateTempAttachment(com.atlassian.jira.user.ApplicationUser user, java.lang.String attachmentName) Creates an object which corresponds to the temporary attachment.
AttachmentCategories	getAttachmentCategories(com.atlassian.jira.issue.Issue issue) Returns the list of categories and attachments stored in them for a specific issue.
java.util.List<CommentThread>	getCommentThreadsForAttachment(com.atlassian.jira.issue.attachment.Attachment attachment) Deprecated. since 2.15.2. We removed the attachments commenting feature in January 2024 and all the code associated with this feature. In this regard, the method returns an empty array. At the moment, the list of past comments can only be obtained by direct query to the database.
java.util.Optional<Scheme>	getSchemeByName(java.lang.String name) Returns a scheme by name.
java.util.Optional<Scheme>	getSchemeByProject(com.atlassian.jira.project.Project project) Returns the scheme for a specific project.
java.util.List<Scheme>	getSchemes() Returns the collection with all schemes.
void	removeRevisionsFromDocuments(java.util.List<com.atlassian.jira.issue.attachment.Attachment> attachments) Deletes the mappings of attachments to documents.
void	removeTempAttachmentsForUser(com.atlassian.jira.issue.Issue issue, com.atlassian.jira.user.ApplicationUser user, int categoryId) Deletes temporary attachments.
com.atlassian.jira.issue.attachment.Attachment	renameAttachment(com.atlassian.jira.issue.attachment.Attachment attachment, java.lang.String newName, com.atlassian.jira.user.ApplicationUser user) Renames the attachment.
Document	renameDocument(com.atlassian.jira.issue.Issue issue, int documentId, java.lang.String newName) Renames the document.
Scheme	updateScheme(Scheme scheme, com.atlassian.jira.user.ApplicationUser user) Updates the category scheme.

Method Detail

getSchemes

java.util.List<Scheme> getSchemes()

Returns the collection with all schemes.

Returns:

collection of Scheme.

Since:

2.1.0

getSchemeByName

java.util.Optional<Scheme> getSchemeByName(java.lang.String name)

Returns a scheme by name.

Returns the found scheme which is wrapped with Optional.

Parameters:

name - the scheme name

Returns:

a Scheme wrapped with Optional

Throws:

SmartAttachmentsException - if the name provided is null or empty

Since:

2.1.0

getSchemeByProject

java.util.Optional<Scheme> getSchemeByProject(com.atlassian.jira.project.Project project)
                                       throws SmartAttachmentsException

Returns the scheme for a specific project.

Returns the project-specific category scheme wrapped with Optional.

Parameters:

project - Project

Returns:

a Scheme wrapped with Optional

Throws:

SmartAttachmentsException - if the project provided is null

Since:

2.1.0

deleteScheme

boolean deleteScheme(Scheme scheme)
              throws SmartAttachmentsException

Deletes the scheme.

Deletes the category scheme if it is not associated with any project. If the category scheme has been already deleted, the method returns true.

Parameters:

scheme - Scheme

Returns:

true if the category scheme was deleted

Throws:

SmartAttachmentsException - if the scheme provided is null

Since:

2.1.0

See Also:

updateScheme(Scheme, ApplicationUser)

createScheme

Scheme createScheme(java.lang.String name,
                    com.atlassian.jira.user.ApplicationUser user)
             throws SmartAttachmentsException

Creates a new category scheme.

Creates a new category scheme with the specified name. The scheme contains the default Uncategorized category. If the category scheme with such name already exists, the method will return the existing category scheme.

Parameters:

name - the scheme name

user - ApplicationUser

Returns:

Scheme

Throws:

SmartAttachmentsException - if the category scheme is null or empty or if the user is null

Since:

2.1.0

updateScheme

Scheme updateScheme(Scheme scheme,
                    com.atlassian.jira.user.ApplicationUser user)
             throws SmartAttachmentsException

Updates the category scheme.

The Scheme entity includes setters that allow you to modify configuration of the category scheme. This method is use to save the modifications in the category scheme. If the scheme is being edited by someone the method throws SmartAttachmentsException

Parameters:

scheme - the for updating

user - ApplicationUser who updating the scheme

Returns:

the Scheme with stored fields

Throws:

SmartAttachmentsException - if parameters are empty or null, the scheme is locked

Since:

2.1.0

copyScheme

Scheme copyScheme(int schemeId,
                  java.lang.String name,
                  com.atlassian.jira.user.ApplicationUser user)
           throws SmartAttachmentsException

Creates a copy of the category scheme.

Copies all settings of the specified category scheme. If the scheme is locked (being edited) by someone the method throws SmartAttachmentsException

Parameters:

schemeId - ID of the source category scheme

name - name for the category scheme copy

user - ApplicationUser who copies the scheme

Returns:

Scheme

Throws:

SmartAttachmentsException - if the category scheme name is empty or null, user is null or scheme is locked

Since:

2.1.0

generateNewConfigCategory

CategoryConfig generateNewConfigCategory(java.lang.String name)

Generates a new category.

Creates a new category with the specified name. The category exists only in memory (RAM). To save it in the category scheme, you need to put it withing the Scheme object Scheme and run updateScheme(Scheme, ApplicationUser). The CategoryConfig fields include the default values.

Parameters:

name - the category name

Returns:

CategoryConfig

Since:

2.1.0

getAttachmentCategories

AttachmentCategories getAttachmentCategories(com.atlassian.jira.issue.Issue issue)
                                      throws SmartAttachmentsException

Returns the list of categories and attachments stored in them for a specific issue.

Returns the object which includes the collection of the AttachmentCategory elements.

Parameters:

issue - Jira Issue

Returns:

AttachmentCategories

Throws:

SmartAttachmentsException - if issue is null

Since:

2.1.0

See Also:

AttachmentCategory

createDocument

Document createDocument(com.atlassian.jira.issue.Issue issue,
                        int categoryId,
                        java.lang.String name,
                        java.util.List<com.atlassian.jira.issue.attachment.Attachment> attachments,
                        com.atlassian.jira.user.ApplicationUser user)
                 throws SmartAttachmentsException

Creates a new document from attachments.

Creates a new document from the specified attachments within the issue.

Parameters:

issue - Issue

categoryId - ID of category

name - the name of the document

attachments - a collection of Attachment

user - ApplicationUser author of the document

Returns:

Document

Throws:

SmartAttachmentsException - if any of the parameters is null or collection of attachments has less than 2 items

Since:

2.1.0

deleteDocument

void deleteDocument(int documentId)

Converts the document (with revisions) to generic attachments.

This method deletes the mappings of attachments to the document and all the attachments are preserved in the issue as individual files.

Parameters:

documentId - document's ID for deleting

Since:

2.1.0

addDocumentRevision

void addDocumentRevision(com.atlassian.jira.issue.Issue issue,
                         int documentId,
                         com.atlassian.jira.issue.attachment.Attachment attachment,
                         com.atlassian.jira.user.ApplicationUser user)
                  throws SmartAttachmentsException

Adds a new revision to the document.

Creates a new document revision based on the attached file.

Parameters:

issue - Issue

documentId - document's ID

attachment - Attachment

user - ApplicationUser author of the document

Throws:

SmartAttachmentsException - if issue/attachment/user is null or attachment is already used in another document

Since:

2.1.0

removeRevisionsFromDocuments

void removeRevisionsFromDocuments(java.util.List<com.atlassian.jira.issue.attachment.Attachment> attachments)
                           throws SmartAttachmentsException

Deletes the mappings of attachments to documents.

The specified attachments remain in the issue as separate attachments. If the document contains fewer than 2 revisions, it is converted to a generic attachment.

Parameters:

attachments - a collection of Attachment

Throws:

SmartAttachmentsException - if a param 'attachments' is null

Since:

2.1.0

addAttachmentsToCategory

void addAttachmentsToCategory(com.atlassian.jira.issue.Issue issue,
                              int categoryId,
                              java.util.List<com.atlassian.jira.issue.attachment.Attachment> attachments,
                              com.atlassian.jira.user.ApplicationUser user)
                       throws SmartAttachmentsException

Places attachments within the category.

Moves the specified attachments to the specified category. If the category is not found or the list of attachments is empty, the moving will not run.

Parameters:

issue - Issue

categoryId - ID of the category, AttachmentCategory.getId()

attachments - a collection of Attachment

user - ApplicationUser who performs the action

Throws:

SmartAttachmentsException - if any of the parameters is null

Since:

2.1.0

addTempAttachmentsToCategory

void addTempAttachmentsToCategory(com.atlassian.jira.issue.Issue issue,
                                  int categoryId,
                                  java.util.List<TempAttachment> tempAttachments)
                           throws SmartAttachmentsException

Adds names of temporary attachments to the category prior to their actual upload.

Adds temporary attachments to the catgory before their actual upload into the issue. Once attachments appear in the issue, they will be placed to the category according to TempAttachment.

Parameters:

issue - Issue

categoryId - ID of the category, AttachmentCategory.getId()

tempAttachments - TempAttachment

Throws:

SmartAttachmentsException - if any of the parameters is null

Since:

2.1.0

See Also:

generateTempAttachment(ApplicationUser, String)

generateTempAttachment

TempAttachment generateTempAttachment(com.atlassian.jira.user.ApplicationUser user,
                                      java.lang.String attachmentName)
                               throws SmartAttachmentsException

Creates an object which corresponds to the temporary attachment.

It generates the temporary attachments that are used in addTempAttachmentsToCategory(Issue, int, List).

Parameters:

user - ApplicationUser author of the attachment

attachmentName - name of the future attachment

Returns:

TempAttachment

Throws:

SmartAttachmentsException - if any of the parameters is null or attachmentName is empty

Since:

2.1.0

See Also:

addTempAttachmentsToCategory(Issue, int, List)

removeTempAttachmentsForUser

void removeTempAttachmentsForUser(com.atlassian.jira.issue.Issue issue,
                                  com.atlassian.jira.user.ApplicationUser user,
                                  int categoryId)
                           throws SmartAttachmentsException

Deletes temporary attachments.

Deletes TempAttachment that was created by the user in the specified category.

Parameters:

issue - Issue

user - ApplicationUser

categoryId - ID of the category, AttachmentCategory.getId()

Throws:

SmartAttachmentsException - if any of the parameters is null

Since:

2.1.0

See Also:

addTempAttachmentsToCategory(Issue, int, List)

archiveAttachments

com.atlassian.jira.issue.attachment.Attachment archiveAttachments(com.atlassian.jira.issue.Issue issue,
                                                                  int categoryId,
                                                                  java.lang.String archiveName,
                                                                  java.util.List<com.atlassian.jira.issue.attachment.Attachment> attachments,
                                                                  java.util.List<java.lang.Integer> documentIds,
                                                                  com.atlassian.jira.user.ApplicationUser user)
                                                           throws SmartAttachmentsException

Creates a ZIP archive with attachments.

Creates a ZIP archive with the specified attachments and documents.

Parameters:

issue - Issue

categoryId - ID of the category, AttachmentCategory.getId()

archiveName - the name of the new archive

attachments - a collection of Attachment

documentIds - collection of the document IDs, Document.getId()

user - ApplicationUser author

Returns:

Attachment

Throws:

SmartAttachmentsException - if any of the parameters is null or the category doesn't exist

Since:

2.1.0

renameAttachment

com.atlassian.jira.issue.attachment.Attachment renameAttachment(com.atlassian.jira.issue.attachment.Attachment attachment,
                                                                java.lang.String newName,
                                                                com.atlassian.jira.user.ApplicationUser user)
                                                         throws SmartAttachmentsException

Renames the attachment.

Parameters:

attachment - Attachment

newName - a new attachment name

user - ApplicationUser

Returns:

Attachment

Throws:

SmartAttachmentsException - if any of the parameters is null or a newName is blank

Since:

2.1.0

renameDocument

Document renameDocument(com.atlassian.jira.issue.Issue issue,
                        int documentId,
                        java.lang.String newName)
                 throws SmartAttachmentsException

Renames the document.

Parameters:

issue - Issue

documentId - ID of the document

newName - a new document name

Returns:

Document

Throws:

SmartAttachmentsException - if any of the parameters is null or newName is blank

Since:

2.1.0

See Also:

Document.getId()

getCommentThreadsForAttachment

@Deprecated
java.util.List<CommentThread> getCommentThreadsForAttachment(com.atlassian.jira.issue.attachment.Attachment attachment)

Deprecated. since 2.15.2. We removed the attachments commenting feature in January 2024 and all the code associated with this feature. In this regard, the method returns an empty array. At the moment, the list of past comments can only be obtained by direct query to the database.

Returns a collection with all comment threads for the attachment.

Parameters:

attachment - Attachment

Returns:

collection of CommentThread

Throws:

SmartAttachmentsException - if the attachment provided is null

Since:

2.13.4