com.pega.pegarules.pub.context

Interface PRQueueManager

public interface PRQueueManager

PegaRULES engine Queue Manager interface. Manipulate items from the System Queue database table, with basic transactional capabilities. Used by Agents and Services to deal with background and item processing across nodes. The Queue Manager object is encapsulated by the creating PegaRULES Requestor, so only one locked item is allowed at a time per requestor.

Services and advanced agent queues can use any of these methods as needed to enqueue, dequeue, browse, and perform other options with the system item queue.

Several properties in the queue item are automatically maintained by the Queue Manager:

System-Queue-.pyItemId - The generated unique key for an item if not provided on enqueue()
System-Queue-.pxCreateDateTime - The datetime this item was enqueued
System-Queue-.pxLastExecutionDateTime - Last time item was retrieved from queue
System-Queue-.pyAttempts - Current number of retrievals performed on this item
@baseclass.pxErrorList - List of errors recorded by rollback attempts
System-Queue-.pxMinimumExecutionDateTime - The earliest datetime that this item can be processed. Defaults to .pxCreateDateTime

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	COPYRIGHT
static char	MODE_ADVANCED For Agent Processing: Indicates a 5.4 agent queue that will explicitly use the Queue Manager to perform custom operations with the system queue.
static char	MODE_COMPATIBLE For Agent Processing: Indicates a pre-5.4 backwards compatible agent queue.
static char	MODE_QUEUEPROCESSING For Agent Processing: Indicates the default mode for new 5.4 agents.
static java.lang.String	OPTION_DEFERRED Is this being called from deferredDelete() to drop a queue item without retrieving it
static java.lang.String	OPTION_DELETE Is this being called from delete() to drop a queue item without retrieving it
static java.lang.String	OPTION_ITEM_STATUS
static java.lang.String	OPTION_LOCK Should queue manager attempt to lock a selected item?
static java.lang.String	OPTION_REMOVE Should queue manager attempt to remove item from queue upon selection?
static java.lang.String	OPTION_UPDATE_STATS Should queue manager update various metadata properties on the item?
static java.lang.String	QUEUE_PAGE
static java.lang.String	STATUS_BROKEN_PROCESS Item status: Failed to process, cannot retry
static java.lang.String	STATUS_IMMEDIATE Item status: Initial status for items that should be processed as a service request
static java.lang.String	STATUS_NOW_PROCESSING Item status: Currently reserved for processing by a node
static java.lang.String	STATUS_SCHEDULED Item status: Initial status for items that should be processed by an agent
static java.lang.String	STATUS_SUCCESS Item status: Successfully processed
static java.lang.String	VERSION

Method Summary

