org.osid.tracking

Interface IssueMessagingSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface IssueMessagingSession
extends OsidSession

This session creates comments on issues and sends messages to customers. A comment is a direct log entry that may not be visible to the customer. A message is sent by some means to the customer and recorded in the log. In both cases, LogEntryForms are used to specify the content of the message or comment with an IssueAction of COMMENTED or MESSAGE_SENT .

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canComment() Tests if this user can comment on Issues.
boolean	canCreateLogEntryCommentWithRecordTypes(Type[] logEntryRecordTypes) Tests if this user can create a single LogEntry using the desired record types.
boolean	canCreateLogEntryMessageWithRecordTypes(Type[] logEntryRecordTypes) Tests if this user can create a single LogEntry using the desired record types.
boolean	canDeleteComment(Id logEntryId) Tests if this user can delete a specified comment.
boolean	canDeleteComments() Tests if this user can delete comments.
boolean	canSendMessages() Tests if this user can send customer messages.
boolean	canUpdateComment(Id logEntryId) Tests if this user can update a specified LogEntry.
boolean	canUpdateComments() Tests if this user can update comments.
LogEntry	comment(Id issueId, LogEntryForm logEntryForm) Comments on an issue.
void	deleteComment(Id logEntryId) Deletes a comment.
void	deleteComments() Deletes all comments in this FrontOffice.
void	deleteCommentsByDate(DateTime from, DateTime to) Deletes all comments within the given date range inclusive in this FrontOffice.
void	deleteCommentsByDateForIssue(Id issueId, DateTime from, DateTime to) Deletes all comments within the given date range inclusive in this Issue.
void	deleteCommentsByDateForQueue(Id queueId, DateTime from, DateTime to) Deletes all comments within the given date range inclusive in this Queue.
void	deleteCommentsForIssue(Id issueId) Deletes all comments in an Issue.
void	deleteCommentsForQueue(Id queueId) Deletes all comments in a Queue.
FrontOffice	getFrontOffice() Gets the FrontOffice associated with this session.
Id	getFrontOfficeId() Gets the FrontOffice Id associated with this session.
LogEntryForm	getLogEntryFormForCommenting(Type[] logEntryRecordTypes) Gets the log entry form for creating commenting on issues.
LogEntryForm	getLogEntryFormForCommentUpdate(Id Id) Gets the log entry form for updating an existing comment.
LogEntryForm	getLogEntryFormForMessaging(Type[] logEntryRecordTypes) Gets the log entry form for creating messages to customers.
LogEntry	sendMessage(Id issueId, LogEntryForm logEntryForm) Send a customer a message and records it in the issue log.
void	updateComment(Id logEntryId, LogEntryForm logEntryForm) Updates an existing log entry.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getFrontOfficeId

Id getFrontOfficeId()

Gets the FrontOffice Id associated with this session.

Returns:

the FrontOffice Id associated with this session

Compliance:

mandatory - This method must be implemented.

getFrontOffice

FrontOffice getFrontOffice()
                           throws OperationFailedException,
                                  PermissionDeniedException

Gets the FrontOffice associated with this session.

Returns:

the front office

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canComment

boolean canComment()

Tests if this user can comment on Issues. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a LogEntry will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer comment operations to an unauthorized user.

Returns:

false if commenting is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateLogEntryCommentWithRecordTypes

boolean canCreateLogEntryCommentWithRecordTypes(Type[] logEntryRecordTypes)

Tests if this user can create a single LogEntry using the desired record types. While TrackingManager.getLogEntryRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific LogEntry. Providing an empty array tests if a LogEntry can be created with no records.

Parameters:

logEntryRecordTypes - array of log entry record types

Returns:

true if LogEntry creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - logEntryRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getLogEntryFormForCommenting

LogEntryForm getLogEntryFormForCommenting(Type[] logEntryRecordTypes)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Gets the log entry form for creating commenting on issues. A new form should be requested for each create transaction.

Parameters:

logEntryRecordTypes - array of log entry record types

Returns:

the log entry form

Throws:

NullArgumentException - logEntryRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

comment

LogEntry comment(Id issueId,
               LogEntryForm logEntryForm)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Comments on an issue.

Parameters:

issueId - the Id of the issue

logEntryForm - the form for this LogEntry

Returns:

the new LogEntry

Throws:

InvalidArgumentException - one or more of the form elements is invalid

NotFoundException - issueId is not found

NullArgumentException - issueId or logEntryForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - logEntryForm is not of this service

Compliance:

mandatory - This method must be implemented.

canUpdateComments

boolean canUpdateComments()

Tests if this user can update comments. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a comment will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer update operations to an unauthorized user.

Returns:

false if comment modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canUpdateComment

boolean canUpdateComment(Id logEntryId)

Tests if this user can update a specified LogEntry. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating the LogEntry will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer an update operation to an unauthorized user for this log entry.

Parameters:

logEntryId - the Id of the comment entry

Returns:

false if log entry modification is not authorized, true otherwise

Throws:

NullArgumentException - logEntryId is null

Compliance:

mandatory - This method must be implemented.

