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 org.jboss.netty.buffer;
17
18 import java.nio.ByteBuffer;
19 import java.nio.ByteOrder;
20
21 /**
22 * A factory that creates or pools {@link ChannelBuffer}s.
23 */
24 public interface ChannelBufferFactory {
25
26 /**
27 * Returns a {@link ChannelBuffer} with the specified {@code capacity}.
28 * This method is identical to {@code getBuffer(getDefaultOrder(), capacity)}.
29 *
30 * @param capacity the capacity of the returned {@link ChannelBuffer}
31 * @return a {@link ChannelBuffer} with the specified {@code capacity},
32 * whose {@code readerIndex} and {@code writerIndex} are {@code 0}
33 */
34 ChannelBuffer getBuffer(int capacity);
35
36 /**
37 * Returns a {@link ChannelBuffer} with the specified {@code endianness}
38 * and {@code capacity}.
39 *
40 * @param endianness the endianness of the returned {@link ChannelBuffer}
41 * @param capacity the capacity of the returned {@link ChannelBuffer}
42 * @return a {@link ChannelBuffer} with the specified {@code endianness} and
43 * {@code capacity}, whose {@code readerIndex} and {@code writerIndex}
44 * are {@code 0}
45 */
46 ChannelBuffer getBuffer(ByteOrder endianness, int capacity);
47
48 /**
49 * Returns a {@link ChannelBuffer} whose content is equal to the sub-region
50 * of the specified {@code array}. Depending on the factory implementation,
51 * the returned buffer could wrap the {@code array} or create a new copy of
52 * the {@code array}.
53 * This method is identical to {@code getBuffer(getDefaultOrder(), array, offset, length)}.
54 *
55 * @param array the byte array
56 * @param offset the offset of the byte array
57 * @param length the length of the byte array
58 *
59 * @return a {@link ChannelBuffer} with the specified content,
60 * whose {@code readerIndex} and {@code writerIndex}
61 * are {@code 0} and {@code (length - offset)} respectively
62 */
63 ChannelBuffer getBuffer(byte[] array, int offset, int length);
64
65 /**
66 * Returns a {@link ChannelBuffer} whose content is equal to the sub-region
67 * of the specified {@code array}. Depending on the factory implementation,
68 * the returned buffer could wrap the {@code array} or create a new copy of
69 * the {@code array}.
70 *
71 * @param endianness the endianness of the returned {@link ChannelBuffer}
72 * @param array the byte array
73 * @param offset the offset of the byte array
74 * @param length the length of the byte array
75 *
76 * @return a {@link ChannelBuffer} with the specified content,
77 * whose {@code readerIndex} and {@code writerIndex}
78 * are {@code 0} and {@code (length - offset)} respectively
79 */
80 ChannelBuffer getBuffer(ByteOrder endianness, byte[] array, int offset, int length);
81
82 /**
83 * Returns a {@link ChannelBuffer} whose content is equal to the sub-region
84 * of the specified {@code nioBuffer}. Depending on the factory
85 * implementation, the returned buffer could wrap the {@code nioBuffer} or
86 * create a new copy of the {@code nioBuffer}.
87 *
88 * @param nioBuffer the NIO {@link ByteBuffer}
89 *
90 * @return a {@link ChannelBuffer} with the specified content,
91 * whose {@code readerIndex} and {@code writerIndex}
92 * are {@code 0} and {@code nioBuffer.remaining()} respectively
93 */
94 ChannelBuffer getBuffer(ByteBuffer nioBuffer);
95
96 /**
97 * Returns the default endianness of the {@link ChannelBuffer} which is
98 * returned by {@link #getBuffer(int)}.
99 *
100 * @return the default endianness of the {@link ChannelBuffer} which is
101 * returned by {@link #getBuffer(int)}
102 */
103 ByteOrder getDefaultOrder();
104 }