/**
 * IMessageQueueService.java
 * Created Apr 16, 2007
 * Copyright (c) Tandberg Television 2007
 */
package com.tandbergtv.workflow.driver.service;

import java.util.concurrent.BlockingQueue;

import org.jbpm.graph.exe.Token;

import com.tandbergtv.workflow.core.service.Service;
import com.tandbergtv.workflow.message.WorkflowMessage;

/**
 * A per-token message queue service. The per-token queue is created when the token is active
 * and is destroyed whenever the token stops execution, i.e. when it is paused or cancelled or
 * terminated. Essentially, this service maintains the lifecycle of the queue based upon the
 * lifecycle of the token.
 * 
 * Messages are added to the queue if one exists for the relevant token, otherwise the message is 
 * discarded.
 * 
 * The service also allows read access to the queue so that a token can receive its messages. Note that
 * the queue will block until a message is written to it.
 * 
 * @author Sahil Verma
 */
public interface IMessageQueueService extends Service {
	
	/**
	 * Adds a message for the specified token to the queue.
	 * 
	 * There should only be one message in the queue at any given point of time. The framework
	 * does not support multiple pending requests for a token.
	 * 
	 * @param token
	 * @param message
	 */
	void addMessage(Token token, WorkflowMessage message);
	
	/**
	 * Returns the message queue for the specified token.
	 *  
	 * @param token
	 * @return The Queue
	 */
	BlockingQueue<WorkflowMessage> getQueue(Token token);
}