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 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 }