com.sapportals.wcm.service.taskqueue
Interface ITaskQueue

[contained in: com.sap.netweaver.bc.sf.service.par - bc.sf.service.taskqueue_api.jar]

public interface ITaskQueue

Priority queue for tasks.

This interface provides a FIFO container for ITask. Tasks that are added to this queue first are fetched first if they have the same or higher priority than other tasks in the queue.

A queue is assigned to one and only one (case-sensitive} namespace by the underlying task queue service. Therefore a queue manages read-write access for tasks belonging to one specific namespace.

The following example provides a possible usage scenario for a simple single-task system:

An application or service (named A ) may write the following tasks to the queue:

   ITaskQueueReader writer = this.service.getTaskQueueWriter( this.user, SERVICE_ID );
   // create some tasks
   ITask entry1 = writer.createTask( properties1, "entry1" );
   ITask entry2 = writer.createTask( properties2, "entry2" );
   ITask entry3 = writer.createTask( properties3, "entry3" );
   ITask entry4 = writer.createTask( properties4, "entry4" );
   ITask maxPrio = writer.createTask( properties5, "maxPrio", ITask.MAX_PRIORITY );
   ITask minPrio = writer.createTask( properties6, "maxPrio", ITask.MIN_PRIORITY );

   // add 4 tasks to the queue (all have the same priority value)
   writer.add( entry1 );
   writer.add( entry2 );
   writer.add( entry3 );
   writer.add( entry4 );
 

Somewhere else another application (named B ) tries to read some tasks:

   ITaskQueueReader reader = this.service.getTaskQueueReader( this.user, SERVICE_ID );

   // fetch the tasks
   ITask task1 = reader.get();   // gets entry1
   ITask task2 = reader.get();   // gets entry2
   ITask task3 = reader.get();   // gets entry3
   ITask task4 = reader.get();   // gets entry4
 

The reading results may differ if another application writes tasks at the same time to the queue.

Some other examples:

A writes tasks in the order minPrio, entry1, maxPrio, entry3, entry2 . B should read: maxPrio, entry1, entry3, entry2, minPrio (in this order).

A writes tasks in the order entry1, entry2, entry3, maxPrio, minPrio . B should read: maxPrio, entry1, entry2, entry3, minPrio

Copyright (c) SAP AG 2003

Method Summary

ITask	add(ITask task) Adds an entry to the end of the queue.
ITask	get() Removes and returns a task from the head of the queue.
java.lang.String	getNamespace() Returns the service namespace this queue is assigned.
boolean	isEmpty() Indicates if the queue is empty.
ITaskQueueIterator	iterator() Creates an iterator for the task queue entries.
boolean	removeTask(ITask task) Removes a task that is queued by this service.
ITask	top() Returns a task from the head of the queue.

Method Detail

getNamespace

public java.lang.String getNamespace()

Returns the service namespace this queue is assigned.

Returns:

The service value

add

public ITask add(ITask task)
          throws WcmException

Adds an entry to the end of the queue. Raises an excpetion if the entry was already added to the queue.

A queue consists of a list (a sequence) of tasks. The tasks can be added to and removed from the list on a priority basis (lowest priority values first, first-in-first-out (FIFO) basis within priority).

The task's state is set to TaskState.NEW during this operation. A TaskStateTransitionException will be thrown if the task's state already was set to an illegal state.

Parameters:

task - The entry

Throws:

WcmException - Exception raised in failure situation

See Also:

TaskState

get

public ITask get()
          throws WcmException

Removes and returns a task from the head of the queue. The task's state is set to TaskState.ACTIVE during this operation.

Returns:

The head entry

Throws:

WcmException - Exception raised in failure situation

top

public ITask top()
          throws WcmException

Returns a task from the head of the queue.

Returns:

The head entry

Throws:

WcmException - Exception raised in failure situation

removeTask

public boolean removeTask(ITask task)
                   throws WcmException

Removes a task that is queued by this service. The task to remove must have been processed (task state was set to TaskState.DONE or TaskState.ERROR) to avoid non-consistend runtime states.

Parameters:

task - The task to remove

Returns:

true if the task was successful removed

Throws:

WcmException - Exception raised in failure situation

iterator

public ITaskQueueIterator iterator()

Creates an iterator for the task queue entries.

Returns:

A new iterator object

isEmpty

public boolean isEmpty()
                throws WcmException

Indicates if the queue is empty.

Returns:

queue is empty.

Throws:

WcmException - Exception raised in failure situation