sunlabs.brazil.template
Class QueueTemplate

java.lang.Object
  sunlabs.brazil.template.Template
      sunlabs.brazil.template.QueueTemplate (view source)

All Implemented Interfaces:

TemplateInterface

public class QueueTemplate
extends Template

Template class for Managing simple Queues, allowing text communication among sessions. The "name" attribute names the Q. When enqueueing messages, "name" is a white space separated list of queue recipients. When Dequeueing Messages, "name" is the recipient Queue.

The following tags are recognized.

• <enqueue name="recipients ..." data=var1 var2 ... varn" [glob="..." delim="." from="sender" nocreate="true|false"] >

• <dequeue name="name" prepend="props prefix" timelimit="sec"> If "timelimit" has a suffix of "ms", then the time is taken in ms.
• <queueinfo name="q_name" prepend="props prefix" clear remove=true|false create=true|false max=n>

This format is supported for backward compatibility with the old behavior. (Just in case the compatibility isn't quite right, see QueueTemplateOld).

• <enqueue name="recipients ..." meta="anything" message="msg" from="sender" [nocreate="true|false"] >

Nested Class Summary

static class	QueueTemplate.Queue Create an object queue.
static class	QueueTemplate.QueueItem A bag of items to keep on the Q.

Field Summary

static String

Q_ID

Fields inherited from class sunlabs.brazil.template.Template

debug

Constructor Summary

QueueTemplate()

Method Summary

static QueueTemplate.QueueItem	dequeue(String name, int timelimit) Program access to the Q.
static void	destroyQueue(String name) Remove a Queue, freeing its resources.
static boolean	enqueue(String to, String from, Dictionary data, boolean noCreate, boolean force) Allow a message to be enqueued from java code.
static boolean	enqueue(String to, String from, String message, String meta, boolean noCreate, boolean force) Deprecated.
static QueueTemplate.Queue	getQ(String name)
static QueueTemplate.Queue	getQ(String name, boolean create) Return a Q.
void	tag_dequeue(RewriteContext hr) Remove an item from the queue, and generate the appropriate properties.
void	tag_enqueue(RewriteContext hr) Add a text message onto a named queue.
void	tag_queueinfo(RewriteContext hr) Return info about the Q, and optionally clear or remove it.

Methods inherited from class sunlabs.brazil.template.Template

done, init

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

Q_ID

public static final String Q_ID

See Also:

Constant Field Values

Constructor Detail

QueueTemplate

public QueueTemplate()

Method Detail

tag_enqueue

public void tag_enqueue(RewriteContext hr)

Add a text message onto a named queue. Attributes:
- name: the name of the queue (required). "name" is a delim list of queues to send the data too.
- from: the sender name
- data: a set of property names to send as name/value pairs. If Names provided of the form nnn#vvv, then "vvv" is taken as the value to use if it is not already set, otherwise the empty string is used as the value.
- nocreate: If set, The item will not be Queued if the Q for that recipient does not already exist.
- force: put to the queue even if its closed
- delim: The delimiter character for the list of names. (It defaults to " " for backward compatibility with the previous behavior)

The property "count" contains the number of recipients for which the message was successfully Queued. The property "error.name" will contain an error message if Queueing failed. In both cases, the template prefix will be prepended. It is not considered an error condition for a message not to be delivered to a non existent Queue if "nocreate" is set.

The experimental attribute "glob" may be used instead of "name", in which case name is taken as the list of "delim" separated tokens named by the first wildcard substring of the matching glob pattern.

enqueue

public static boolean enqueue(String to,
                              String from,
                              String message,
                              String meta,
                              boolean noCreate,
                              boolean force)

Deprecated.

Allow a message to be enqueued from java code. Use the enqueue(String to, String from, Dictionary data, boolean noCreate, boolean force) method instead.

Parameters:

to - The queue name

from - The sender of the data

message - The message to enqueue

meta - The meta data, if any

noCreate - If true, don't create a Q if it doesn't already exist

force - Force item onto Q even if it is closed

Returns:

True, if the data was enqueued

enqueue

public static boolean enqueue(String to,
                              String from,
                              Dictionary data,
                              boolean noCreate,
                              boolean force)

Allow a message to be enqueued from java code.

Parameters:

to - The queue name (only a single q)

from - The sender of the data

data - a dictionary f name/value pairs

noCreate - If true, don't create a Q if it doesn'a already exist

force - Force item onto Q even if it is closed

Returns:

True, if the data was enqueued

destroyQueue

public static void destroyQueue(String name)

Remove a Queue, freeing its resources.

tag_dequeue

public void tag_dequeue(RewriteContext hr)

Remove an item from the queue, and generate the appropriate properties. Attributes:

name

The name of the queue to examine

prepend

The prefix in the properties table to use to set the results. Defaults to our prefix.

timelimit

how long to wait for an item to appear, in sec. Defaults to 30.

If an item is retrieved, the following request properties are set (preceded by prepend):

age

Set how long the message has been q's (in seconds)

sent

Set the timestamp (in sec) of when the item was q'd.

items

Set the number of Q'd items.

from

Set the (unauthenticated) sender.

error

Something went wrong. Set an error message.

In addition, all name/value pairs send as part of the message will be set as well. (In prewvious versions of this template, that consists of "message" and (optionally) "meta".)

Note: this tag blocks until an item is received in the Queue (or a timelimit expires). As template processing is synchronized based on sessions, care should be taken to avoid blocking other (unrelated) session based requests while waiting on the queue.

dequeue

public static QueueTemplate.QueueItem dequeue(String name,
                                              int timelimit)

Program access to the Q.

Parameters:

name - The name of the Q. A new Q will be created if it doesn't already exist.

timelimit - how long (in ms) to wait before returning

Returns:

The Queue item, or Null if no item is available.

tag_queueinfo

public void tag_queueinfo(RewriteContext hr)

Return info about the Q, and optionally clear or remove it. If the queue doesn't already exist, it is created. Attributes:

name

The name of the queue to examine

prepend

The prefix in the properties table to use to set the results. Defaults to our prefix.

clear

If set, then clear the queue

remove

If set, then remove the queue

closed=[true|false]

set the closed state of the Q

create=[true|false]

Should the Q be created if it doesn't already exist (defaults to true).

max=nn

Set the max Queue size (the default is 100). The Queue must already exists (e.g. use create=true if not sure).

The following request properties are set (preceded by prepend):

lastIn

The timestamp (ms) of the last Q insert attempt.

lastOut

The timestamp (ms) of the last Q retrieval attempt.

size

The number of items in the Q.

count

The total number of items inserted into the Q

created

The timestamp (in ms) of the Q's creation

expires

The Q's expiration period (in ms)

max

The maximum queueable items

If the Q doesn't exist (e.g. create=false), then the property "error" is set.

getQ

public static QueueTemplate.Queue getQ(String name,
                                       boolean create)

Return a Q. All calls to the session manager go through here, so we can reap old queues some day.

getQ

public static QueueTemplate.Queue getQ(String name)