com.netscape.certsrv.request

Interface IRequestQueue

public interface IRequestQueue

The IRequestQueue interface defines the operations on a collection of requests within the certificate server. There are may several collections, such as KRA, RA and CA requests. Each of these request collection has a defined set of policies, a notification service (for request completion) and a service routine. The request queue provides an interface for creating and viewing requests, as well as performing operations on them.

Version:

$Revision$ $Date$

Method Summary

Modifier and Type	Method and Description
void	approveRequest(IRequest request) Approves a request.
void	cancelRequest(IRequest request) Cancels a request.
IRequest	cloneAndMarkPending(IRequest r) Clones a request object and mark it pending.
IRequest	cloneRequest(IRequest r) Clones a request object.
IRequest	findRequest(RequestId id) Gets the Request corresponding to id.
RequestId	findRequestBySourceId(java.lang.String id) Locates a request from the SourceId.
IRequestList	findRequestsBySourceId(java.lang.String id) Locates all requests with a particular SourceId.
java.math.BigInteger	getLastRequestIdInRange(java.math.BigInteger reqId_low_bound, java.math.BigInteger reqId_upper_bound)
IRequestVirtualList	getPagedRequests(int pageSize) Gets a pageable list of IRequest entries in this queue.
IRequestVirtualList	getPagedRequestsByFilter(RequestId fromId, boolean jumpToEnd, java.lang.String filter, int pageSize, java.lang.String sortKey) Gets a pageable list of IRequest entries in this queue.
IRequestVirtualList	getPagedRequestsByFilter(RequestId fromId, java.lang.String filter, int pageSize, java.lang.String sortKey) Gets a pageable list of IRequest entries in this queue.
IRequestVirtualList	getPagedRequestsByFilter(java.lang.String filter, int pageSize, java.lang.String sortKey) Gets a pageable list of IRequest entries in this queue.
INotify	getPendingNotify() Retrieves the notifier for pending request.
java.lang.String	getPublishingStatus()
IRepository	getRequestRepository() Gets request repository.
IRequestScheduler	getRequestScheduler() Gets request scheduler.
IRequestList	listRequests() Returns an enumerator that lists all RequestIds in the queue.
IRequestList	listRequestsByFilter(java.lang.String filter) Returns an enumerator that lists all RequestIds for requests that match the filter.
IRequestList	listRequestsByFilter(java.lang.String filter, int maxSize) Returns an enumerator that lists all RequestIds for requests that match the filter.
IRequestList	listRequestsByFilter(java.lang.String filter, int maxSize, int timeLimit) Returns an enumerator that lists all RequestIds for requests that match the filter.
IRequestList	listRequestsByStatus(RequestStatus status) Returns an enumerator that lists all RequestIds for requests that are in the given status.
void	markAsServiced(IRequest r) Marks as serviced after destination authority has serviced request.
void	markRequestPending(IRequest req) Puts a new request into the PENDING state.
IRequest	newRequest(java.lang.String requestType) Creates a new request object.
void	processRequest(IRequest req) Begins processing for this request.
void	recover() Resends requests
void	rejectRequest(IRequest request) Rejects a request.
void	releaseRequest(IRequest r) Releases the LOCK on a request obtained from findRequest() or newRequest()
void	removeAllObjects() Removes all objects with this repository.
void	resetSerialNumber(java.math.BigInteger serial) Resets serial number.
void	setPublishingStatus(java.lang.String status)
void	setRequestScheduler(IRequestScheduler scheduler) Sets request scheduler.
void	updateRequest(IRequest request) Updates the request in the permanent data store.

Method Detail

newRequest

IRequest newRequest(java.lang.String requestType)
             throws EBaseException

Creates a new request object. A request id is assigned to it - see IRequest.getRequestId, and the status is set to RequestStatus.BEGIN

The request is LOCKED. The caller MUST release the request object by calling releaseRequest().

TODO: provide other required values (such as type and sourceId)

Parameters:

requestType - request type

Returns:

new request

Throws:

EBaseException - failed to create new request

cloneRequest

IRequest cloneRequest(IRequest r)
               throws EBaseException

