HandcarLoggingService

Key HandcarLogging
Version 1.0
Included Services  
Java Package edu.mit.oeit.mc3.handcar.model

The Handcar Logging Service is a RESTful expression of the OSID Logging
manager and related services needed to manage logs and log entries.

Handcar is a simplified, but faithful, expression of the OSIDs that aligns
with the REST goals of simplicity and focuses on exposing OSID objects as
resources.

See href="http://en.wikipedia.org/wiki/Representational_state_transfer">Wikipedia
Representation state transfer

In particular Handcar takes a data centric view whereas the OSIDs exercise
more specific method calls to express its rich functionality.

OSID reference: Logging
Package

Operations
Main Message Structures

Method getLogGenusTypes
Description Gets the list of log genus types.

OSID reference: Log.genusType
REST Signature
GET handcar/services/logging/logs/types/genus?proxyname={XXXX}
Parameters String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return TypeBeanList list of log types that can be used to create logs
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user

Back to Operations

Method getLogEntryGenusTypes
Description Gets the list of logEntry genus types.

OSID reference: LogEntry.genusType
REST Signature
GET handcar/services/logging/logs/types/genus/logentry?proxyname={XXXX}
Parameters String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return TypeBeanList list of logEntry types that can be used to log entries
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException HTTP 404 if the log id does not exist

Back to Operations

Method getLogEntryPriorityTypes
Description Gets the list of logEntry priority types.

OSID reference: LogEntry.priorityType
REST Signature
GET handcar/services/logging/logs/types/priority/logentry?proxyname={XXXX}
Parameters String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return TypeBeanList list of logEntry types that can be used to set log entry priority
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException HTTP 404 if the log id does not exist

Back to Operations

Method getLogEntryExtensionRecord
Description Fetch a particular log entry's EXTENSION record

An EXTENSION record is basically a set of key value pairs holding
additional data not explicitly defined in the object. It is a way to
extend the object without breaking the contract. See
ExtensionRecordBean
for more details.

OSID reference: LogEntry.getLogEntryRecord
REST Signature
GET handcar/services/logging/logs/{logId}/logentries/{logEntryId}/extension?optionalRecordTypeIds={id}&optionalRecordTypeIds={id}...&proxyname={XXXX}
Parameters String logId log that the logEntry is in
String logEntryId id of the logEntry you want to fetch
StringList optionalRecordTypeIds optional list of the record types to
include, if not specified all record types are included
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return ExtensionRecordBean the fetched logEntry's extension record
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException HTTP 404 if the id is not valid

Back to Operations

Method getLogsOptionallyByGenusType
Description Get a list of all logs

OSID reference: LogLookupSession
REST Signature
GET handcar/services/logging/logs/?genustypeids={id}&genustypeids={id}...&proxyname={XXXX}
Parameters StringList genusTypeIds optional list of genus types on which to query
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return LogBeanList list of all logs
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user

Back to Operations

Method getLogById
Description Get a particular log by id

OSID reference: LogLookupSession
REST Signature
GET handcar/services/logging/logs/{logId}?proxyname={XXXX}
Parameters String logId that you want to fetch
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return LogBean the fetched log
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException HTTP 404 if the log id is bad

Back to Operations

Method getLogEntriesInLogByQueryParams
Description Get logEntries in the log optionally by Query Parameters

The entries are ordered by the entries timestamp so that the most recent log entries
appear first.
REST Signature
GET handcar/services/logging/logs/{logId}/logentries?genustypeids={id}&genustypeids={id}...&resourceid={id}&startat={999}&maxvalues={999}&proxyname={XXXX}
Parameters String logId within which the logEntries exist
StringList genusTypeIds optional list of genus types on which to query
String resourceId the value of resourceId
Integer startAt row to start at for paging, start at 1 is the same as not specifying it at all
Integer maxValues max number to be returned
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return LogEntryBeanList LogEntries filtered by the supplied query parameters
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException HTTP 404 if the log id is not known

Back to Operations

Method getLogEntryInLogById
Description Fetch a particular logEntry from a log
REST Signature
GET handcar/services/logging/logs/{logId}/logentries/{logEntryId}?proxyname={XXXX}
Parameters String logId log that the logEntry is in
String logEntryId id of the logEntry you want to fetch
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return LogEntryBean the fetched logEntry
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException HTTP 404 if the logEntry id is not in
the log

Back to Operations

Method getLogEntryById
Description Fetch a particular logEntry regardless of which log it is in
REST Signature
GET handcar/services/logging/logentries/{logEntryId}?proxyname={XXXX}
Parameters String logEntryId id of the logEntry you want to fetch
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return LogEntryBean the fetched logEntry
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException HTTP 404 if the logEntry id is not in
the log

Back to Operations

Method createLog
Description Creates a log

