1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/emul/compact/src/main/java/java/io/BufferedOutputStream.java Wed Feb 06 15:10:22 2013 +0100
1.3 @@ -0,0 +1,143 @@
1.4 +/*
1.5 + * Copyright (c) 1994, 2003, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package java.io;
1.30 +
1.31 +/**
1.32 + * The class implements a buffered output stream. By setting up such
1.33 + * an output stream, an application can write bytes to the underlying
1.34 + * output stream without necessarily causing a call to the underlying
1.35 + * system for each byte written.
1.36 + *
1.37 + * @author Arthur van Hoff
1.38 + * @since JDK1.0
1.39 + */
1.40 +public
1.41 +class BufferedOutputStream extends FilterOutputStream {
1.42 + /**
1.43 + * The internal buffer where data is stored.
1.44 + */
1.45 + protected byte buf[];
1.46 +
1.47 + /**
1.48 + * The number of valid bytes in the buffer. This value is always
1.49 + * in the range <tt>0</tt> through <tt>buf.length</tt>; elements
1.50 + * <tt>buf[0]</tt> through <tt>buf[count-1]</tt> contain valid
1.51 + * byte data.
1.52 + */
1.53 + protected int count;
1.54 +
1.55 + /**
1.56 + * Creates a new buffered output stream to write data to the
1.57 + * specified underlying output stream.
1.58 + *
1.59 + * @param out the underlying output stream.
1.60 + */
1.61 + public BufferedOutputStream(OutputStream out) {
1.62 + this(out, 8192);
1.63 + }
1.64 +
1.65 + /**
1.66 + * Creates a new buffered output stream to write data to the
1.67 + * specified underlying output stream with the specified buffer
1.68 + * size.
1.69 + *
1.70 + * @param out the underlying output stream.
1.71 + * @param size the buffer size.
1.72 + * @exception IllegalArgumentException if size <= 0.
1.73 + */
1.74 + public BufferedOutputStream(OutputStream out, int size) {
1.75 + super(out);
1.76 + if (size <= 0) {
1.77 + throw new IllegalArgumentException("Buffer size <= 0");
1.78 + }
1.79 + buf = new byte[size];
1.80 + }
1.81 +
1.82 + /** Flush the internal buffer */
1.83 + private void flushBuffer() throws IOException {
1.84 + if (count > 0) {
1.85 + out.write(buf, 0, count);
1.86 + count = 0;
1.87 + }
1.88 + }
1.89 +
1.90 + /**
1.91 + * Writes the specified byte to this buffered output stream.
1.92 + *
1.93 + * @param b the byte to be written.
1.94 + * @exception IOException if an I/O error occurs.
1.95 + */
1.96 + public synchronized void write(int b) throws IOException {
1.97 + if (count >= buf.length) {
1.98 + flushBuffer();
1.99 + }
1.100 + buf[count++] = (byte)b;
1.101 + }
1.102 +
1.103 + /**
1.104 + * Writes <code>len</code> bytes from the specified byte array
1.105 + * starting at offset <code>off</code> to this buffered output stream.
1.106 + *
1.107 + * <p> Ordinarily this method stores bytes from the given array into this
1.108 + * stream's buffer, flushing the buffer to the underlying output stream as
1.109 + * needed. If the requested length is at least as large as this stream's
1.110 + * buffer, however, then this method will flush the buffer and write the
1.111 + * bytes directly to the underlying output stream. Thus redundant
1.112 + * <code>BufferedOutputStream</code>s will not copy data unnecessarily.
1.113 + *
1.114 + * @param b the data.
1.115 + * @param off the start offset in the data.
1.116 + * @param len the number of bytes to write.
1.117 + * @exception IOException if an I/O error occurs.
1.118 + */
1.119 + public synchronized void write(byte b[], int off, int len) throws IOException {
1.120 + if (len >= buf.length) {
1.121 + /* If the request length exceeds the size of the output buffer,
1.122 + flush the output buffer and then write the data directly.
1.123 + In this way buffered streams will cascade harmlessly. */
1.124 + flushBuffer();
1.125 + out.write(b, off, len);
1.126 + return;
1.127 + }
1.128 + if (len > buf.length - count) {
1.129 + flushBuffer();
1.130 + }
1.131 + System.arraycopy(b, off, buf, count, len);
1.132 + count += len;
1.133 + }
1.134 +
1.135 + /**
1.136 + * Flushes this buffered output stream. This forces any buffered
1.137 + * output bytes to be written out to the underlying output stream.
1.138 + *
1.139 + * @exception IOException if an I/O error occurs.
1.140 + * @see java.io.FilterOutputStream#out
1.141 + */
1.142 + public synchronized void flush() throws IOException {
1.143 + flushBuffer();
1.144 + out.flush();
1.145 + }
1.146 +}
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/emul/compact/src/main/java/java/io/ByteArrayOutputStream.java Wed Feb 06 15:10:22 2013 +0100
2.3 @@ -0,0 +1,272 @@
2.4 +/*
2.5 + * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved.
2.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
2.7 + *
2.8 + * This code is free software; you can redistribute it and/or modify it
2.9 + * under the terms of the GNU General Public License version 2 only, as
2.10 + * published by the Free Software Foundation. Oracle designates this
2.11 + * particular file as subject to the "Classpath" exception as provided
2.12 + * by Oracle in the LICENSE file that accompanied this code.
2.13 + *
2.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
2.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
2.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
2.17 + * version 2 for more details (a copy is included in the LICENSE file that
2.18 + * accompanied this code).
2.19 + *
2.20 + * You should have received a copy of the GNU General Public License version
2.21 + * 2 along with this work; if not, write to the Free Software Foundation,
2.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
2.23 + *
2.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2.25 + * or visit www.oracle.com if you need additional information or have any
2.26 + * questions.
2.27 + */
2.28 +
2.29 +package java.io;
2.30 +
2.31 +import java.util.Arrays;
2.32 +
2.33 +/**
2.34 + * This class implements an output stream in which the data is
2.35 + * written into a byte array. The buffer automatically grows as data
2.36 + * is written to it.
2.37 + * The data can be retrieved using <code>toByteArray()</code> and
2.38 + * <code>toString()</code>.
2.39 + * <p>
2.40 + * Closing a <tt>ByteArrayOutputStream</tt> has no effect. The methods in
2.41 + * this class can be called after the stream has been closed without
2.42 + * generating an <tt>IOException</tt>.
2.43 + *
2.44 + * @author Arthur van Hoff
2.45 + * @since JDK1.0
2.46 + */
2.47 +
2.48 +public class ByteArrayOutputStream extends OutputStream {
2.49 +
2.50 + /**
2.51 + * The buffer where data is stored.
2.52 + */
2.53 + protected byte buf[];
2.54 +
2.55 + /**
2.56 + * The number of valid bytes in the buffer.
2.57 + */
2.58 + protected int count;
2.59 +
2.60 + /**
2.61 + * Creates a new byte array output stream. The buffer capacity is
2.62 + * initially 32 bytes, though its size increases if necessary.
2.63 + */
2.64 + public ByteArrayOutputStream() {
2.65 + this(32);
2.66 + }
2.67 +
2.68 + /**
2.69 + * Creates a new byte array output stream, with a buffer capacity of
2.70 + * the specified size, in bytes.
2.71 + *
2.72 + * @param size the initial size.
2.73 + * @exception IllegalArgumentException if size is negative.
2.74 + */
2.75 + public ByteArrayOutputStream(int size) {
2.76 + if (size < 0) {
2.77 + throw new IllegalArgumentException("Negative initial size: "
2.78 + + size);
2.79 + }
2.80 + buf = new byte[size];
2.81 + }
2.82 +
2.83 + /**
2.84 + * Increases the capacity if necessary to ensure that it can hold
2.85 + * at least the number of elements specified by the minimum
2.86 + * capacity argument.
2.87 + *
2.88 + * @param minCapacity the desired minimum capacity
2.89 + * @throws OutOfMemoryError if {@code minCapacity < 0}. This is
2.90 + * interpreted as a request for the unsatisfiably large capacity
2.91 + * {@code (long) Integer.MAX_VALUE + (minCapacity - Integer.MAX_VALUE)}.
2.92 + */
2.93 + private void ensureCapacity(int minCapacity) {
2.94 + // overflow-conscious code
2.95 + if (minCapacity - buf.length > 0)
2.96 + grow(minCapacity);
2.97 + }
2.98 +
2.99 + /**
2.100 + * Increases the capacity to ensure that it can hold at least the
2.101 + * number of elements specified by the minimum capacity argument.
2.102 + *
2.103 + * @param minCapacity the desired minimum capacity
2.104 + */
2.105 + private void grow(int minCapacity) {
2.106 + // overflow-conscious code
2.107 + int oldCapacity = buf.length;
2.108 + int newCapacity = oldCapacity << 1;
2.109 + if (newCapacity - minCapacity < 0)
2.110 + newCapacity = minCapacity;
2.111 + if (newCapacity < 0) {
2.112 + if (minCapacity < 0) // overflow
2.113 + throw new OutOfMemoryError();
2.114 + newCapacity = Integer.MAX_VALUE;
2.115 + }
2.116 + buf = Arrays.copyOf(buf, newCapacity);
2.117 + }
2.118 +
2.119 + /**
2.120 + * Writes the specified byte to this byte array output stream.
2.121 + *
2.122 + * @param b the byte to be written.
2.123 + */
2.124 + public synchronized void write(int b) {
2.125 + ensureCapacity(count + 1);
2.126 + buf[count] = (byte) b;
2.127 + count += 1;
2.128 + }
2.129 +
2.130 + /**
2.131 + * Writes <code>len</code> bytes from the specified byte array
2.132 + * starting at offset <code>off</code> to this byte array output stream.
2.133 + *
2.134 + * @param b the data.
2.135 + * @param off the start offset in the data.
2.136 + * @param len the number of bytes to write.
2.137 + */
2.138 + public synchronized void write(byte b[], int off, int len) {
2.139 + if ((off < 0) || (off > b.length) || (len < 0) ||
2.140 + ((off + len) - b.length > 0)) {
2.141 + throw new IndexOutOfBoundsException();
2.142 + }
2.143 + ensureCapacity(count + len);
2.144 + System.arraycopy(b, off, buf, count, len);
2.145 + count += len;
2.146 + }
2.147 +
2.148 + /**
2.149 + * Writes the complete contents of this byte array output stream to
2.150 + * the specified output stream argument, as if by calling the output
2.151 + * stream's write method using <code>out.write(buf, 0, count)</code>.
2.152 + *
2.153 + * @param out the output stream to which to write the data.
2.154 + * @exception IOException if an I/O error occurs.
2.155 + */
2.156 + public synchronized void writeTo(OutputStream out) throws IOException {
2.157 + out.write(buf, 0, count);
2.158 + }
2.159 +
2.160 + /**
2.161 + * Resets the <code>count</code> field of this byte array output
2.162 + * stream to zero, so that all currently accumulated output in the
2.163 + * output stream is discarded. The output stream can be used again,
2.164 + * reusing the already allocated buffer space.
2.165 + *
2.166 + * @see java.io.ByteArrayInputStream#count
2.167 + */
2.168 + public synchronized void reset() {
2.169 + count = 0;
2.170 + }
2.171 +
2.172 + /**
2.173 + * Creates a newly allocated byte array. Its size is the current
2.174 + * size of this output stream and the valid contents of the buffer
2.175 + * have been copied into it.
2.176 + *
2.177 + * @return the current contents of this output stream, as a byte array.
2.178 + * @see java.io.ByteArrayOutputStream#size()
2.179 + */
2.180 + public synchronized byte toByteArray()[] {
2.181 + return Arrays.copyOf(buf, count);
2.182 + }
2.183 +
2.184 + /**
2.185 + * Returns the current size of the buffer.
2.186 + *
2.187 + * @return the value of the <code>count</code> field, which is the number
2.188 + * of valid bytes in this output stream.
2.189 + * @see java.io.ByteArrayOutputStream#count
2.190 + */
2.191 + public synchronized int size() {
2.192 + return count;
2.193 + }
2.194 +
2.195 + /**
2.196 + * Converts the buffer's contents into a string decoding bytes using the
2.197 + * platform's default character set. The length of the new <tt>String</tt>
2.198 + * is a function of the character set, and hence may not be equal to the
2.199 + * size of the buffer.
2.200 + *
2.201 + * <p> This method always replaces malformed-input and unmappable-character
2.202 + * sequences with the default replacement string for the platform's
2.203 + * default character set. The {@linkplain java.nio.charset.CharsetDecoder}
2.204 + * class should be used when more control over the decoding process is
2.205 + * required.
2.206 + *
2.207 + * @return String decoded from the buffer's contents.
2.208 + * @since JDK1.1
2.209 + */
2.210 + public synchronized String toString() {
2.211 + return new String(buf, 0, count);
2.212 + }
2.213 +
2.214 + /**
2.215 + * Converts the buffer's contents into a string by decoding the bytes using
2.216 + * the specified {@link java.nio.charset.Charset charsetName}. The length of
2.217 + * the new <tt>String</tt> is a function of the charset, and hence may not be
2.218 + * equal to the length of the byte array.
2.219 + *
2.220 + * <p> This method always replaces malformed-input and unmappable-character
2.221 + * sequences with this charset's default replacement string. The {@link
2.222 + * java.nio.charset.CharsetDecoder} class should be used when more control
2.223 + * over the decoding process is required.
2.224 + *
2.225 + * @param charsetName the name of a supported
2.226 + * {@linkplain java.nio.charset.Charset </code>charset<code>}
2.227 + * @return String decoded from the buffer's contents.
2.228 + * @exception UnsupportedEncodingException
2.229 + * If the named charset is not supported
2.230 + * @since JDK1.1
2.231 + */
2.232 + public synchronized String toString(String charsetName)
2.233 + throws UnsupportedEncodingException
2.234 + {
2.235 + return new String(buf, 0, count, charsetName);
2.236 + }
2.237 +
2.238 + /**
2.239 + * Creates a newly allocated string. Its size is the current size of
2.240 + * the output stream and the valid contents of the buffer have been
2.241 + * copied into it. Each character <i>c</i> in the resulting string is
2.242 + * constructed from the corresponding element <i>b</i> in the byte
2.243 + * array such that:
2.244 + * <blockquote><pre>
2.245 + * c == (char)(((hibyte & 0xff) << 8) | (b & 0xff))
2.246 + * </pre></blockquote>
2.247 + *
2.248 + * @deprecated This method does not properly convert bytes into characters.
2.249 + * As of JDK 1.1, the preferred way to do this is via the
2.250 + * <code>toString(String enc)</code> method, which takes an encoding-name
2.251 + * argument, or the <code>toString()</code> method, which uses the
2.252 + * platform's default character encoding.
2.253 + *
2.254 + * @param hibyte the high byte of each resulting Unicode character.
2.255 + * @return the current contents of the output stream, as a string.
2.256 + * @see java.io.ByteArrayOutputStream#size()
2.257 + * @see java.io.ByteArrayOutputStream#toString(String)
2.258 + * @see java.io.ByteArrayOutputStream#toString()
2.259 + */
2.260 + @Deprecated
2.261 + public synchronized String toString(int hibyte) {
2.262 + return new String(buf, hibyte, 0, count);
2.263 + }
2.264 +
2.265 + /**
2.266 + * Closing a <tt>ByteArrayOutputStream</tt> has no effect. The methods in
2.267 + * this class can be called after the stream has been closed without
2.268 + * generating an <tt>IOException</tt>.
2.269 + * <p>
2.270 + *
2.271 + */
2.272 + public void close() throws IOException {
2.273 + }
2.274 +
2.275 +}
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/emul/compact/src/main/java/java/util/Objects.java Wed Feb 06 15:10:22 2013 +0100
3.3 @@ -0,0 +1,229 @@
3.4 +/*
3.5 + * Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved.
3.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3.7 + *
3.8 + * This code is free software; you can redistribute it and/or modify it
3.9 + * under the terms of the GNU General Public License version 2 only, as
3.10 + * published by the Free Software Foundation. Oracle designates this
3.11 + * particular file as subject to the "Classpath" exception as provided
3.12 + * by Oracle in the LICENSE file that accompanied this code.
3.13 + *
3.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
3.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
3.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
3.17 + * version 2 for more details (a copy is included in the LICENSE file that
3.18 + * accompanied this code).
3.19 + *
3.20 + * You should have received a copy of the GNU General Public License version
3.21 + * 2 along with this work; if not, write to the Free Software Foundation,
3.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
3.23 + *
3.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
3.25 + * or visit www.oracle.com if you need additional information or have any
3.26 + * questions.
3.27 + */
3.28 +
3.29 +package java.util;
3.30 +
3.31 +/**
3.32 + * This class consists of {@code static} utility methods for operating
3.33 + * on objects. These utilities include {@code null}-safe or {@code
3.34 + * null}-tolerant methods for computing the hash code of an object,
3.35 + * returning a string for an object, and comparing two objects.
3.36 + *
3.37 + * @since 1.7
3.38 + */
3.39 +public final class Objects {
3.40 + private Objects() {
3.41 + throw new AssertionError("No java.util.Objects instances for you!");
3.42 + }
3.43 +
3.44 + /**
3.45 + * Returns {@code true} if the arguments are equal to each other
3.46 + * and {@code false} otherwise.
3.47 + * Consequently, if both arguments are {@code null}, {@code true}
3.48 + * is returned and if exactly one argument is {@code null}, {@code
3.49 + * false} is returned. Otherwise, equality is determined by using
3.50 + * the {@link Object#equals equals} method of the first
3.51 + * argument.
3.52 + *
3.53 + * @param a an object
3.54 + * @param b an object to be compared with {@code a} for equality
3.55 + * @return {@code true} if the arguments are equal to each other
3.56 + * and {@code false} otherwise
3.57 + * @see Object#equals(Object)
3.58 + */
3.59 + public static boolean equals(Object a, Object b) {
3.60 + return (a == b) || (a != null && a.equals(b));
3.61 + }
3.62 +
3.63 + /**
3.64 + * Returns {@code true} if the arguments are deeply equal to each other
3.65 + * and {@code false} otherwise.
3.66 + *
3.67 + * Two {@code null} values are deeply equal. If both arguments are
3.68 + * arrays, the algorithm in {@link Arrays#deepEquals(Object[],
3.69 + * Object[]) Arrays.deepEquals} is used to determine equality.
3.70 + * Otherwise, equality is determined by using the {@link
3.71 + * Object#equals equals} method of the first argument.
3.72 + *
3.73 + * @param a an object
3.74 + * @param b an object to be compared with {@code a} for deep equality
3.75 + * @return {@code true} if the arguments are deeply equal to each other
3.76 + * and {@code false} otherwise
3.77 + * @see Arrays#deepEquals(Object[], Object[])
3.78 + * @see Objects#equals(Object, Object)
3.79 + */
3.80 + public static boolean deepEquals(Object a, Object b) {
3.81 + if (a == b)
3.82 + return true;
3.83 + else if (a == null || b == null)
3.84 + return false;
3.85 + else
3.86 + return Arrays.deepEquals0(a, b);
3.87 + }
3.88 +
3.89 + /**
3.90 + * Returns the hash code of a non-{@code null} argument and 0 for
3.91 + * a {@code null} argument.
3.92 + *
3.93 + * @param o an object
3.94 + * @return the hash code of a non-{@code null} argument and 0 for
3.95 + * a {@code null} argument
3.96 + * @see Object#hashCode
3.97 + */
3.98 + public static int hashCode(Object o) {
3.99 + return o != null ? o.hashCode() : 0;
3.100 + }
3.101 +
3.102 + /**
3.103 + * Generates a hash code for a sequence of input values. The hash
3.104 + * code is generated as if all the input values were placed into an
3.105 + * array, and that array were hashed by calling {@link
3.106 + * Arrays#hashCode(Object[])}.
3.107 + *
3.108 + * <p>This method is useful for implementing {@link
3.109 + * Object#hashCode()} on objects containing multiple fields. For
3.110 + * example, if an object that has three fields, {@code x}, {@code
3.111 + * y}, and {@code z}, one could write:
3.112 + *
3.113 + * <blockquote><pre>
3.114 + * @Override public int hashCode() {
3.115 + * return Objects.hash(x, y, z);
3.116 + * }
3.117 + * </pre></blockquote>
3.118 + *
3.119 + * <b>Warning: When a single object reference is supplied, the returned
3.120 + * value does not equal the hash code of that object reference.</b> This
3.121 + * value can be computed by calling {@link #hashCode(Object)}.
3.122 + *
3.123 + * @param values the values to be hashed
3.124 + * @return a hash value of the sequence of input values
3.125 + * @see Arrays#hashCode(Object[])
3.126 + * @see List#hashCode
3.127 + */
3.128 + public static int hash(Object... values) {
3.129 + return Arrays.hashCode(values);
3.130 + }
3.131 +
3.132 + /**
3.133 + * Returns the result of calling {@code toString} for a non-{@code
3.134 + * null} argument and {@code "null"} for a {@code null} argument.
3.135 + *
3.136 + * @param o an object
3.137 + * @return the result of calling {@code toString} for a non-{@code
3.138 + * null} argument and {@code "null"} for a {@code null} argument
3.139 + * @see Object#toString
3.140 + * @see String#valueOf(Object)
3.141 + */
3.142 + public static String toString(Object o) {
3.143 + return String.valueOf(o);
3.144 + }
3.145 +
3.146 + /**
3.147 + * Returns the result of calling {@code toString} on the first
3.148 + * argument if the first argument is not {@code null} and returns
3.149 + * the second argument otherwise.
3.150 + *
3.151 + * @param o an object
3.152 + * @param nullDefault string to return if the first argument is
3.153 + * {@code null}
3.154 + * @return the result of calling {@code toString} on the first
3.155 + * argument if it is not {@code null} and the second argument
3.156 + * otherwise.
3.157 + * @see Objects#toString(Object)
3.158 + */
3.159 + public static String toString(Object o, String nullDefault) {
3.160 + return (o != null) ? o.toString() : nullDefault;
3.161 + }
3.162 +
3.163 + /**
3.164 + * Returns 0 if the arguments are identical and {@code
3.165 + * c.compare(a, b)} otherwise.
3.166 + * Consequently, if both arguments are {@code null} 0
3.167 + * is returned.
3.168 + *
3.169 + * <p>Note that if one of the arguments is {@code null}, a {@code
3.170 + * NullPointerException} may or may not be thrown depending on
3.171 + * what ordering policy, if any, the {@link Comparator Comparator}
3.172 + * chooses to have for {@code null} values.
3.173 + *
3.174 + * @param <T> the type of the objects being compared
3.175 + * @param a an object
3.176 + * @param b an object to be compared with {@code a}
3.177 + * @param c the {@code Comparator} to compare the first two arguments
3.178 + * @return 0 if the arguments are identical and {@code
3.179 + * c.compare(a, b)} otherwise.
3.180 + * @see Comparable
3.181 + * @see Comparator
3.182 + */
3.183 + public static <T> int compare(T a, T b, Comparator<? super T> c) {
3.184 + return (a == b) ? 0 : c.compare(a, b);
3.185 + }
3.186 +
3.187 + /**
3.188 + * Checks that the specified object reference is not {@code null}. This
3.189 + * method is designed primarily for doing parameter validation in methods
3.190 + * and constructors, as demonstrated below:
3.191 + * <blockquote><pre>
3.192 + * public Foo(Bar bar) {
3.193 + * this.bar = Objects.requireNonNull(bar);
3.194 + * }
3.195 + * </pre></blockquote>
3.196 + *
3.197 + * @param obj the object reference to check for nullity
3.198 + * @param <T> the type of the reference
3.199 + * @return {@code obj} if not {@code null}
3.200 + * @throws NullPointerException if {@code obj} is {@code null}
3.201 + */
3.202 + public static <T> T requireNonNull(T obj) {
3.203 + if (obj == null)
3.204 + throw new NullPointerException();
3.205 + return obj;
3.206 + }
3.207 +
3.208 + /**
3.209 + * Checks that the specified object reference is not {@code null} and
3.210 + * throws a customized {@link NullPointerException} if it is. This method
3.211 + * is designed primarily for doing parameter validation in methods and
3.212 + * constructors with multiple parameters, as demonstrated below:
3.213 + * <blockquote><pre>
3.214 + * public Foo(Bar bar, Baz baz) {
3.215 + * this.bar = Objects.requireNonNull(bar, "bar must not be null");
3.216 + * this.baz = Objects.requireNonNull(baz, "baz must not be null");
3.217 + * }
3.218 + * </pre></blockquote>
3.219 + *
3.220 + * @param obj the object reference to check for nullity
3.221 + * @param message detail message to be used in the event that a {@code
3.222 + * NullPointerException} is thrown
3.223 + * @param <T> the type of the reference
3.224 + * @return {@code obj} if not {@code null}
3.225 + * @throws NullPointerException if {@code obj} is {@code null}
3.226 + */
3.227 + public static <T> T requireNonNull(T obj, String message) {
3.228 + if (obj == null)
3.229 + throw new NullPointerException(message);
3.230 + return obj;
3.231 + }
3.232 +}