third-party/atomix/storage/src/main/java/io/atomix/storage/buffer/Bytes.java

   1 /*
   2  * Copyright 2015-present Open Networking Foundation
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * 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,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 package io.atomix.storage.buffer;
  17
  18 import java.nio.ByteOrder;
  19
  20 /**
  21  * Common interface for interacting with a memory or disk based array of bytes.
  22  *
  23  * @author <a href="http://github.com/kuujo">Jordan Halterman</a>
  24  */
  25 public interface Bytes extends BytesInput<Bytes>, BytesOutput<Bytes>, AutoCloseable {
  26   int BYTE = 1;
  27   int BOOLEAN = 1;
  28   int CHARACTER = 2;
  29   int SHORT = 2;
  30   int MEDIUM = 3;
  31   int INTEGER = 4;
  32   int LONG = 8;
  33   int FLOAT = 4;
  34   int DOUBLE = 8;
  35
  36   /**
  37    * Returns whether the bytes has an array.
  38    *
  39    * @return Whether the bytes has an underlying array.
  40    */
  41   default boolean hasArray() {
  42     return false;
  43   }
  44
  45   /**
  46    * Returns the underlying byte array.
  47    *
  48    * @return the underlying byte array
  49    * @throws UnsupportedOperationException if a heap array is not supported
  50    */
  51   default byte[] array() {
  52     throw new UnsupportedOperationException();
  53   }
  54
  55   /**
  56    * Returns the count of the bytes.
  57    *
  58    * @return The count of the bytes.
  59    */
  60   int size();
  61
  62   /**
  63    * Resizes the bytes.
  64    * <p>
  65    * When the bytes are resized, underlying memory addresses in copies of this instance may no longer be valid. Additionally,
  66    * if the {@code newSize} is smaller than the current {@code count} then some data may be lost during the resize. Use
  67    * with caution.
  68    *
  69    * @param newSize The count to which to resize this instance.
  70    * @return The resized bytes.
  71    */
  72   Bytes resize(int newSize);
  73
  74   /**
  75    * Returns the byte order.
  76    * <p>
  77    * For consistency with {@link java.nio.ByteBuffer}, all bytes implementations are initially in {@link ByteOrder#BIG_ENDIAN} order.
  78    *
  79    * @return The byte order.
  80    */
  81   ByteOrder order();
  82
  83   /**
  84    * Sets the byte order, returning a new swapped {@link Bytes} instance.
  85    * <p>
  86    * By default, all bytes are read and written in {@link ByteOrder#BIG_ENDIAN} order. This provides complete
  87    * consistency with {@link java.nio.ByteBuffer}. To flip bytes to {@link ByteOrder#LITTLE_ENDIAN} order, this
  88    * {@code Bytes} instance is decorated by a {@link SwappedBytes} instance which will reverse
  89    * read and written bytes using, e.g. {@link Integer#reverseBytes(int)}.
  90    *
  91    * @param order The byte order.
  92    * @return The updated bytes.
  93    * @throws NullPointerException If the {@code order} is {@code null}
  94    */
  95   Bytes order(ByteOrder order);
  96
  97   /**
  98    * Returns a boolean value indicating whether the bytes are direct.
  99    *
 100    * @return Indicates whether the bytes are direct.
 101    */
 102   boolean isDirect();
 103
 104   /**
 105    * Returns a boolean value indicating whether the bytes are backed by a file.
 106    *
 107    * @return Indicates whether the bytes are backed by a file.
 108    */
 109   boolean isFile();
 110
 111   @Override
 112   void close();
 113
 114 }