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 }