01: /*
02: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
03: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
04: *
05: * This program is free software; you can redistribute it and/or
06: * modify it under the terms of the GNU General Public License version
07: * 2 only, as published by the Free Software Foundation.
08: *
09: * This program is distributed in the hope that it will be useful, but
10: * WITHOUT ANY WARRANTY; without even the implied warranty of
11: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12: * General Public License version 2 for more details (a copy is
13: * included at /legal/license.txt).
14: *
15: * You should have received a copy of the GNU General Public License
16: * version 2 along with this work; if not, write to the Free Software
17: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
18: * 02110-1301 USA
19: *
20: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
21: * Clara, CA 95054 or visit www.sun.com if you need additional
22: * information or have any questions.
23: */
24:
25: package com.sun.jump.message;
26:
27: import java.io.IOException;
28:
29: /**
30: * <code>JUMPMessageDispatcher</code> is a high-level construct used to
31: * read messages from underlying message queues and distribute them to
32: * listeners.
33: */
34: public interface JUMPMessageDispatcher {
35:
36: /**
37: * Registers the message type for direct receipt via
38: * <code>waitForMessage()</code>. This is akin to a reservation of
39: * the type before blocking on incoming messages.
40: *
41: * @return
42: * opaque object that represents the registration. The token can be
43: * used to cancel the registaration using
44: * {@link #cancelRegistration(Object)}
45: * @throws JUMPMessageDispatcherTypeException if there is already an
46: * existing handler registration for the message type.
47: * @throws IOException if there is a problem registering for the
48: * message type.
49: */
50: public Object registerDirect(String messageType)
51: throws JUMPMessageDispatcherTypeException, IOException;
52:
53: /**
54: * Blocks and waits for a message of type <code>messageType</code>.
55: *
56: * @throws JUMPMessageDispatcherTypeException if there is already
57: * an existing handler registration for the message type, or if it has not
58: * been registered via <code>registerDirect()</code>.
59: *
60: * @throws JUMPTimedOutException
61: * @throws JUMPUnblockedException
62: * @throws IOException
63: */
64: public JUMPMessage waitForMessage(String messageType, long timeout)
65: throws JUMPMessageDispatcherTypeException,
66: JUMPTimedOutException, IOException;
67:
68: /**
69: * Registers the message handler for the message type. This
70: * starts a daemon thread which will persist until all
71: * handlers for the message type have been cancelled.
72: *
73: * @return
74: * opaque object that represents the registration. The token can be
75: * used to cancel the registaration using
76: * {@link #cancelRegistration(Object)}
77: *
78: * @throws JUMPMessageDispatcherTypeException if the message type was
79: * registered via <code>registerDirect()</code>.
80: * @throws IOException if there is a problem registering for the
81: * message type.
82: */
83: public Object registerHandler(String messageType,
84: JUMPMessageHandler handler)
85: throws JUMPMessageDispatcherTypeException, IOException;
86:
87: /**
88: * Removes the registration for the message type. This applies to
89: * direct registrations as well as handler registrations.
90: *
91: * @throws IOException if there is a problem canceling the
92: * registration.
93: * @throws IllegalStateException if the registrationToken
94: * has already been canceled.
95: */
96: public void cancelRegistration(Object registrationToken)
97: throws IOException;
98: }
|