Clones a request object. A new request id is assigned and all attributes of the request is copied to cloned request, except for the sourceID of the original request (remote authority's request Id).

The cloned request that is returned is LOCKED. The caller MUST release the request object by calling releaseRequest().

Parameters:

r - request to be cloned

Returns:

cloned request

Throws:

EBaseException - failed to clone request

findRequest

IRequest findRequest(RequestId id)
              throws EBaseException

Gets the Request corresponding to id. Returns null if the id does not correspond to a valid request id.

Errors may be generated for other conditions.

Parameters:

id - request id

Returns:

found request

Throws:

EBaseException - failed to access request queue

processRequest

void processRequest(IRequest req)
             throws EBaseException

Begins processing for this request. This call is valid only on requests with status BEGIN An error is generated for other cases.

Parameters:

req - request to be processed

Throws:

EBaseException - failed to process request

setRequestScheduler

void setRequestScheduler(IRequestScheduler scheduler)

Sets request scheduler.

Parameters:

scheduler - request scheduler

getRequestScheduler

IRequestScheduler getRequestScheduler()

Gets request scheduler.

Returns:

request scheduler

markRequestPending

void markRequestPending(IRequest req)
                 throws EBaseException

Puts a new request into the PENDING state. This call is only valid for requests with status BEGIN. An error is generated for other cases.

This call might be used by agent servlets that want to copy a previous request, and resubmit it. By putting it into PENDING state, the normal agent screens can be used for further processing.

Parameters:

req - the request to mark PENDING

Throws:

EBaseException - failed to mark request as pending

cloneAndMarkPending

IRequest cloneAndMarkPending(IRequest r)
                      throws EBaseException

Clones a request object and mark it pending. A new request id is assigned and all attributes of the request is copied to cloned request, except for the sourceID of the original request (remote authority's request Id).

The cloned request that is returned is LOCKED. The caller MUST release the request object by calling releaseRequest().

Parameters:

r - request to be cloned

Returns:

cloned request mark PENDING

Throws:

EBaseException - failed to clone or mark request

approveRequest

void approveRequest(IRequest request)
             throws EBaseException

Approves a request. The request must be locked.

This call will fail if: the request is not in PENDING state the policy modules do not accept the request

If the policy modules reject the request, then the request will remain in the PENDING state. Messages from the policy module can be display to the agent to indicate the source of the problem.

The request processing code adds an AgentApproval to this request that contains the authentication id of the agent. This data is retrieved from the Session object (qv).

Parameters:

request - the request that is being approved

Throws:

EBaseException - failed to approve request

rejectRequest

void rejectRequest(IRequest request)
            throws EBaseException

Rejects a request. The request must be locked.

This call will fail if: the request is not in PENDING state

The agent servlet (or other application) may wish to store AgentMessage values to indicate the reason for the action

Parameters:

request - the request that is being rejected

Throws:

EBaseException - failed to reject request

cancelRequest

void cancelRequest(IRequest request)
            throws EBaseException

Cancels a request. The request must be locked.

This call will fail if: the request is not in PENDING state

The agent servlet (or other application) may wish to store AgentMessage values to indicate the reason for the action

Parameters:

request - the request that is being canceled

Throws:

EBaseException - failed to cancel request

updateRequest

void updateRequest(IRequest request)
            throws EBaseException

Updates the request in the permanent data store.

This call can be made after changing a value like source id or owner, to force the new value to be written.

The request must be locked to make this call.

Parameters:

request - the request that is being updated

Throws:

EBaseException - failed to update request

listRequests

IRequestList listRequests()

Returns an enumerator that lists all RequestIds in the queue. The caller should use the RequestIds to locate each request by calling findRequest().

NOTE: This interface will not be useful for large databases. This needs to be replace by a VLV (paged) search object.

Returns:

request list

listRequestsByStatus

IRequestList listRequestsByStatus(RequestStatus status)

Returns an enumerator that lists all RequestIds for requests that are in the given status. For example, all the PENDING requests could be listed by specifying RequestStatus.PENDING as the status argument

NOTE: This interface will not be useful for large databases. This needs to be replace by a VLV (paged) search object.

Parameters:

status - request status

Returns:

request list

listRequestsByFilter

IRequestList listRequestsByFilter(java.lang.String filter)

Returns an enumerator that lists all RequestIds for requests that match the filter.

NOTE: This interface will not be useful for large databases. This needs to be replace by a VLV (paged) search object.

Parameters:

filter - search filter

Returns:

request list

listRequestsByFilter

IRequestList listRequestsByFilter(java.lang.String filter,
                                  int maxSize)

Returns an enumerator that lists all RequestIds for requests that match the filter.

NOTE: This interface will not be useful for large databases. This needs to be replace by a VLV (paged) search object.

Parameters:

filter - search filter

maxSize - max size to return

Returns:

request list

listRequestsByFilter

IRequestList listRequestsByFilter(java.lang.String filter,
                                  int maxSize,
                                  int timeLimit)

Returns an enumerator that lists all RequestIds for requests that match the filter.

NOTE: This interface will not be useful for large databases. This needs to be replace by a VLV (paged) search object.

Parameters:

filter - search filter

maxSize - max size to return

timeLimit - timeout value for the search

Returns:

request list

findRequestBySourceId

RequestId findRequestBySourceId(java.lang.String id)

Locates a request from the SourceId.

Parameters:

id - a unique identifier for the record that is based on the source of the request, and possibly an identify assigned by the source.

Returns:

The requestid corresponding to this source id. null is returned if the source id does not exist.

findRequestsBySourceId

IRequestList findRequestsBySourceId(java.lang.String id)

Locates all requests with a particular SourceId.

Parameters:

id - an identifier for the record that is based on the source of the request

Returns:

A list of requests corresponding to this source id. null is returned if the source id does not exist.

releaseRequest

void releaseRequest(IRequest r)

Releases the LOCK on a request obtained from findRequest() or newRequest()

Parameters:

r - request

markAsServiced

void markAsServiced(IRequest r)

Marks as serviced after destination authority has serviced request. Used by connector.

Parameters:

r - request

recover

void recover()

Resends requests

getPagedRequests

IRequestVirtualList getPagedRequests(int pageSize)

Gets a pageable list of IRequest entries in this queue.

Parameters:

pageSize - page size

Returns:

request list

getPagedRequestsByFilter

IRequestVirtualList getPagedRequestsByFilter(java.lang.String filter,
                                             int pageSize,
                                             java.lang.String sortKey)

Gets a pageable list of IRequest entries in this queue.

Parameters:

filter - search filter

pageSize - page size

sortKey - the attributes to sort by

Returns:

request list

getPagedRequestsByFilter

IRequestVirtualList getPagedRequestsByFilter(RequestId fromId,
                                             java.lang.String filter,
                                             int pageSize,
                                             java.lang.String sortKey)

Gets a pageable list of IRequest entries in this queue.

Parameters:

fromId - request id to start with

filter - search filter

pageSize - page size

sortKey - the attributes to sort by

Returns:

request list

getPagedRequestsByFilter

IRequestVirtualList getPagedRequestsByFilter(RequestId fromId,
                                             boolean jumpToEnd,
                                             java.lang.String filter,
                                             int pageSize,
                                             java.lang.String sortKey)

Gets a pageable list of IRequest entries in this queue. This jumps right to the end of the list

Parameters:

fromId - request id to start with

jumpToEnd - jump to end of list (set fromId to null)

filter - search filter

pageSize - page size

sortKey - the attributes to sort by

Returns:

request list

getPendingNotify

INotify getPendingNotify()

Retrieves the notifier for pending request.

Returns:

notifier for pending request

getLastRequestIdInRange

java.math.BigInteger getLastRequestIdInRange(java.math.BigInteger reqId_low_bound,
                                             java.math.BigInteger reqId_upper_bound)

resetSerialNumber

void resetSerialNumber(java.math.BigInteger serial)
                throws EBaseException

Resets serial number.

Throws:

EBaseException

removeAllObjects

void removeAllObjects()
               throws EBaseException

Removes all objects with this repository.

Throws:

EBaseException

getRequestRepository

IRepository getRequestRepository()

Gets request repository.

Returns:

request repository

getPublishingStatus

java.lang.String getPublishingStatus()

setPublishingStatus

void setPublishingStatus(java.lang.String status)