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: 1659 $ $Date: 2010-12-20 23:42:50 -0800 (Mon, 20 Dec 2010) $

Method Summary
 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)