Modifier and Type	Method and Description
void	addErrorMessage(java.lang.String aMessage) If there is a locked item, add a new error message to the pxErrorList property and add diagnostics to the pxErrorDetails property
void	addErrorMessage(java.lang.String aMessage, java.lang.Throwable t) If there is a locked item, add a new error message to the pxErrorList property and add diagnostics to the pxErrorDetails property.
void	commit() Commit currently locked queue item to queue.
void	delete(java.lang.String aItemId) Delete an item immediately from the queue by Item ID.
void	deleteDeferred(java.lang.String aItemId) Delete an item from the queue by Item ID.
ClipboardPage	dequeue(java.lang.String aItemId) Return one specific item from the queue by Item ID.
ClipboardPage	dequeue(java.lang.String aItemId, StringMap aOptions) Return one specific item from the queue by Item ID.
ClipboardPage	dequeueForUpdate(java.lang.String aItemId) Return one specific item from the queue by Item ID.
ClipboardPage	dequeueForUpdate(java.lang.String aItemId, StringMap aOptions) Return one specific item from the queue by Item ID.
ClipboardPage	dequeueLightWeight(java.lang.String aItemId, StringMap aOptions) Return one specific item which does not have stream from the queue by Item ID.
java.lang.String	enqueue(ClipboardPage aItemPage) Immediately enqueue an item for processing.
java.lang.String	enqueue(ClipboardPage aItemPage, boolean aWithErrors) Immediately enqueue an item for processing, optionally allowing page to be saved with page/property messagse.
java.lang.String	enqueueDeferred(ClipboardPage aItemPage) Enqueue an item for processing, on the deferred operation list.
java.lang.String	enqueueDeferred(ClipboardPage aItemPage, boolean aWithErrors) Enqueue an item for processing, on the deferred operation list.
java.lang.String	enqueueLightWeight(ClipboardPage aItemPage) Immediately enqueue an item for processing.
java.lang.String	enqueueLightWeightDeferred(ClipboardPage aItemPage) Enqueue an item for processing, on the deferred operation list.
ClipboardPage	getFirst(java.lang.String aQueueClass, StringMap aOptions) Get and lock the first available queue item based on the specified criteria Options:
ClipboardPage	getFirst(java.lang.String aQueueClass, java.lang.String aAgentName, StringMap aOptions) Get and lock the first available queue item based on the specified criteria Options:
ClipboardPage	getLockedItem() Get the currently locked item (or null) for this Queue Manager
java.util.Date	getNextExecutionDateTime(ClipboardPage aItemPage) Returns the next execution DateTime of an Item.
java.lang.String	getNodeId()
boolean	hasLockedItem() Does this QueueManager currently have an item locked?
PRQueueIterator	iterator(java.lang.String aQueueClass) Get simple iterator object that will return the next item matching the specified class of status "Scheduled".
PRQueueIterator	iterator(java.lang.String aQueueClass, java.lang.String aAgentName) Get simple iterator object that will return the next item matching the specified class of status "Scheduled".
PRQueueIterator	iterator(java.lang.String aQueueClass, StringMap aOptions) Get simple iterator object that will return the next item matching the specified criteria.
PRQueueIterator	iterator(java.lang.String aQueueClass, java.lang.String aAgentName, StringMap aOptions) Get simple iterator object that will return the next item matching the specified criteria.
PRQueueIterator	lightWeightIterator(java.lang.String aQueueClass, StringMap aOptions) Get simple iterator object that will return the next item matching the specified criteria.This API needs to be used to retrieve the items enqueued using enqueueLightWeightDeferred(ClipboardPage aItemPage)
PRQueueIterator	lightWeightIterator(java.lang.String aQueueClass, java.lang.String aAgentName, StringMap aOptions) Get simple iterator object that will return the next item matching the specified criteria.This API needs to be used to retrieve the items enqueued using enqueueLightWeightDeferred(ClipboardPage aItemPage)
boolean	repair(java.lang.String aItemId) Repair an item that is broken.
boolean	repairDeferred(java.lang.String aItemId) Repair an item that is broken, using a deferred save.
void	rollback() Deal with failed item processing for the currently locked item.
void	rollback(java.lang.String aReason)
void	setUseRequestorId(boolean aUse) Should locking be done on a per-requestor or per-node basis.
void	update() Perform an immediate update (save) of the currently locked item.
void	update(ClipboardPage aItemPage) Perform an immediate update (save) of the specified item.
void	updateDeferred(ClipboardPage aItemPage) Perform a deferred update (save) of the specified item.
void	updateDeferred(ClipboardPage aItemPage, boolean repairBroken) Perform a deferred update (save) of the specified item.

Field Detail

MODE_COMPATIBLE

static final char MODE_COMPATIBLE

For Agent Processing: Indicates a pre-5.4 backwards compatible agent queue. Will not use Queue Manager for processing: Agent activity is responsible for all transactional and queue related functions.

See Also:

Constant Field Values

MODE_QUEUEPROCESSING

static final char MODE_QUEUEPROCESSING

For Agent Processing: Indicates the default mode for new 5.4 agents. Agent is only responsible for business processing of a queue item. The Queue Manager will handle queue items and transactional functions.

See Also:

Constant Field Values

MODE_ADVANCED

static final char MODE_ADVANCED

For Agent Processing: Indicates a 5.4 agent queue that will explicitly use the Queue Manager to perform custom operations with the system queue.

See Also:

Constant Field Values

OPTION_ITEM_STATUS

static final java.lang.String OPTION_ITEM_STATUS

See Also:

Constant Field Values

OPTION_LOCK

static final java.lang.String OPTION_LOCK

Should queue manager attempt to lock a selected item?

See Also:

Constant Field Values

OPTION_REMOVE

static final java.lang.String OPTION_REMOVE

Should queue manager attempt to remove item from queue upon selection?

See Also:

Constant Field Values

OPTION_DEFERRED

static final java.lang.String OPTION_DEFERRED

Is this being called from deferredDelete() to drop a queue item without retrieving it

See Also:

Constant Field Values

OPTION_DELETE

static final java.lang.String OPTION_DELETE

Is this being called from delete() to drop a queue item without retrieving it

See Also:

Constant Field Values

OPTION_UPDATE_STATS

static final java.lang.String OPTION_UPDATE_STATS

Should queue manager update various metadata properties on the item?

See Also:

Constant Field Values

STATUS_SUCCESS

static final java.lang.String STATUS_SUCCESS

Item status: Successfully processed

See Also:

Constant Field Values

STATUS_BROKEN_PROCESS

static final java.lang.String STATUS_BROKEN_PROCESS

Item status: Failed to process, cannot retry

See Also:

Constant Field Values

STATUS_NOW_PROCESSING

static final java.lang.String STATUS_NOW_PROCESSING

Item status: Currently reserved for processing by a node

See Also:

Constant Field Values

STATUS_SCHEDULED

static final java.lang.String STATUS_SCHEDULED

Item status: Initial status for items that should be processed by an agent

See Also:

Constant Field Values

STATUS_IMMEDIATE

static final java.lang.String STATUS_IMMEDIATE

Item status: Initial status for items that should be processed as a service request

See Also:

Constant Field Values

QUEUE_PAGE

static final java.lang.String QUEUE_PAGE

See Also:

Constant Field Values

COPYRIGHT

static final java.lang.String COPYRIGHT

See Also:

Constant Field Values

VERSION

static final java.lang.String VERSION

Method Detail

enqueue

java.lang.String enqueue(ClipboardPage aItemPage)
                  throws DatabaseException

Immediately enqueue an item for processing. Item must have a pxObjClass extending System-Queue-, and must have a pyItemStatus of either "Scheduled" or "Immediate".

Item will have some properties generated and updated, and then be inserted into the system queue with an immediate save.

Optional properties that affect processing of this item:

pyAgentName (String): Will let a specific browse the queue for items assigned to it by name. This needs to be specified in the form RuleSet:AgentName, where RuleSet is the rule set name of the Rule-Agent-Queue record, and AgentName is the "Agent Name" field from the targeted row in the agent queue form. pyRetainOnFailure (true, false): Determines whether to retain item in queue when maximum number of rollbacks (failures) have been reached. Default is true.
pyRetainOnSuccess (true, false): Determines whether item will be updated in queue with Success status when commit() occurs, or if item will just be removed from queue. Default is false.
pyMaxAttempts (number): Maximum allowed attempts to process this item before it is considered broken, and either removed or status updated to Broken-Process. Default is 1. (see pyRetainOnFailure)
pyMinimumAgeForProcessing (number): Minimum delay (in milliseconds) after item was either created or last processed before item can be locked for processing again. Default is 0.
pyMinimumDateTimeForProcessing (datetime): Minimum date/time after item was either created or last processed before item can be locked for processing again. Default is current date/time.
pyRequeuePattern (String: "Daily", "Weekly", "Monthly", "Yearly"): If pyRequeueOnSuccess is true, what should the delay be for processing the requeued item?
pyDuplicateProperty (String): When calling enqueue(), will force a check for existing queue items to see if the new item is a duplicate of an existing item. Duplicate check is done using 3 checks: Does the queue item class match? Does the agent name match? If both are true, it will check the value of the property specified in pyDuplicateProperty to see if the value matches in the new item and the existing item. If all these conditions are true, this method will return the id of the existing item instead of enqueueing the new item.
pyManualTransactionHandling (boolean): When item is locked when dequeued/browsed, it will not be considered for commit or rollback until the queue manager is manually informed that the item can be processed. The default behavior is that the item is processed whenever a database commit or rollback occurs. This setting allows an agent to prevent automatic commit/rollback processing of the locked item until the agent activity completes.

