1 /*
2 * Copyright 2009 Red Hat, Inc.
3 *
4 * Red Hat licenses this file to you under the Apache License, version 2.0
5 * (the "License"); you may not use this file except in compliance with the
6 * 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 * @author <a href="http://www.jboss.org/netty/">The Netty Project</a>
25 * @author <a href="http://gleamynode.net/">Trustin Lee</a>
26 * @version $Rev: 2080 $, $Date: 2010-01-26 18:04:19 +0900 (Tue, 26 Jan 2010) $
27 */
28 public interface ChannelBufferFactory {
29
30 /**
31 * Returns a {@link ChannelBuffer} with the specified {@code capacity}.
32 * This method is identical to {@code getBuffer(getDefaultOrder(), capacity)}.
33 *
34 * @param capacity the capacity of the returned {@link ChannelBuffer}
35 * @return a {@link ChannelBuffer} with the specified {@code capacity},
36 * whose {@code readerIndex} and {@code writerIndex} are {@code 0}
37 */
38 ChannelBuffer getBuffer(int capacity);
39
40 /**
41 * Returns a {@link ChannelBuffer} with the specified {@code endianness}
42 * and {@code capacity}.
43 *
44 * @param endianness the endianness of the returned {@link ChannelBuffer}
45 * @param capacity the capacity of the returned {@link ChannelBuffer}
46 * @return a {@link ChannelBuffer} with the specified {@code endianness} and
47 * {@code capacity}, whose {@code readerIndex} and {@code writerIndex}
48 * are {@code 0}
49 */
50 ChannelBuffer getBuffer(ByteOrder endianness, int capacity);
51
52 /**
53 * Returns a {@link ChannelBuffer} whose content is equal to the sub-region
54 * of the specified {@code array}. Depending on the factory implementation,
55 * the returned buffer could wrap the {@code array} or create a new copy of
56 * the {@code array}.
57 * This method is identical to {@code getBuffer(getDefaultOrder(), array, offset, length)}.
58 *
59 * @param array the byte array
60 * @param offset the offset of the byte array
61 * @param length the length of the byte array
62 *
63 * @return a {@link ChannelBuffer} with the specified content,
64 * whose {@code readerIndex} and {@code writerIndex}
65 * are {@code 0} and {@code (length - offset)} respectively
66 */
67 ChannelBuffer getBuffer(byte[] array, int offset, int length);
68
69 /**
70 * Returns a {@link ChannelBuffer} whose content is equal to the sub-region
71 * of the specified {@code array}. Depending on the factory implementation,
72 * the returned buffer could wrap the {@code array} or create a new copy of
73 * the {@code array}.
74 *
75 * @param endianness the endianness of the returned {@link ChannelBuffer}
76 * @param array the byte array
77 * @param offset the offset of the byte array
78 * @param length the length of the byte array
79 *
80 * @return a {@link ChannelBuffer} with the specified content,
81 * whose {@code readerIndex} and {@code writerIndex}
82 * are {@code 0} and {@code (length - offset)} respectively
83 */
84 ChannelBuffer getBuffer(ByteOrder endianness, byte[] array, int offset, int length);
85
86 /**
87 * Returns a {@link ChannelBuffer} whose content is equal to the sub-region
88 * of the specified {@code nioBuffer}. Depending on the factory
89 * implementation, the returned buffer could wrap the {@code nioBuffer} or
90 * create a new copy of the {@code nioBuffer}.
91 *
92 * @param nioBuffer the NIO {@link ByteBuffer}
93 *
94 * @return a {@link ChannelBuffer} with the specified content,
95 * whose {@code readerIndex} and {@code writerIndex}
96 * are {@code 0} and {@code nioBuffer.remaining()} respectively
97 */
98 ChannelBuffer getBuffer(ByteBuffer nioBuffer);
99
100 /**
101 * Returns the default endianness of the {@link ChannelBuffer} which is
102 * returned by {@link #getBuffer(int)}.
103 *
104 * @return the default endianness of the {@link ChannelBuffer} which is
105 * returned by {@link #getBuffer(int)}
106 */
107 ByteOrder getDefaultOrder();
108 }