de.danet.an.workflow.api
Interface Channel

All Superinterfaces:
WfObject

public interface Channel
extends WfObject

This interface defines a named connection with a process that can be used to receive messages from activities and send messages to activities.

Note that messages sent from the workflow engine to clients on a channel may be lost when no client has opened the channel.

Version:
$Revision: 2231 $
Author:
Michael Lipp

Method Summary
 java.lang.String name()
          Return the channel name.
 Process process()
          Return the process this channel belongs to.
 java.util.Map receiveMessage()
          Wait for the next message from the process on this channel.
 java.util.Map receiveMessage(long timeout)
          Wait for the next message from the process on this channel within the specified timeout interval.
 void sendMessage(java.util.Map msg)
          Send a message on this channel to the process.
 

Method Detail

process

public Process process()
                throws InvalidKeyException,
                       java.rmi.RemoteException
Return the process this channel belongs to.

Returns:
the process
Throws:
InvalidKeyException - if the process no longer exists
java.rmi.RemoteException - if a system-level error occurs

name

public java.lang.String name()
                      throws java.rmi.RemoteException
Return the channel name.

Returns:
the name
Throws:
java.rmi.RemoteException - if a system-level error occurs

receiveMessage

public java.util.Map receiveMessage()
                             throws java.rmi.RemoteException
Wait for the next message from the process on this channel. The message consists of all IN or INOUT parameters of the sender tool, stored in the Map object by formal parameter name.

Returns:
the message or null if the process has been closed or removed
Throws:
java.rmi.RemoteException - if a system-level error occurs

receiveMessage

public java.util.Map receiveMessage(long timeout)
                             throws java.rmi.RemoteException
Wait for the next message from the process on this channel within the specified timeout interval. The message consists of all IN or INOUT parameters of the sender tool, stored in the Map object by formal parameter name.

Parameters:
timeout - the timeout value in milliseconds. A timeout of zero never expires.
Returns:
the message or null if the process has been closed or removed or the timeout expires
Throws:
java.rmi.RemoteException - if a system-level error occurs

sendMessage

public void sendMessage(java.util.Map msg)
                 throws InvalidKeyException,
                        InvalidDataException,
                        java.rmi.RemoteException
Send a message on this channel to the process. The message will be received by an active or subsequently activated receiver tool listening on this channel. If two or more receiver tools listen on the same channel concurrently, the message delivery (only to one or to every receiver) is undefined.

The message sent is mapped to the formal OUT parameters of the receiver tool by matching the parameter names with the data entry names in the message.

Parameters:
msg - the message
Throws:
InvalidKeyException - if the process no longer exists
InvalidDataException - if the message contains invalid data, i.e. entries that do not match the name of a formal parameter
java.rmi.RemoteException - if a system-level error occurs