These fields will be created/updated when item is enqueued:

pxCreateDateTime - Date/time item was enqueued
pyItemId - unique generated key across all queue classes and nodes
pyAttempts - Set to "0" on enqueue

Parameters:

aItemPage - ClipboardPage with instance class extending System-Queue-

Returns:

String pyItemId unique key for item.

Throws:

DatabaseException - if save operation failed

enqueue

java.lang.String enqueue(ClipboardPage aItemPage,
                         boolean aWithErrors)
                  throws DatabaseException

Immediately enqueue an item for processing, optionally allowing page to be saved with page/property messagse. Item must have a pxObjClass extending System-Queue-, and must have a pyItemStatus of either "Scheduled" or "Immediate".

Item will have some properties generated and updated, and then be inserted into the system queue with an immediate save.

Parameters:

aItemPage - ClipboardPage with instance class extending System-Queue-

aWithErrors - If true, allow item to be saved even if page or property messages exist

Returns:

String pyItemId unique key for item.

Throws:

DatabaseException - if save operation failed

enqueueDeferred

java.lang.String enqueueDeferred(ClipboardPage aItemPage)
                          throws DatabaseException

Enqueue an item for processing, on the deferred operation list. Item must have a pxObjClass extending System-Queue-, and must have a pyItemStatus of either "Scheduled" or "Immediate".

Item will have some properties generated and updated, and then be inserted into the system queue with an immediate save.

Optional properties that affect processing of this item:

pyAgentName (String): Will let a specific browse the queue for items assigned to it by name. This needs to be specified in the form RuleSet:AgentName, where RuleSet is the rule set name of the Rule-Agent-Queue record, and AgentName is the "Agent Name" field from the targeted row in the agent queue form. pyRetainOnFailure (true, false): Determines whether to retain item in queue when maximum number of rollbacks (failures) have been reached. Default is true.
pyRetainOnSuccess (true, false): Determines whether item will be updated in queue with Success status when commit() occurs, or if item will just be removed from queue. Default is false.
pyMaxAttempts (number): Maximum allowed attempts to process this item before it is considered broken, and either removed or status updated to Broken-Process. Default is 1. (see pyRetainOnFailure)
pyMinimumAgeForProcessing (number): Minimum delay (in milliseconds) after item was either created or last processed before item can be locked for processing again. Default is 0.
pyMinimumDateTimeForProcessing (datetime): Minimum date/time after item was either created or last processed before item can be locked for processing again. Default is current date/time.
pyRequeuePattern (String: "Daily", "Weekly", "Monthly", "Yearly"): If pyRequeueOnSuccess is true, what should the delay be for processing the requeued item?
pyDuplicateProperty (String): When calling enqueue(), will force a check for existing queue items to see if the new item is a duplicate of an existing item. Duplicate check is done using 3 checks: Does the queue item class match? Does the agent name match? If both are true, it will check the value of the property specified in pyDuplicateProperty to see if the value matches in the new item and the existing item. If all these conditions are true, this method will return the id of the existing item instead of enqueueing the new item.
pyManualTransactionHandling (boolean): When item is locked when dequeued/browsed, it will not be considered for commit or rollback until the queue manager is manually informed that the item can be processed. The default behavior is that the item is processed whenever a database commit or rollback occurs. This setting allows an agent to prevent automatic commit/rollback processing of the locked item until the agent activity completes.

These fields will be created/updated when item is enqueued:

pxCreateDateTime - Date/time item was enqueued
pyItemId - unique generated key across all queue classes and nodes
pyAttempts - Set to "0" on enqueue

Parameters:

aItemPage - ClipboardPage with instance class extending System-Queue-

Returns:

String pyItemId unique key for item.

Throws:

DatabaseException - if save operation failed

enqueueDeferred

java.lang.String enqueueDeferred(ClipboardPage aItemPage,
                                 boolean aWithErrors)
                          throws DatabaseException

Enqueue an item for processing, on the deferred operation list. Item must have a pxObjClass extending System-Queue-, and must have a pyItemStatus of either "Scheduled" or "Immediate".