Note: for certain log genus types there can only be one log with that
type. If you try to create another one the pre-existing one is returned
instead.

OSID reference: LogAdminSession
REST Signature
POST {logBean} to  handcar/services/logging/logs?proxyname={XXXX}
{
"id" : "id",
"genusTypeId" : "id",
"displayName" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"description" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"current" : true,
"sortKey" : "XXXX",
"extensionRecord" : {
"recordTypeIds" : ["id", ...],
"recordProperties" : [ {
"displayName" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"description" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"recordTypeId" : "id",
"value" : "XXXX",
"displayLabel" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"associatedId" : "id"
},
...],
"associatedId" : "id"
},
"auditTrail" : {
"addedBy" : "XXXX",
"addedOn" : "YYYY-MM-DDThh:mm:ss",
"updatedBy" : "XXXX",
"updatedOn" : "YYYY-MM-DDThh:mm:ss",
"comment" : "XXXX"
}
}
Parameters LogBean logBean to be created
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return LogBean the newly created log
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException ???
HandcarInvalidArgumentException HTTP 422 if the data is invalid

Back to Operations

Method createLogEntryInLog
Description Creates a logEntry in a log
REST Signature
POST {logEntry} to  handcar/services/logging/logs/{logId}/logentries?proxyname={XXXX}
{
"id" : "id",
"genusTypeId" : "id",
"displayName" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"description" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"resourceId" : "id",
"agentId" : "id",
"priorityTypeId" : "id",
"timestamp" : "YYYY-MM-DD",
"current" : true,
"sortKey" : "XXXX",
"extensionRecord" : {
"recordTypeIds" : ["id", ...],
"recordProperties" : [ {
"displayName" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"description" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"recordTypeId" : "id",
"value" : "XXXX",
"displayLabel" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"associatedId" : "id"
},
...],
"associatedId" : "id"
},
"auditTrail" : {
"addedBy" : "XXXX",
"addedOn" : "YYYY-MM-DDThh:mm:ss",
"updatedBy" : "XXXX",
"updatedOn" : "YYYY-MM-DDThh:mm:ss",
"comment" : "XXXX"
}
}
Parameters String logId within which the logEntry is to be created
LogEntryBean logEntry to be created
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return void ???
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException HTTP 404 if the log or logEntry does not
exist
HandcarInvalidArgumentException HTTP 422 if the data is invalid

Back to Operations

Method updateLogEntryInLog
Description Updates an logEntry

The logEntry Id read-only and cannot be changed and changes will be
silently ignored.

OSID reference: RelationshipAdminSession
REST Signature
PUT {logEntry} to  handcar/services/logging/logs/{logId}/logentries?proxyname={XXXX}
{
"id" : "id",
"genusTypeId" : "id",
"displayName" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"description" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"resourceId" : "id",
"agentId" : "id",
"priorityTypeId" : "id",
"timestamp" : "YYYY-MM-DD",
"current" : true,
"sortKey" : "XXXX",
"extensionRecord" : {
"recordTypeIds" : ["id", ...],
"recordProperties" : [ {
"displayName" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"description" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"recordTypeId" : "id",
"value" : "XXXX",
"displayLabel" : {
"languageTypeId" : "id",
"scriptTypeId" : "id",
"formatTypeId" : "id",
"text" : "XXXX"
},
"associatedId" : "id"
},
...],
"associatedId" : "id"
},
"auditTrail" : {
"addedBy" : "XXXX",
"addedOn" : "YYYY-MM-DDThh:mm:ss",
"updatedBy" : "XXXX",
"updatedOn" : "YYYY-MM-DDThh:mm:ss",
"comment" : "XXXX"
}
}
Parameters String logId within which the logEntry is to be updated
LogEntryBean logEntry to be updated
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return LogEntryBean the newly updated logEntry
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException HTTP 404 if the log or logEntry does not
exist
HandcarInvalidArgumentException HTTP 422 if the data is invalid

Back to Operations

Method deleteLogEntryInLog
Description Delete an logEntry
REST Signature
DELETE handcar/services/logging/logs/{logId}/logentries/{logEntryId}?proxyname={XXXX}
Parameters String logId within which the logEntry exists
String logEntryId id of the logEntry to be deleted
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return LogEntryBean the logEntry as it was before it was deleted
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user
HandcarNotFoundException HTTP 404 if the logEntry is not in the
log

Back to Operations

Method getAuthorizationHintsForLog
Description Get authorization hints for a particular log
REST Signature
GET handcar/services/logging/logs/{logId}/authorization?proxyname={XXXX}
Parameters String logId that you want to fetch
String proxyName optional name of user for whom this operation is being
executed, if not specified taken from security context
Return AuthorizationHintsBean authorization hints for accessing logs
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have
rights to call this method or are not allowed to proxy user

Back to Operations