KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > axis > ime > internal > util > KeyedBuffer


1 /*
2  * Copyright 2001-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16 package org.apache.axis.ime.internal.util;
17
18 /**
19  * A KeyedBuffer is a low level hybrid FIFO Queue and Keyed map
20  * Each MessageExchange implementation will create at least two
21  * KeyedBuffer's, one for messages being sent, and another for
22  * messages that have been received.
23  *
24  * KeyedBuffers differ from traditional FIFO Queues in that
25  * elements put in are keyed and can be taken out of order.
26  *
27  * Different implementations may allow for variations on
28  * how the KeyedBuffer model is implemented. For instance,
29  * the code will ship with a NonPersistentKeyedBuffer that
30  * will store all contained objects in memory. The fact that
31  * everything is stored in memory means that the buffer is not
32  * fault tolerant. If fault tolerance is required, then a
33  * Persistent KeyedBuffer must be created that persists the
34  * objects somehow.
35  *
36  * @author James M Snell (jasnell@us.ibm.com)
37  */

38 public interface KeyedBuffer {
39
40     /**
41      * Select, but do not remove the next message on the
42      * channel. If one does not exist, return null
43      */

44     public Object JavaDoc peek();
45
46     /**
47      * Select, but do not remove all messages on the
48      * channel. This method will not block.
49      */

50     public Object JavaDoc[] peekAll();
51
52     /**
53      * Put a message onto the channel
54      */

55     public void put(
56             Object JavaDoc key,
57             Object JavaDoc context);
58
59     /**
60      * Cancel a message that has been put on the channel.
61      * Unlike select(Object key), this method will not block
62      * and wait for a message with the specified key to be
63      * put onto the MessageChannel.
64      */

65     public Object JavaDoc cancel(
66             Object JavaDoc key);
67
68     /**
69      * Select and remove all of the messages currently in
70      * the channel (useful for bulk operations). This
71      * method will not block. It is also not guaranteed
72      * that the Channel will be empty once this operation
73      * returns (it is possible that another thread may
74      * put new MessageContexts into the channel before this
75      * operation completes)
76      */

77     public Object JavaDoc[] selectAll();
78
79     /**
80      * Select and remove the next message in the channel
81      * If a message is not available, wait indefinitely for one
82      */

83     public Object JavaDoc select()
84             throws InterruptedException JavaDoc;
85
86     /**
87      * Select and remove the next message in the channel
88      * If a message is not available, wait the specified amount
89      * of time for one
90      */

91     public Object JavaDoc select(
92             long timeout)
93             throws InterruptedException JavaDoc;
94
95     /**
96      * Select and remove a specific message in the channel
97      * If the message is not available, wait indefinitely
98      * for one to be available
99      */

100     public Object JavaDoc select(
101             Object JavaDoc key)
102             throws InterruptedException JavaDoc;
103
104     /**
105      * Select and remove a specific message in the channel
106      * If the message is not available, wait the specified
107      * amount of time for one
108      */

109     public Object JavaDoc select(
110             Object JavaDoc key,
111             long timeout)
112             throws InterruptedException JavaDoc;
113     
114     /**
115      * Select and remove the next object in the buffer
116      * (does not wait for a message to be put into the buffer)
117      */

118     public Object JavaDoc get();
119
120     /**
121      * Select and remove the specified object in the buffer
122      * (does not wait for a message to be put into the buffer)
123      */

124     public Object JavaDoc get(Object JavaDoc key);
125     
126 }
127
Popular Tags