1 /*
   2  * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package java.util.zip;
  26 
  27 import java.nio.ByteBuffer;
  28 
  29 /**
  30  * An interface representing a data checksum.
  31  *
  32  * @author David Connelly
  33  */
  34 public interface Checksum {
  35 
  36     /**
  37      * Updates the current checksum with the specified byte.
  38      *
  39      * @param b the byte to update the checksum with
  40      */
  41     public void update(int b);
  42 
  43     /**
  44      * Updates the current checksum with the specified array of bytes.
  45      *
  46      * @implSpec This default implementation is equal to calling
  47      * {@code update(b, 0, b.length)}.
  48      *
  49      * @param b the array of bytes to update the checksum with
  50      *
  51      * @throws NullPointerException
  52      *         if {@code b} is {@code null}
  53      *
  54      * @since 9
  55      */
  56     default public void update(byte[] b) {
  57         update(b, 0, b.length);
  58     }
  59 
  60     /**
  61      * Updates the current checksum with the specified array of bytes.
  62      *
  63      * @param b the byte array to update the checksum with
  64      * @param off the start offset of the data
  65      * @param len the number of bytes to use for the update
  66      */
  67     public void update(byte[] b, int off, int len);
  68 
  69     /**
  70      * Updates the current checksum with the bytes from the specified buffer.
  71      *
  72      * The checksum is updated with the remaining bytes in the buffer, starting
  73      * at the buffer's position. Upon return, the buffer's position will be
  74      * updated to its limit; its limit will not have been changed.
  75      *
  76      * @apiNote For best performance with DirectByteBuffer and other ByteBuffer
  77      * implementations without a backing array implementers of this interface
  78      * should override this method.
  79      *
  80      * @implSpec The default implementation has the following behavior.<br>
  81      * For ByteBuffers backed by an accessible byte array.
  82      * <pre>{@code
  83      * update(buffer.array(),
  84      *        buffer.position() + buffer.arrayOffset(),
  85      *        buffer.remaining());
  86      * }</pre>
  87      * For ByteBuffers not backed by an accessible byte array.
  88      * <pre>{@code
  89      * byte[] b = new byte[Math.min(buffer.remaining(), 4096)];
  90      * while (buffer.hasRemaining()) {
  91      *     int length = Math.min(buffer.remaining(), b.length);
  92      *     buffer.get(b, 0, length);
  93      *     update(b, 0, length);
  94      * }
  95      * }</pre>
  96      *
  97      * @param buffer the ByteBuffer to update the checksum with
  98      *
  99      * @throws NullPointerException
 100      *         if {@code buffer} is {@code null}
 101      *
 102      * @since 9
 103      */
 104     default public void update(ByteBuffer buffer) {
 105         int pos = buffer.position();
 106         int limit = buffer.limit();
 107         assert (pos <= limit);
 108         int rem = limit - pos;
 109         if (rem <= 0) {
 110             return;
 111         }
 112         if (buffer.hasArray()) {
 113             update(buffer.array(), pos + buffer.arrayOffset(), rem);
 114         } else {
 115             byte[] b = new byte[Math.min(buffer.remaining(), 4096)];
 116             while (buffer.hasRemaining()) {
 117                 int length = Math.min(buffer.remaining(), b.length);
 118                 buffer.get(b, 0, length);
 119                 update(b, 0, length);
 120             }
 121         }
 122         buffer.position(limit);
 123     }
 124 
 125     /**
 126      * Returns the current checksum value.
 127      *
 128      * @return the current checksum value
 129      */
 130     public long getValue();
 131 
 132     /**
 133      * Resets the checksum to its initial value.
 134      */
 135     public void reset();
 136 }