public interface MessageBatchAdminSession extends MessageAdminSession
This session creates, updates, and deletes Messages
in
bulk. The data for create and update is provided by the consumer via the
form object. OsidForms
are requested for each create or
update and may not be reused.
Create and update operations differ in their usage. To create a
Message,
a MessageForm
is requested using
getMessageFormsForCreate()
specifying the desired record
Types
or none if no record Types
are needed. Each
of the returned MessageForms
will indicate that it is to be
used with a create operation and can be used to examine metdata or
validate data prior to creation. Once a MessageForm
is
submiited to a create operation, it cannot be reused with another create
operation unless the first operation was unsuccessful. Each
MessageForm
corresponds to an attempted transaction.
The MessageForms
returned from
getMessageFormsForCreate()
may be linked to the originating
request through the peer Ids
of the MessageForm.
In the case where there may be duplicates, any MessageForm
of the same peer Ids
may be used for a create
operation.
Once a batch of MessageForms
are submitted for create,
a CreateResponse
is returned for each MessageForm,
although the ordering is not defined. Only errors that pertain to
the entire create operation are returned from createMessages(),
errors specific to an individual MessageForm
are
indicated in the corresponding CreateResponse.
CreateResponses
may be linked to the originating
MessageForm
through the MessageForm
Id
.
For updates, MessageForms
are requested to the
Message
Id
that is to be updated using
getMessageFormsForUpdate()
where the reference Id
in the MessageForm
may be used to link the request.
Similarly, the MessageForm
has metadata about the data that
can be updated and it can perform validation before submitting the update.
The MessageForm
can only be used once for a successful
update and cannot be reused.
Once a batch of MessageForms
are submitted for update,
an UpdateResponse
is returned for each MessageForm,
although the ordering is not defined. Only errors that pertain to
the entire update operation are returned from updateMessages(),
errors specific to an individual MessageForm
are
indicated in the corresponding UpdateResponse.
UpdateResponses
may be linked to the originating
MessageForm
through the MessageForm
Id.
The delete operations delete Messages
in bulk. To unmap
a Message
from the current Mailbox,
the
MessageMailboxAssignmentSession
should be used. These
delete operations attempt to remove the Message
itself thus
removing it from all known Mailbox
catalogs. Bulk delete
operations return the results in DeleteResponses.
Modifier and Type | Method and Description |
---|---|
AliasResponseList |
aliasMessages(AliasRequestList aliasRequests)
Adds an
Id to a Message for the purpose
of creating compatibility. |
CreateResponseList |
createMessages(MessageBatchFormList messageForms)
Creates a new set of
Messages. |
DeleteResponseList |
deleteAllMessages()
Deletes all
Messages in this Mailbox . |
DeleteResponseList |
deleteMessagesByDate(DateTime from,
DateTime to)
Deletes messages received between the given date range inclusive.
|
DeleteResponseList |
deleteMessagesBySender(Id resourceId)
Deletes messages for the given sender resource.
|
MessageBatchFormList |
getMessageFormsForCreate(long number,
Type[] messageRecordTypes)
Gets the message forms for creating a bunch of new messages.
|
MessageBatchFormList |
getMessageFormsForUpdate(IdList messageIds)
Gets the message forms for updating an existing set of messages.
|
UpdateResponseList |
updateMessages(MessageBatchFormList messageForms)
Updates existing messages.
|
aliasMessage, canCreateMessages, canCreateMessageWithRecordTypes, canDeleteMessages, canManageMessageAliases, canUpdateMessages, createMessage, deleteMessage, getMailbox, getMailboxId, getMessageFormForCreate, getMessageFormForUpdate, updateMessage
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
MessageBatchFormList getMessageFormsForCreate(long number, Type[] messageRecordTypes) throws OperationFailedException, PermissionDeniedException
number
- the number of forms to retrievemessageRecordTypes
- array of message record types to be
included in each create operation or an empty list if noneNullArgumentException
- messageRecordTypes
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- unable to request forms with
given record typesmandatory
- This method must be implemented. CreateResponseList createMessages(MessageBatchFormList messageForms) throws OperationFailedException, PermissionDeniedException
Messages.
This method returns an
error if the entire operation fails. Otherwise, the status of an
individual create operation is indicated in the
BatchCreateResponse
.messageForms
- the message formsNullArgumentException
- messageForms
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. MessageBatchFormList getMessageFormsForUpdate(IdList messageIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
messageIds
- the Ids
of the Message
NotFoundException
- a messageId
is not
foundNullArgumentException
- messageIds
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. UpdateResponseList updateMessages(MessageBatchFormList messageForms) throws OperationFailedException, PermissionDeniedException
BatchCreateResponse
.messageForms
- the form containing the elements to be updatedNullArgumentException
- messageForms
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. DeleteResponseList deleteAllMessages() throws OperationFailedException, PermissionDeniedException
Messages
in this Mailbox
.OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. DeleteResponseList deleteMessagesBySender(Id resourceId) throws OperationFailedException, PermissionDeniedException
resourceId
- the Id
of a resourceNullArgumentException
- resourceId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. DeleteResponseList deleteMessagesByDate(DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
from
- start of date rangeto
- end of date rangeInvalidArgumentException
- from
is
greater than to
NullArgumentException
- from
or
to
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. AliasResponseList aliasMessages(AliasRequestList aliasRequests) throws OperationFailedException, PermissionDeniedException
Id
to a Message
for the purpose
of creating compatibility. The primary Id
of the
Message
is determined by the provider. The new Id
is an alias to the primary Id.
If the alias is
a pointer to another message, it is reassigned to the given message
Id.
aliasRequests
- the alias requestsNullArgumentException
- aliasRequests
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.