Item will have some properties generated and updated, and then be inserted into the system queue with an immediate save.

Optional properties that affect processing of this item:

pyAgentName (String): Will let a specific browse the queue for items assigned to it by name. This needs to be specified in the form RuleSet:AgentName, where RuleSet is the rule set name of the Rule-Agent-Queue record, and AgentName is the "Agent Name" field from the targeted row in the agent queue form. pyRetainOnFailure (true, false): Determines whether to retain item in queue when maximum number of rollbacks (failures) have been reached. Default is true.
pyRetainOnSuccess (true, false): Determines whether item will be updated in queue with Success status when commit() occurs, or if item will just be removed from queue. Default is false.
pyMaxAttempts (number): Maximum allowed attempts to process this item before it is considered broken, and either removed or status updated to Broken-Process. Default is 1. (see pyRetainOnFailure)
pyMinimumAgeForProcessing (number): Minimum delay (in milliseconds) after item was either created or last processed before item can be locked for processing again. Default is 0.
pyMinimumDateTimeForProcessing (datetime): Minimum date/time after item was either created or last processed before item can be locked for processing again. Default is current date/time.
pyRequeuePattern (String: "Daily", "Weekly", "Monthly", "Yearly"): If pyRequeueOnSuccess is true, what should the delay be for processing the requeued item?
pyDuplicateProperty (String): When calling enqueue(), will force a check for existing queue items to see if the new item is a duplicate of an existing item. Duplicate check is done using 3 checks: Does the queue item class match? Does the agent name match? If both are true, it will check the value of the property specified in pyDuplicateProperty to see if the value matches in the new item and the existing item. If all these conditions are true, this method will return the id of the existing item instead of enqueueing the new item.
pyManualTransactionHandling (boolean): When item is locked when dequeued/browsed, it will not be considered for commit or rollback until the queue manager is manually informed that the item can be processed. The default behavior is that the item is processed whenever a database commit or rollback occurs. This setting allows an agent to prevent automatic commit/rollback processing of the locked item until the agent activity completes.

These fields will be created/updated when item is enqueued:

pxCreateDateTime - Date/time item was enqueued
pyItemId - unique generated key across all queue classes and nodes
pyAttempts - Set to "0" on enqueue

Parameters:

aItemPage - ClipboardPage with instance class extending System-Queue-

aWithErrors - If true, allow item to be saved even if page or property messages exist

Returns:

String pyItemId unique key for item.

Throws:

DatabaseException - if save operation failed

dequeue

ClipboardPage dequeue(java.lang.String aItemId,
                      StringMap aOptions)

Return one specific item from the queue by Item ID.

Options that can override settings found in queue item itself:

Lock (true/false): If true, acquire a lock on the item which will be released
upon commit or rollback of transaction. Default is false. Remove (true/false): If true, item is removed from queue immediately upon retrieval. Default is false
UpdateStats (true/false): If true, some statistical metadata in the queue item will be updated immediately. Default is true

Parameters:

aItemId - Item key (pyItemId)

aOptions - Map of dequeueing options (can be null)

Returns:

ClipboardPage Item page, extending class System-Queue-, or null if item not found in queue.

dequeueForUpdate

ClipboardPage dequeueForUpdate(java.lang.String aItemId)

Return one specific item from the queue by Item ID.

By default, will lock and set UpdateStats to false

Parameters:

aItemId - Item key (pyItemId)

Returns:

ClipboardPage Item page, extending class System-Queue-, or null if item not found in queue.

dequeueForUpdate

ClipboardPage dequeueForUpdate(java.lang.String aItemId,
                               StringMap aOptions)

Return one specific item from the queue by Item ID. This dequeue method is to be used only for updating a Queue item. For other purposes use dequeue(String) or dequeue(String,StringMap) methods

Lock (true/false): If false, give error
UpdateStats (true/false): If true, give error
Remove (true/false): If true, give error

Parameters:

aItemId - Item key (pyItemId)

aOptions - Map of dequeueing options (can be null)

Returns:

ClipboardPage Item page, extending class System-Queue-, or null if item not found in queue.

dequeue

