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 */
25package java.util.zip;
26
27import java.nio.ByteBuffer;
28
29/**
30 * An interface representing a data checksum.
31 *
32 * @author David Connelly
33 * @since 1.1
34 */
35public interface Checksum {
36
37    /**
38     * Updates the current checksum with the specified byte.
39     *
40     * @param b the byte to update the checksum with
41     */
42    public void update(int b);
43
44    /**
45     * Updates the current checksum with the specified array of bytes.
46     *
47     * @implSpec This default implementation is equal to calling
48     * {@code update(b, 0, b.length)}.
49     *
50     * @param b the array of bytes to update the checksum with
51     *
52     * @throws NullPointerException
53     *         if {@code b} is {@code null}
54     *
55     * @since 9
56     */
57    default public void update(byte[] b) {
58        update(b, 0, b.length);
59    }
60
61    /**
62     * Updates the current checksum with the specified array of bytes.
63     *
64     * @param b the byte array to update the checksum with
65     * @param off the start offset of the data
66     * @param len the number of bytes to use for the update
67     */
68    public void update(byte[] b, int off, int len);
69
70    /**
71     * Updates the current checksum with the bytes from the specified buffer.
72     *
73     * The checksum is updated with the remaining bytes in the buffer, starting
74     * at the buffer's position. Upon return, the buffer's position will be
75     * updated to its limit; its limit will not have been changed.
76     *
77     * @apiNote For best performance with DirectByteBuffer and other ByteBuffer
78     * implementations without a backing array implementers of this interface
79     * should override this method.
80     *
81     * @implSpec The default implementation has the following behavior.<br>
82     * For ByteBuffers backed by an accessible byte array.
83     * <pre>{@code
84     * update(buffer.array(),
85     *        buffer.position() + buffer.arrayOffset(),
86     *        buffer.remaining());
87     * }</pre>
88     * For ByteBuffers not backed by an accessible byte array.
89     * <pre>{@code
90     * byte[] b = new byte[Math.min(buffer.remaining(), 4096)];
91     * while (buffer.hasRemaining()) {
92     *     int length = Math.min(buffer.remaining(), b.length);
93     *     buffer.get(b, 0, length);
94     *     update(b, 0, length);
95     * }
96     * }</pre>
97     *
98     * @param buffer the ByteBuffer to update the checksum with
99     *
100     * @throws NullPointerException
101     *         if {@code buffer} is {@code null}
102     *
103     * @since 9
104     */
105    default public void update(ByteBuffer buffer) {
106        int pos = buffer.position();
107        int limit = buffer.limit();
108        assert (pos <= limit);
109        int rem = limit - pos;
110        if (rem <= 0) {
111            return;
112        }
113        if (buffer.hasArray()) {
114            update(buffer.array(), pos + buffer.arrayOffset(), rem);
115        } else {
116            byte[] b = new byte[Math.min(buffer.remaining(), 4096)];
117            while (buffer.hasRemaining()) {
118                int length = Math.min(buffer.remaining(), b.length);
119                buffer.get(b, 0, length);
120                update(b, 0, length);
121            }
122        }
123        buffer.position(limit);
124    }
125
126    /**
127     * Returns the current checksum value.
128     *
129     * @return the current checksum value
130     */
131    public long getValue();
132
133    /**
134     * Resets the checksum to its initial value.
135     */
136    public void reset();
137}
138