Notes:

If - the logEntryId is not found, then it is acceptable to return false to indicate the lack of an update available.

getLogEntryFormForCommentUpdate

LogEntryForm getLogEntryFormForCommentUpdate(Id Id)
                                             throws NotFoundException,
                                                    OperationFailedException

Gets the log entry form for updating an existing comment. A new log entry form should be requested for each update transaction.

Parameters:

Id - the Id of the LogEntry

Returns:

the log entry form

Throws:

NotFoundException - logEntryId is not found

NullArgumentException - logEntryId is null

OperationFailedException - unable to complete request

Compliance:

mandatory - This method must be implemented.

updateComment

void updateComment(Id logEntryId,
                 LogEntryForm logEntryForm)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Updates an existing log entry.

Parameters:

logEntryId - the Id of the LogEntry

logEntryForm - the form containing the elements to be updated

Throws:

InvalidArgumentException - the form contains an invalid value

NotFoundException - logEntryId is not found or not a comment

NullArgumentException - logEntryId or logEntryForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - logEntryForm is not supported

Compliance:

mandatory - This method must be implemented.

canDeleteComments

boolean canDeleteComments()

Tests if this user can delete comments. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a comment will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer delete operations to an unauthorized user.

Returns:

false if comment deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canDeleteComment

boolean canDeleteComment(Id logEntryId)

Tests if this user can delete a specified comment. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting the comment will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer an delete operation to an unauthorized user for this log entry.

Parameters:

logEntryId - the Id of the comment

Returns:

false if deletion of this LogEntry is not authorized, true otherwise

Throws:

NullArgumentException - logEntryId is null

Compliance:

mandatory - This method must be implemented.

Notes:

If - the logEntryId is not found, then it is acceptable to return false to indicate the lack of an delete available.

deleteComment

void deleteComment(Id logEntryId)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Deletes a comment.

Parameters:

logEntryId - the Id of the comment to remove

Throws:

NotFoundException - logEntryId not found

NullArgumentException - logEntryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteComments

void deleteComments()
                    throws OperationFailedException,
                           PermissionDeniedException

Deletes all comments in this FrontOffice.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteCommentsByDate

void deleteCommentsByDate(DateTime from,
                        DateTime to)
                          throws OperationFailedException,
                                 PermissionDeniedException

Deletes all comments within the given date range inclusive in this FrontOffice.

Parameters:

from - start date

to - end date

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteCommentsForQueue

void deleteCommentsForQueue(Id queueId)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Deletes all comments in a Queue.

Parameters:

queueId - the Id of a Queue

Throws:

NotFoundException - queueId not found

NullArgumentException - queueId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteCommentsByDateForQueue

void deleteCommentsByDateForQueue(Id queueId,
                                DateTime from,
                                DateTime to)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

Deletes all comments within the given date range inclusive in this Queue.

Parameters:

queueId - the Id of a Queue

from - start date

to - end date

Throws:

InvalidArgumentException - from is greater than to

NotFoundException - queueId not found

NullArgumentException - queueId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteCommentsForIssue

void deleteCommentsForIssue(Id issueId)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Deletes all comments in an Issue.

Parameters:

issueId - the Id of an Issue

Throws:

NotFoundException - issueId not found

NullArgumentException - issueId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteCommentsByDateForIssue

void deleteCommentsByDateForIssue(Id issueId,
                                DateTime from,
                                DateTime to)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

Deletes all comments within the given date range inclusive in this Issue.

Parameters:

issueId - the Id of an Issue

from - start date

to - end date

Throws:

InvalidArgumentException - from is greater than to

NotFoundException - issueId not found

NullArgumentException - issueId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canSendMessages

boolean canSendMessages()

Tests if this user can send customer messages. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a LogEntry will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer comment operations to an unauthorized user.

Returns:

false if messaging is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateLogEntryMessageWithRecordTypes

boolean canCreateLogEntryMessageWithRecordTypes(Type[] logEntryRecordTypes)

Tests if this user can create a single LogEntry using the desired record types. While TrackingManager.getLogEntryRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific LogEntry. Providing an empty array tests if a LogEntry can be created with no records.

Parameters:

logEntryRecordTypes - array of log entry record types

Returns:

true if LogEntry creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - logEntryRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getLogEntryFormForMessaging

LogEntryForm getLogEntryFormForMessaging(Type[] logEntryRecordTypes)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Gets the log entry form for creating messages to customers. A new form should be requested for each create transaction.

Parameters:

logEntryRecordTypes - array of log entry record types

Returns:

the log entry form

Throws:

NullArgumentException - logEntryRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

sendMessage

LogEntry sendMessage(Id issueId,
                   LogEntryForm logEntryForm)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Send a customer a message and records it in the issue log.

Parameters:

issueId - the Id of the issue

logEntryForm - the form for this LogEntry

Returns:

the new LogEntry

Throws:

InvalidArgumentException - one or more of the form elements is invalid

NotFoundException - issueId is not found

NullArgumentException - issueId or logEntryForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - logEntryForm is not of this service

Compliance:

mandatory - This method must be implemented.