Source code: org/apache/axis/ime/internal/util/KeyedBuffer.java
1 /*
2 * The Apache Software License, Version 1.1
3 *
4 *
5 * Copyright (c) 2001-2003 The Apache Software Foundation. All rights
6 * reserved.
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 *
15 * 2. Redistributions in binary form must reproduce the above copyright
16 * notice, this list of conditions and the following disclaimer in
17 * the documentation and/or other materials provided with the
18 * distribution.
19 *
20 * 3. The end-user documentation included with the redistribution,
21 * if any, must include the following acknowledgment:
22 * "This product includes software developed by the
23 * Apache Software Foundation (http://www.apache.org/)."
24 * Alternately, this acknowledgment may appear in the software itself,
25 * if and wherever such third-party acknowledgments normally appear.
26 *
27 * 4. The names "Axis" and "Apache Software Foundation" must
28 * not be used to endorse or promote products derived from this
29 * software without prior written permission. For written
30 * permission, please contact apache@apache.org.
31 *
32 * 5. Products derived from this software may not be called "Apache",
33 * nor may "Apache" appear in their name, without prior written
34 * permission of the Apache Software Foundation.
35 *
36 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47 * SUCH DAMAGE.
48 * ====================================================================
49 *
50 * This software consists of voluntary contributions made by many
51 * individuals on behalf of the Apache Software Foundation. For more
52 * information on the Apache Software Foundation, please see
53 * <http://www.apache.org/>.
54 */
55 package org.apache.axis.ime.internal.util;
56
57 /**
58 * A KeyedBuffer is a low level hybrid FIFO Queue and Keyed map
59 * Each MessageExchange implementation will create at least two
60 * KeyedBuffer's, one for messages being sent, and another for
61 * messages that have been received.
62 *
63 * KeyedBuffers differ from traditional FIFO Queues in that
64 * elements put in are keyed and can be taken out of order.
65 *
66 * Different implementations may allow for variations on
67 * how the KeyedBuffer model is implemented. For instance,
68 * the code will ship with a NonPersistentKeyedBuffer that
69 * will store all contained objects in memory. The fact that
70 * everything is stored in memory means that the buffer is not
71 * fault tolerant. If fault tolerance is required, then a
72 * Persistent KeyedBuffer must be created that persists the
73 * objects somehow.
74 *
75 * @author James M Snell (jasnell@us.ibm.com)
76 */
77 public interface KeyedBuffer {
78
79 /**
80 * Select, but do not remove the next message on the
81 * channel. If one does not exist, return null
82 */
83 public Object peek();
84
85 /**
86 * Select, but do not remove all messages on the
87 * channel. This method will not block.
88 */
89 public Object[] peekAll();
90
91 /**
92 * Put a message onto the channel
93 */
94 public void put(
95 Object key,
96 Object context);
97
98 /**
99 * Cancel a message that has been put on the channel.
100 * Unlike select(Object key), this method will not block
101 * and wait for a message with the specified key to be
102 * put onto the MessageChannel.
103 */
104 public Object cancel(
105 Object key);
106
107 /**
108 * Select and remove all of the messages currently in
109 * the channel (useful for bulk operations). This
110 * method will not block. It is also not guaranteed
111 * that the Channel will be empty once this operation
112 * returns (it is possible that another thread may
113 * put new MessageContexts into the channel before this
114 * operation completes)
115 */
116 public Object[] selectAll();
117
118 /**
119 * Select and remove the next message in the channel
120 * If a message is not available, wait indefinitely for one
121 */
122 public Object select()
123 throws InterruptedException;
124
125 /**
126 * Select and remove the next message in the channel
127 * If a message is not available, wait the specified amount
128 * of time for one
129 */
130 public Object select(
131 long timeout)
132 throws InterruptedException;
133
134 /**
135 * Select and remove a specific message in the channel
136 * If the message is not available, wait indefinitely
137 * for one to be available
138 */
139 public Object select(
140 Object key)
141 throws InterruptedException;
142
143 /**
144 * Select and remove a specific message in the channel
145 * If the message is not available, wait the specified
146 * amount of time for one
147 */
148 public Object select(
149 Object key,
150 long timeout)
151 throws InterruptedException;
152
153 /**
154 * Select and remove the next object in the buffer
155 * (does not wait for a message to be put into the buffer)
156 */
157 public Object get();
158
159 /**
160 * Select and remove the specified object in the buffer
161 * (does not wait for a message to be put into the buffer)
162 */
163 public Object get(Object key);
164
165 }