001/*
002 * Copyright 2002-2018 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.core.io.buffer;
018
019import java.nio.ByteBuffer;
020import java.util.List;
021
022/**
023 * A factory for {@link DataBuffer DataBuffers}, allowing for allocation and
024 * wrapping of data buffers.
025 *
026 * @author Arjen Poutsma
027 * @since 5.0
028 * @see DataBuffer
029 */
030public interface DataBufferFactory {
031
032        /**
033         * Allocate a data buffer of a default initial capacity. Depending on the
034         * underlying implementation and its configuration, this will be heap-based
035         * or direct buffer.
036         * @return the allocated buffer
037         */
038        DataBuffer allocateBuffer();
039
040        /**
041         * Allocate a data buffer of the given initial capacity. Depending on the
042         * underlying implementation and its configuration, this will be heap-based
043         * or direct buffer.
044         * @param initialCapacity the initial capacity of the buffer to allocate
045         * @return the allocated buffer
046         */
047        DataBuffer allocateBuffer(int initialCapacity);
048
049        /**
050         * Wrap the given {@link ByteBuffer} in a {@code DataBuffer}. Unlike
051         * {@linkplain #allocateBuffer(int) allocating}, wrapping does not use new memory.
052         * @param byteBuffer the NIO byte buffer to wrap
053         * @return the wrapped buffer
054         */
055        DataBuffer wrap(ByteBuffer byteBuffer);
056
057        /**
058         * Wrap the given {@code byte} array in a {@code DataBuffer}. Unlike
059         * {@linkplain #allocateBuffer(int) allocating}, wrapping does not use new memory.
060         * @param bytes the byte array to wrap
061         * @return the wrapped buffer
062         */
063        DataBuffer wrap(byte[] bytes);
064
065        /**
066         * Return a new {@code DataBuffer} composed of the {@code dataBuffers} elements joined together.
067         * Depending on the implementation, the returned buffer may be a single buffer containing all
068         * data of the provided buffers, or it may be a true composite that contains references to the
069         * buffers.
070         * <p>Note that the given data buffers do <strong>not</strong> have to be released, as they are
071         * released as part of the returned composite.
072         * @param dataBuffers the data buffers to be composed
073         * @return a buffer that is composed from the {@code dataBuffers} argument
074         * @since 5.0.3
075         */
076        DataBuffer join(List<? extends DataBuffer> dataBuffers);
077
078}