001: /*
002: * This file is part of the WfMOpen project.
003: * Copyright (C) 2001-2004 Danet GmbH (www.danet.de), GS-AN.
004: * All rights reserved.
005: *
006: * This program is free software; you can redistribute it and/or modify
007: * it under the terms of the GNU General Public License as published by
008: * the Free Software Foundation; either version 2 of the License, or
009: * (at your option) any later version.
010: *
011: * This program is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
014: * GNU General Public License for more details.
015: *
016: * You should have received a copy of the GNU General Public License
017: * along with this program; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
019: *
020: * $Id: Channel.java,v 1.3 2007/02/07 16:49:43 mlipp Exp $
021: *
022: * $Log: Channel.java,v $
023: * Revision 1.3 2007/02/07 16:49:43 mlipp
024: * Added receiving with timeout.
025: *
026: * Revision 1.2 2006/09/29 12:32:07 drmlipp
027: * Consistently using WfMOpen as projct name now.
028: *
029: * Revision 1.1.1.1 2004/08/18 15:17:36 drmlipp
030: * Update to 1.2
031: *
032: * Revision 1.3 2004/02/13 08:25:29 lipp
033: * Changed channel message data type to Map which is more appropriate.
034: *
035: * Revision 1.2 2004/01/30 14:36:29 lipp
036: * Partial implementation of message receipt.
037: *
038: * Revision 1.1 2004/01/28 16:11:38 lipp
039: * Re-implementation of chabacc, Sender working.
040: *
041: */
042: package de.danet.an.workflow.api;
043:
044: import java.util.Map;
045:
046: import java.rmi.RemoteException;
047:
048: import de.danet.an.workflow.omgcore.InvalidDataException;
049: import de.danet.an.workflow.omgcore.WfObject;
050:
051: /**
052: * This interface defines a named connection with a process that can
053: * be used to receive messages from activities and send messages to
054: * activities.<P>
055: *
056: * Note that messages sent from the workflow engine to clients on a
057: * channel may be lost when no client has opened the channel.
058: *
059: * @author <a href="mailto:lipp@danet.de">Michael Lipp</a>
060: * @version $Revision: 1.3 $
061: */
062:
063: public interface Channel extends WfObject {
064:
065: /**
066: * Return the process this channel belongs to.
067: * @return the process
068: * @throws InvalidKeyException if the process no longer exists
069: * @throws RemoteException if a system-level error occurs
070: */
071: Process process() throws InvalidKeyException, RemoteException;
072:
073: /**
074: * Return the channel name.
075: * @return the name
076: * @throws RemoteException if a system-level error occurs
077: */
078: String name() throws RemoteException;
079:
080: /**
081: * Wait for the next message from the process on this channel. The
082: * message consists of all <code>IN</code> or <code>INOUT</code>
083: * parameters of the sender tool, stored in the
084: * <code>Map</code> object by formal parameter name.
085: *
086: * @return the message or <code>null</code> if the process has
087: * been closed or removed
088: * @throws RemoteException if a system-level error occurs
089: */
090: Map receiveMessage() throws RemoteException;
091:
092: /**
093: * Wait for the next message from the process on this channel within
094: * the specified timeout interval. The
095: * message consists of all <code>IN</code> or <code>INOUT</code>
096: * parameters of the sender tool, stored in the
097: * <code>Map</code> object by formal parameter name.
098: *
099: * @param timeout the timeout value in milliseconds. A timeout
100: * of zero never expires.
101: * @return the message or <code>null</code> if the process has
102: * been closed or removed or the timeout expires
103: * @throws RemoteException if a system-level error occurs
104: */
105: Map receiveMessage(long timeout) throws RemoteException;
106:
107: /**
108: * Send a message on this channel to the process. The message will
109: * be received by an active or subsequently activated receiver
110: * tool listening on this channel. If two or more receiver tools
111: * listen on the same channel concurrently, the message delivery
112: * (only to one or to every receiver) is undefined.<P>
113: *
114: * The message sent is mapped to the formal <code>OUT</code>
115: * parameters of the receiver tool by matching the parameter names
116: * with the data entry names in the message.
117: *
118: * @param msg the message
119: * @throws InvalidKeyException if the process no longer exists
120: * @throws InvalidDataException if the message contains invalid data, i.e.
121: * entries that do not match the name of a formal parameter
122: * @throws RemoteException if a system-level error occurs
123: */
124: void sendMessage(Map msg) throws InvalidKeyException,
125: InvalidDataException, RemoteException;
126: }
|