org.osid.logging.batch

Interface LogEntryBatchAdminSession

All Superinterfaces:

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

public interface LogEntryBatchAdminSession
extends LogEntryAdminSession

This session creates, updates, and deletes LogEntries 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 LogEntry, a LogEntryForm is requested using getLogEntryFormsForCreate() specifying the desired record Types or none if no record Types are needed. Each of the returned LogEntryForms 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 LogEntryForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each LogEntryForm corresponds to an attempted transaction.

The LogEntryForms returned from getLogEntryFormsForCreate() may be linked to the originating request through the peer Ids of the LogEntryForm. In the case where there may be duplicates, any LogEntryForm of the same peer Ids may be used for a create operation.

Once a batch of LogEntryForms are submitted for create, a CreateResponse is returned for each LogEntryForm, although the ordering is not defined. Only errors that pertain to the entire create operation are returned from createLogEntries(), errors specific to an individual LogEntryForm are indicated in the corresponding CreateResponse. CreateResponses may be linked to the originating LogEntryForm through the LogEntryForm Id .

For updates, LogEntryForms are requested to the LogEntry Id that is to be updated using getLogEntryFormsForUpdate() where the reference Id in the LogEntryForm may be used to link the request. Similarly, the LogEntryForm has metadata about the data that can be updated and it can perform validation before submitting the update. The LogEntryForm can only be used once for a successful update and cannot be reused.

Once a batch of LogEntryForms are submitted for update, an UpdateResponse is returned for each LogEntryForm, although the ordering is not defined. Only errors that pertain to the entire update operation are returned from updateLogEntries(), errors specific to an individual LogEntryForm are indicated in the corresponding UpdateResponse. UpdateResponses may be linked to the originating LogEntryForm through the LogEntryForm Id.

The delete operations delete LogEntries in bulk. To unmap a LogEntry from the current Log, the LogEntryLogAssignmentSession should be used. These delete operations attempt to remove the LogEntry itself thus removing it from all known Log catalogs. Bulk delete operations return the results in DeleteResponses.

Method Summary

Methods

Modifier and Type	Method and Description
AliasResponseList	aliasLogEntries(AliasRequestList aliasRequests) Adds an Id to a LogEntry for the purpose of creating compatibility.
CreateResponseList	createLogEntries(LogEntryBatchFormList logEntryForms) Creates a new set of LogEntries.
DeleteResponseList	deleteAllLogEntries() Deletes all LogEntries in this Log .
DeleteResponseList	deleteLogEntries(IdList logEntryIds) Deletes log entries for the given Ids.
DeleteResponseList	deleteLogEntriesByDate(DateTime from, DateTime to) Deletes log entries between the given date range inclusive.
DeleteResponseList	deleteLogEntriesByResource(Id resourceId) Deletes log entries for the given resource.
LogEntryBatchFormList	getLogEntryFormsForCreate(long number, Type[] logEntryRecordTypes) Gets the log entry forms for creating a bunch of new log entries.
LogEntryBatchFormList	getLogEntryFormsForUpdate(IdList logEntryIds) Gets the log entry forms for updating an existing set of log entries.
UpdateResponseList	updateLogEntries(LogEntryBatchFormList logEntryForms) Updates existing log entries.

Methods inherited from interface org.osid.logging.LogEntryAdminSession

aliasLogEntry, canCreateLogEntries, canCreateLogEntryWithRecordTypes, canDeleteLogEntries, canManageLogEntryAliases, canUpdateLogEntries, createLogEntry, deleteLogEntry, getLog, getLogEntryFormForCreate, getLogEntryFormForUpdate, getLogId, updateLogEntry

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

getLogEntryFormsForCreate

LogEntryBatchFormList getLogEntryFormsForCreate(long number,
                                              Type[] logEntryRecordTypes)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

Gets the log entry forms for creating a bunch of new log entries.

Parameters:

number - the number of forms to retrieve

logEntryRecordTypes - array of log entry record types to be included in each create operation or an empty list if none

Returns:

the log entry forms

Throws:

NullArgumentException - logEntryRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to request forms with given record types

Compliance:

mandatory - This method must be implemented.

createLogEntries

CreateResponseList createLogEntries(LogEntryBatchFormList logEntryForms)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Creates a new set of LogEntries. This method returns an error if the entire operation fails. Otherwise, the status of an individual create operation is indicated in the BatchCreateResponse .

Parameters:

logEntryForms - the log entry forms

Returns:

the create responses

Throws:

NullArgumentException - logEntryForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getLogEntryFormsForUpdate

LogEntryBatchFormList getLogEntryFormsForUpdate(IdList logEntryIds)
                                                throws NotFoundException,
                                                       OperationFailedException,
                                                       PermissionDeniedException

Gets the log entry forms for updating an existing set of log entries. A new log entry form should be requested for each update transaction.

Parameters:

logEntryIds - the Ids of the LogEntry

Returns:

the log entry form

Throws:

NotFoundException - a logEntryId is not found

NullArgumentException - logEntryIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateLogEntries

UpdateResponseList updateLogEntries(LogEntryBatchFormList logEntryForms)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Updates existing log entries. This method returns an error if the entire operation fails. Otherwise, the status of an individual update operation is indicated in the BatchCreateResponse .

Parameters:

logEntryForms - the form containing the elements to be updated

Returns:

the update responses

Throws:

NullArgumentException - logEntryForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteAllLogEntries

DeleteResponseList deleteAllLogEntries()
                                       throws OperationFailedException,
                                              PermissionDeniedException

Deletes all LogEntries in this Log .

Returns:

the delete responses

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteLogEntries

DeleteResponseList deleteLogEntries(IdList logEntryIds)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Deletes log entries for the given Ids.

Parameters:

logEntryIds - the Ids of the log entries to delete

Returns:

the delete responses

Throws:

NullArgumentException - logEntryIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteLogEntriesByResource

DeleteResponseList deleteLogEntriesByResource(Id resourceId)
                                              throws OperationFailedException,
                                                     PermissionDeniedException

Deletes log entries for the given resource.

Parameters:

resourceId - the Id of a resource

Returns:

the delete responses

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteLogEntriesByDate

DeleteResponseList deleteLogEntriesByDate(DateTime from,
                                        DateTime to)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Deletes log entries between the given date range inclusive.

Parameters:

from - starting date

to - ending date

Returns:

the delete responses

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.

aliasLogEntries

AliasResponseList aliasLogEntries(AliasRequestList aliasRequests)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Adds an Id to a LogEntry for the purpose of creating compatibility. The primary Id of the Log Entry is determined by the provider. The new Id is an alias to the primary Id. If the alias is a pointer to another log entry, it is reassigned to the given entry Id.

Parameters:

aliasRequests - the alias requests

Returns:

the alias responses

Throws:

NullArgumentException - aliasRequests is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.