network/buffer/ManagedBuffer.java

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *    http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 package org.apache.spark.network.buffer;
0019
0020 import java.io.IOException;
0021 import java.io.InputStream;
0022 import java.nio.ByteBuffer;
0023
0024 /**
0025  * This interface provides an immutable view for data in the form of bytes. The implementation
0026  * should specify how the data is provided:
0027  *
0028  * - {@link FileSegmentManagedBuffer}: data backed by part of a file
0029  * - {@link NioManagedBuffer}: data backed by a NIO ByteBuffer
0030  * - {@link NettyManagedBuffer}: data backed by a Netty ByteBuf
0031  *
0032  * The concrete buffer implementation might be managed outside the JVM garbage collector.
0033  * For example, in the case of {@link NettyManagedBuffer}, the buffers are reference counted.
0034  * In that case, if the buffer is going to be passed around to a different thread, retain/release
0035  * should be called.
0036  */
0037 public abstract class ManagedBuffer {
0038
0039   /**
0040    * Number of bytes of the data. If this buffer will decrypt for all of the views into the data,
0041    * this is the size of the decrypted data.
0042    */
0043   public abstract long size();
0044
0045   /**
0046    * Exposes this buffer's data as an NIO ByteBuffer. Changing the position and limit of the
0047    * returned ByteBuffer should not affect the content of this buffer.
0048    */
0049   // TODO: Deprecate this, usage may require expensive memory mapping or allocation.
0050   public abstract ByteBuffer nioByteBuffer() throws IOException;
0051
0052   /**
0053    * Exposes this buffer's data as an InputStream. The underlying implementation does not
0054    * necessarily check for the length of bytes read, so the caller is responsible for making sure
0055    * it does not go over the limit.
0056    */
0057   public abstract InputStream createInputStream() throws IOException;
0058
0059   /**
0060    * Increment the reference count by one if applicable.
0061    */
0062   public abstract ManagedBuffer retain();
0063
0064   /**
0065    * If applicable, decrement the reference count by one and deallocates the buffer if the
0066    * reference count reaches zero.
0067    */
0068   public abstract ManagedBuffer release();
0069
0070   /**
0071    * Convert the buffer into an Netty object, used to write the data out. The return value is either
0072    * a {@link io.netty.buffer.ByteBuf} or a {@link io.netty.channel.FileRegion}.
0073    *
0074    * If this method returns a ByteBuf, then that buffer's reference count will be incremented and
0075    * the caller will be responsible for releasing this new reference.
0076    */
0077   public abstract Object convertToNetty() throws IOException;
0078 }