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   peek();
45  
46      /**
47       * Select, but do not remove all messages on the 
48       * channel.  This method will not block.
49       */
50      public Object  [] peekAll();
51  
52      /**
53       * Put a message onto the channel
54       */
55      public void put(
56              Object   key,
57              Object   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   cancel(
66              Object   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  [] 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   select()
84              throws InterruptedException  ;
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   select(
92              long timeout)
93              throws InterruptedException  ;
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   select(
101             Object   key)
102             throws InterruptedException  ;
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   select(
110             Object   key,
111             long timeout)
112             throws InterruptedException  ;
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   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   get(Object   key);
125     
126 }
127
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags