View Javadoc
1   /*
2    * Copyright 2012 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. 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, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  package io.netty.channel;
17  
18  import io.netty.buffer.ByteBuf;
19  import io.netty.buffer.ByteBufAllocator;
20  import io.netty.util.UncheckedBooleanSupplier;
21  import io.netty.util.internal.UnstableApi;
22  
23  import static io.netty.util.internal.ObjectUtil.checkNotNull;
24  
25  /**
26   * Allocates a new receive buffer whose capacity is probably large enough to read all inbound data and small enough
27   * not to waste its space.
28   */
29  public interface RecvByteBufAllocator {
30      /**
31       * Creates a new handle.  The handle provides the actual operations and keeps the internal information which is
32       * required for predicting an optimal buffer capacity.
33       */
34      Handle newHandle();
35  
36      /**
37       * @deprecated Use {@link ExtendedHandle}.
38       */
39      @Deprecated
40      interface Handle {
41          /**
42           * Creates a new receive buffer whose capacity is probably large enough to read all inbound data and small
43           * enough not to waste its space.
44           */
45          ByteBuf allocate(ByteBufAllocator alloc);
46  
47          /**
48           * Similar to {@link #allocate(ByteBufAllocator)} except that it does not allocate anything but just tells the
49           * capacity.
50           */
51          int guess();
52  
53          /**
54           * Reset any counters that have accumulated and recommend how many messages/bytes should be read for the next
55           * read loop.
56           * <p>
57           * This may be used by {@link #continueReading()} to determine if the read operation should complete.
58           * </p>
59           * This is only ever a hint and may be ignored by the implementation.
60           * @param config The channel configuration which may impact this object's behavior.
61           */
62          void reset(ChannelConfig config);
63  
64          /**
65           * Increment the number of messages that have been read for the current read loop.
66           * @param numMessages The amount to increment by.
67           */
68          void incMessagesRead(int numMessages);
69  
70          /**
71           * Set the bytes that have been read for the last read operation.
72           * This may be used to increment the number of bytes that have been read.
73           * @param bytes The number of bytes from the previous read operation. This may be negative if an read error
74           * occurs. If a negative value is seen it is expected to be return on the next call to
75           * {@link #lastBytesRead()}. A negative value will signal a termination condition enforced externally
76           * to this class and is not required to be enforced in {@link #continueReading()}.
77           */
78          void lastBytesRead(int bytes);
79  
80          /**
81           * Get the amount of bytes for the previous read operation.
82           * @return The amount of bytes for the previous read operation.
83           */
84          int lastBytesRead();
85  
86          /**
87           * Set how many bytes the read operation will (or did) attempt to read.
88           * @param bytes How many bytes the read operation will (or did) attempt to read.
89           */
90          void attemptedBytesRead(int bytes);
91  
92          /**
93           * Get how many bytes the read operation will (or did) attempt to read.
94           * @return How many bytes the read operation will (or did) attempt to read.
95           */
96          int attemptedBytesRead();
97  
98          /**
99           * Determine if the current read loop should should continue.
100          * @return {@code true} if the read loop should continue reading. {@code false} if the read loop is complete.
101          */
102         boolean continueReading();
103 
104         /**
105          * The read has completed.
106          */
107         void readComplete();
108     }
109 
110     @SuppressWarnings("deprecation")
111     @UnstableApi
112     interface ExtendedHandle extends Handle {
113         /**
114          * Same as {@link Handle#continueReading()} except "more data" is determined by the supplier parameter.
115          * @param maybeMoreDataSupplier A supplier that determines if there maybe more data to read.
116          */
117         boolean continueReading(UncheckedBooleanSupplier maybeMoreDataSupplier);
118     }
119 
120     /**
121      * A {@link Handle} which delegates all call to some other {@link Handle}.
122      */
123     class DelegatingHandle implements Handle {
124         private final Handle delegate;
125 
126         public DelegatingHandle(Handle delegate) {
127             this.delegate = checkNotNull(delegate, "delegate");
128         }
129 
130         /**
131          * Get the {@link Handle} which all methods will be delegated to.
132          * @return the {@link Handle} which all methods will be delegated to.
133          */
134         protected final Handle delegate() {
135             return delegate;
136         }
137 
138         @Override
139         public ByteBuf allocate(ByteBufAllocator alloc) {
140             return delegate.allocate(alloc);
141         }
142 
143         @Override
144         public int guess() {
145             return delegate.guess();
146         }
147 
148         @Override
149         public void reset(ChannelConfig config) {
150             delegate.reset(config);
151         }
152 
153         @Override
154         public void incMessagesRead(int numMessages) {
155             delegate.incMessagesRead(numMessages);
156         }
157 
158         @Override
159         public void lastBytesRead(int bytes) {
160             delegate.lastBytesRead(bytes);
161         }
162 
163         @Override
164         public int lastBytesRead() {
165             return delegate.lastBytesRead();
166         }
167 
168         @Override
169         public boolean continueReading() {
170             return delegate.continueReading();
171         }
172 
173         @Override
174         public int attemptedBytesRead() {
175             return delegate.attemptedBytesRead();
176         }
177 
178         @Override
179         public void attemptedBytesRead(int bytes) {
180             delegate.attemptedBytesRead(bytes);
181         }
182 
183         @Override
184         public void readComplete() {
185             delegate.readComplete();
186         }
187     }
188 }