ClipboardPage dequeue(java.lang.String aItemId)

Return one specific item from the queue by Item ID.

By default, will not lock or remove the item from the queue.

Parameters:

aItemId - Item key (pyItemId)

Returns:

ClipboardPage Item page, extending class System-Queue-, or null if item not found in queue.

commit

void commit()
     throws DatabaseException

Commit currently locked queue item to queue. Will either update status or remove item from queue depending on pyRetainOnSuccess property.

Does not perform database commit.

Throws:

DatabaseException - If error occurs during update/remove process

rollback

void rollback()
       throws DatabaseException

Deal with failed item processing for the currently locked item. First compares pyAttempts to pyMaxAttempts. If pyAttempts is less than allowed maximum, item status is reverted to original status and item in queue is updated, with pyAttempts incremented. If pyATtempts is greater than pyMaxAttempts, and pyRetainOnFailure is true, item status is updated to "Broken-Process" and item in queue is updated. If pyRetainOnFailure is false, item is deleted from queue.

Does not perform database rollback.

Throws:

DatabaseException - If error occurs during update/remove process

rollback

void rollback(java.lang.String aReason)
       throws DatabaseException

Parameters:

aReason - Reason string (will be added to pxErrorList value list property)

Throws:

DatabaseException - If error occurs during update/remove process

See Also:

rollback

repair

boolean repair(java.lang.String aItemId)
        throws DatabaseException

Repair an item that is broken. Resets to Scheduled status, clear error information, reset retry information, and requeue (without creating a new item).

Parameters:

aItemId - Item ID (as returned from enqueue() method) to repair

Returns:

boolean Did repair succeed

Throws:

DatabaseException

repairDeferred

boolean repairDeferred(java.lang.String aItemId)
                throws DatabaseException

Repair an item that is broken, using a deferred save. Resets to Scheduled status, clear error information, reset retry information, and requeue as a deferred operation (without creating a new item).

Parameters:

aItemId - Item ID (as returned from enqueue() method) to repair

Returns:

boolean Did repair succeed

Throws:

DatabaseException

iterator

PRQueueIterator iterator(java.lang.String aQueueClass)

Get simple iterator object that will return the next item matching the specified class of status "Scheduled".

Defaults to locking oldest scheduled item, and retaining item in queue until commit or rollback.

Parameters:

aQueueClass - Class of queue item to retrieve

Returns:

iterator

iterator

PRQueueIterator iterator(java.lang.String aQueueClass,
                         java.lang.String aAgentName)

Get simple iterator object that will return the next item matching the specified class of status "Scheduled".

Defaults to locking oldest scheduled item, and retaining item in queue until commit or rollback.

Parameters:

aQueueClass - Class of queue item to retrieve

aAgentName - Filter items by pyAgentName

Returns:

iterator

iterator

PRQueueIterator iterator(java.lang.String aQueueClass,
                         StringMap aOptions)

Get simple iterator object that will return the next item matching the specified criteria.

Options:

ItemStatus (String): What kind of item (pyItemStatus) to browse, either "Immediate" or "Scheduled". Default is "Scheduled"
Remove ("true"/"false"): If true, item is removed from queue upon retrieval. Default is false.
UpdateStats ("true"/"false"): If true, update various statistical metadata in the item during locking or removal operation. Default is true.

Parameters:

aQueueClass - Class of queue item to retrieve

aOptions - String map of options (see above)

Returns:

iterator

iterator

PRQueueIterator iterator(java.lang.String aQueueClass,
                         java.lang.String aAgentName,
                         StringMap aOptions)

Get simple iterator object that will return the next item matching the specified criteria.

Options:

ItemStatus (String): What kind of item (pyItemStatus) to browse, either "Immediate" or "Scheduled". Default is "Scheduled"
Remove ("true"/"false"): If true, item is removed from queue upon retrieval. Default is false.
UpdateStats ("true"/"false"): If true, update various statistical metadata in the item during locking or removal operation. Default is true.

Parameters:

aQueueClass - Class of queue item to retrieve

aAgentName - Filter items by pyAgentName

aOptions - String map of options (see above)

Returns:

iterator

getFirst

ClipboardPage getFirst(java.lang.String aQueueClass,
                       StringMap aOptions)

Get and lock the first available queue item based on the specified criteria Options:

ItemStatus (String): What kind of item (pyItemStatus) to browse, either "Immediate" or "Scheduled". Default is "Scheduled"
Remove ("true"/"false"): If true, item is removed from queue upon retrieval. Default is false.
UpdateStats ("true"/"false"): If true, update various statistical metadata in the item during locking or removal operation. Default is true.

Parameters:

aQueueClass - Class of queue item to retrieve

aOptions - String map of options (see above)

Returns:

page

getFirst

ClipboardPage getFirst(java.lang.String aQueueClass,
                       java.lang.String aAgentName,
                       StringMap aOptions)

Get and lock the first available queue item based on the specified criteria Options:

ItemStatus (String): What kind of item (pyItemStatus) to browse, either "Immediate" or "Scheduled". Default is "Scheduled"
Remove ("true"/"false"): If true, item is removed from queue upon retrieval. Default is false.
UpdateStats ("true"/"false"): If true, update various statistical metadata in the item during locking or removal operation. Default is true.

Parameters:

aQueueClass - Class of queue item to retrieve

aAgentName - Filter items by pyAgentName

aOptions - String map of options (see above)

Returns:

page

update

void update(ClipboardPage aItemPage)
     throws DatabaseException

Perform an immediate update (save) of the specified item. Must match currently locked item, otherwise exception is thrown.

Parameters:

aItemPage - System-Queue- page.

Throws:

PRRuntimeException - If specified item is not currently locked by this Queue Manager

DatabaseException - If error occurs during update/remove process

updateDeferred

void updateDeferred(ClipboardPage aItemPage)
             throws DatabaseException

Perform a deferred update (save) of the specified item. Must match currently locked item, otherwise exception is thrown.

Parameters:

aItemPage - System-Queue- page.

Throws:

PRRuntimeException - If specified item is not currently locked by this Queue Manager

DatabaseException - If error occurs during update/remove process

updateDeferred

void updateDeferred(ClipboardPage aItemPage,
                    boolean repairBroken)
             throws DatabaseException

Perform a deferred update (save) of the specified item. Must match currently locked item, otherwise exception is thrown.

Parameters:

aItemPage - System-Queue- page.

repairBroken - if the "Broken-Process" should be repaired

Throws:

PRRuntimeException - If specified item is not currently locked by this Queue Manager

DatabaseException - If error occurs during update/remove process

update

void update()
     throws DatabaseException

Perform an immediate update (save) of the currently locked item. If no item is locked by this QueueManager, throws exception.

Throws:

PRRuntimeException - If no item is currently locked by this Queue Manager

DatabaseException - If error occurs during update/remove process

hasLockedItem

boolean hasLockedItem()

Does this QueueManager currently have an item locked?

Returns:

boolean Is there a locked item?

getLockedItem

ClipboardPage getLockedItem()

Get the currently locked item (or null) for this Queue Manager

Returns:

ClipboardPage The locked item, or null if no item is locked

addErrorMessage

void addErrorMessage(java.lang.String aMessage)

If there is a locked item, add a new error message to the pxErrorList property and add diagnostics to the pxErrorDetails property

Parameters:

aMessage -

addErrorMessage

void addErrorMessage(java.lang.String aMessage,
                     java.lang.Throwable t)

If there is a locked item, add a new error message to the pxErrorList property and add diagnostics to the pxErrorDetails property. Will include stack trace from specified exception in the error details page.

Parameters:

aMessage -

t -

setUseRequestorId

void setUseRequestorId(boolean aUse)

Should locking be done on a per-requestor or per-node basis. Default uses node id to establish lock on a queue item.

Parameters:

aUse -

delete

void delete(java.lang.String aItemId)
     throws DatabaseException

Delete an item immediately from the queue by Item ID.

Acquire lock and delete item from queue.

Parameters:

aItemId - Item key (pyItemId)

Throws:

DatabaseException - If error occurs during delete process

deleteDeferred

void deleteDeferred(java.lang.String aItemId)
             throws DatabaseException

Delete an item from the queue by Item ID.

Acquire lock and delete item from queue.

Parameters:

aItemId - Item key (pyItemId)

Throws:

DatabaseException - If error occurs during delete process

getNextExecutionDateTime

java.util.Date getNextExecutionDateTime(ClipboardPage aItemPage)

Returns the next execution DateTime of an Item. Item must have a pxObjClass extending System-Queue-

Parameters:

aItemPage - ClipboardPage with instance class extending System-Queue-

Returns:

Date next execution Date of the Item

enqueueLightWeight

java.lang.String enqueueLightWeight(ClipboardPage aItemPage)
                             throws DatabaseException

Immediately enqueue an item for processing. Item must have a pxObjClass extending System-Queue-, and must have a pyItemStatus of either "Scheduled" or "Immediate". The queue class should be mapped to a table which does not have stream(pzPvStream) column

The caller should make sure that the page does not have any non scalar properties. Item will have some properties generated and updated, and then be inserted into the system queue with an immediate save. It will not add any non-scalar properties to the page.

Parameters:

aItemPage - ClipboardPage with instance class extending System-Queue-

Returns:

String pyItemId unique key for item.

Throws:

DatabaseException - if save operation failed

enqueueLightWeightDeferred

java.lang.String enqueueLightWeightDeferred(ClipboardPage aItemPage)
                                     throws DatabaseException

Enqueue an item for processing, on the deferred operation list. Item must have a pxObjClass extending System-Queue-, and must have a pyItemStatus of either "Scheduled" or "Immediate". The queue class should be mapped to a table which does not have stream(pzPvStream) column

The caller should make sure that the page does not have any non scalar properties. Item will have some properties generated and updated, and then be inserted into the system queue with deferred save. It will not add any non-scalar properties to the page.

Parameters:

aItemPage - ClipboardPage with instance class extending System-Queue-

Returns:

String pyItemId unique key for item.

Throws:

DatabaseException - if save operation failed

dequeueLightWeight

ClipboardPage dequeueLightWeight(java.lang.String aItemId,
                                 StringMap aOptions)

Return one specific item which does not have stream from the queue by Item ID. This API needs to be used to retrieve the items enqueued using enqueueLightWeightDeferred(ClipboardPage aItemPage)

Options that can override settings found in queue item itself:

Remove (true/false): If true, item is removed from queue immediately upon retrieval. Default is false

Parameters:

aItemId - Item key (pyItemId)

aOptions - Map of dequeueing options (cannot be null. For Lightweight queue items, REMOVE option should always be specified)

Returns:

ClipboardPage Item page, extending class System-Queue-, or null if item not found in queue.

lightWeightIterator

PRQueueIterator lightWeightIterator(java.lang.String aQueueClass,
                                    StringMap aOptions)

Get simple iterator object that will return the next item matching the specified criteria.This API needs to be used to retrieve the items enqueued using enqueueLightWeightDeferred(ClipboardPage aItemPage)

Options:

ItemStatus (String): What kind of item (pyItemStatus) to browse, either "Immediate" or "Scheduled". Default is "Scheduled"
Remove ("true"/"false"): If true, item is removed from queue upon retrieval. Default is false.

Parameters:

aQueueClass - Class of queue item to retrieve

aOptions - String map of options (see above)

Returns:

iterator

lightWeightIterator

PRQueueIterator lightWeightIterator(java.lang.String aQueueClass,
                                    java.lang.String aAgentName,
                                    StringMap aOptions)

Get simple iterator object that will return the next item matching the specified criteria.This API needs to be used to retrieve the items enqueued using enqueueLightWeightDeferred(ClipboardPage aItemPage)

Options:

ItemStatus (String): What kind of item (pyItemStatus) to browse, either "Immediate" or "Scheduled". Default is "Scheduled"
Remove ("true"/"false"): If true, item is removed from queue upon retrieval. Default is false.

Parameters:

aQueueClass - Class of queue item to retrieve

aAgentName - Filter items by pyAgentName

aOptions - String map of options (see above)

Returns:

iterator

getNodeId

java.lang.String getNodeId()