archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 15:24:43 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8284851: Update javax.crypto files to use proper javadoc for mentioned classes

Browse source 
Reviewed-by: weijun, valeriep
This commit is contained in:
Mark Powers 2022-07-07 23:20:58 +00:00 • committed by Valerie Peng
parent 8cdead0c94
commit f804f2ce8e
92 changed files with 2142 additions and 2010 deletions
Download patch file Download diff file Expand all files Collapse all files

107
src/java.base/share/classes/javax/crypto/CipherInputStream.java
View file

@ -30,38 +30,40 @@ import java.io.IOException;
import java.io.InputStream;
/**
* A CipherInputStream is composed of an InputStream and a Cipher so
* that read() methods return data that are read in from the
* underlying InputStream but have been additionally processed by the
* Cipher. The Cipher must be fully initialized before being used by
* a CipherInputStream.
* A {@code CipherInputStream} is composed of an {@code InputStream}
* and a {@code Cipher} object so that read() methods return data that are
* read in from the underlying {@code InputStream} but have been
* additionally processed by the {@code Cipher} object. The {@code Cipher}
* object must be fully initialized before being used by a
* {@code CipherInputStream}.
*
* <p> For example, if the Cipher is initialized for decryption, the
* CipherInputStream will attempt to read in data and decrypt them,
* before returning the decrypted data.
* <p> For example, if the {@code Cipher} object is initialized for decryption,
* the {@code CipherInputStream} will attempt to read in data and decrypt
* them, before returning the decrypted data.
*
* <p> This class adheres strictly to the semantics, especially the
* failure semantics, of its ancestor classes
* java.io.FilterInputStream and java.io.InputStream. This class has
* exactly those methods specified in its ancestor classes, and
* {@code java.io.FilterInputStream} and {@code java.io.InputStream}.
* This class has exactly those methods specified in its ancestor classes, and
* overrides them all. Moreover, this class catches all exceptions
* that are not thrown by its ancestor classes. In particular, the
* <code>skip</code> method skips, and the <code>available</code>
* method counts only data that have been processed by the encapsulated Cipher.
* This class may catch BadPaddingException and other exceptions thrown by
* failed integrity checks during decryption. These exceptions are not
* {@code skip} method skips, and the {@code available}
* method counts only data that have been processed by the encapsulated
* {@code Cipher} object.
* This class may catch {@code BadPaddingException} and other exceptions
* thrown by failed integrity checks during decryption. These exceptions are not
* re-thrown, so the client may not be informed that integrity checks
* failed. Because of this behavior, this class may not be suitable
* for use with decryption in an authenticated mode of operation (e.g. GCM).
* Applications that require authenticated encryption can use the Cipher API
* directly as an alternative to using this class.
* Applications that require authenticated encryption can use the
* {@code Cipher} API directly as an alternative to using this class.
*
* <p> It is crucial for a programmer using this class not to use
* methods that are not defined or overridden in this class (such as a
* new method or constructor that is later added to one of the super
* classes), because the design and implementation of those methods
* are unlikely to have considered security impact with regard to
* CipherInputStream.
* {@code CipherInputStream}.
*
* @author Li Gong
* @see java.io.InputStream
@ -100,7 +102,7 @@ public class CipherInputStream extends FilterInputStream {
/**
* Ensure obuffer is big enough for the next update or doFinal
* operation, given the input length <code>inLen</code> (in bytes)
* operation, given the input length {@code inLen} (in bytes)
* The ostart and ofinish indices are reset to 0.
*
* @param inLen the input length (in bytes)
@ -163,13 +165,13 @@ public class CipherInputStream extends FilterInputStream {
}
/**
* Constructs a CipherInputStream from an InputStream and a
* Cipher.
* Constructs a {@code CipherInputStream} from an
* {@code InputStream} and a {@code Cipher} object.
* <br>Note: if the specified input stream or cipher is
* null, a NullPointerException may be thrown later when
* {@code null}, a {@code NullPointerException} may be thrown later when
* they are used.
* @param is the to-be-processed input stream
* @param c an initialized Cipher object
* @param c an initialized {@code Cipher} object
*/
public CipherInputStream(InputStream is, Cipher c) {
super(is);
@ -178,11 +180,12 @@ public class CipherInputStream extends FilterInputStream {
}
/**
* Constructs a CipherInputStream from an InputStream without
* specifying a Cipher. This has the effect of constructing a
* CipherInputStream using a NullCipher.
* <br>Note: if the specified input stream is null, a
* NullPointerException may be thrown later when it is used.
* Constructs a {@code CipherInputStream} from an
* {@code InputStream} without specifying a {@code Cipher} object.
* This has the effect of constructing a {@code CipherInputStream}
* using a {@code NullCipher}.
* <br>Note: if the specified input stream is {@code null}, a
* {@code NullPointerException} may be thrown later when it is used.
* @param is the to-be-processed input stream
*/
protected CipherInputStream(InputStream is) {
@ -193,14 +196,14 @@ public class CipherInputStream extends FilterInputStream {
/**
* Reads the next byte of data from this input stream. The value
* byte is returned as an <code>int</code> in the range
* <code>0</code> to <code>255</code>. If no byte is available
* byte is returned as an {@code int} in the range
* {@code 0} to {@code 255}. If no byte is available
* because the end of the stream has been reached, the value
* <code>-1</code> is returned. This method blocks until input data
* {@code -1} is returned. This method blocks until input data
* is available, the end of the stream is detected, or an exception
* is thrown.
*
* @return the next byte of data, or <code>-1</code> if the end of the
* @return the next byte of data, or {@code -1} if the end of the
* stream is reached.
* @exception IOException if an I/O error occurs.
*/
@ -216,16 +219,16 @@ public class CipherInputStream extends FilterInputStream {
}
/**
* Reads up to <code>b.length</code> bytes of data from this input
* Reads up to {@code b.length} bytes of data from this input
* stream into an array of bytes.
* <p>
* The <code>read</code> method of <code>InputStream</code> calls
* the <code>read</code> method of three arguments with the arguments
* <code>b</code>, <code>0</code>, and <code>b.length</code>.
* The {@code read} method of {@code InputStream} calls
* the {@code read} method of three arguments with the arguments
* {@code b}, {@code 0}, and {@code b.length}.
*
* @param b the buffer into which the data is read.
* @return the total number of bytes read into the buffer, or
* <code>-1</code> is there is no more data because the end of
* {@code -1} is there is no more data because the end of
* the stream has been reached.
* @exception IOException if an I/O error occurs.
* @see java.io.InputStream#read(byte[], int, int)
@ -236,17 +239,17 @@ public class CipherInputStream extends FilterInputStream {
}
/**
* Reads up to <code>len</code> bytes of data from this input stream
* Reads up to {@code len} bytes of data from this input stream
* into an array of bytes. This method blocks until some input is
* available. If the first argument is <code>null,</code> up to
* <code>len</code> bytes are read and discarded.
* available. If the first argument is {@code null}, up to
* {@code len} bytes are read and discarded.
*
* @param b the buffer into which the data is read.
* @param off the start offset in the destination array
* <code>buf</code>
* {@code buf}
* @param len the maximum number of bytes read.
* @return the total number of bytes read into the buffer, or
* <code>-1</code> if there is no more data because the end of
* {@code -1} if there is no more data because the end of
* the stream has been reached.
* @exception IOException if an I/O error occurs.
* @see java.io.InputStream#read()
@ -272,15 +275,15 @@ public class CipherInputStream extends FilterInputStream {
}
/**
* Skips <code>n</code> bytes of input from the bytes that can be read
* Skips {@code n} bytes of input from the bytes that can be read
* from this input stream without blocking.
*
* <p>Fewer bytes than requested might be skipped.
* The actual number of bytes skipped is equal to <code>n</code> or
* The actual number of bytes skipped is equal to {@code n} or
* the result of a call to
* {@link #available() available},
* whichever is smaller.
* If <code>n</code> is less than zero, no bytes are skipped.
* If {@code n} is less than zero, no bytes are skipped.
*
* <p>The actual number of bytes skipped is returned.
*
@ -303,8 +306,8 @@ public class CipherInputStream extends FilterInputStream {
/**
* Returns the number of bytes that can be read from this input
* stream without blocking. The <code>available</code> method of
* <code>InputStream</code> returns <code>0</code>. This method
* stream without blocking. The {@code available} method of
* {@code InputStream} returns {@code 0}. This method
* <B>should</B> be overridden by subclasses.
*
* @return the number of bytes that can be read from this input stream
@ -320,8 +323,8 @@ public class CipherInputStream extends FilterInputStream {
* Closes this input stream and releases any system resources
* associated with the stream.
* <p>
* The <code>close</code> method of <code>CipherInputStream</code>
* calls the <code>close</code> method of its underlying input
* The {@code close} method of {@code CipherInputStream}
* calls the {@code close} method of its underlying input
* stream.
*
* @exception IOException if an I/O error occurs.
@ -350,11 +353,11 @@ public class CipherInputStream extends FilterInputStream {
}
/**
* Tests if this input stream supports the <code>mark</code>
* and <code>reset</code> methods, which it does not.
* Tests if this input stream supports the {@code mark}
* and {@code reset} methods, which it does not.
*
* @return <code>false</code>, since this class does not support the
* <code>mark</code> and <code>reset</code> methods.
* @return {@code false}, since this class does not support the
* {@code mark} and {@code reset} methods.
* @see java.io.InputStream#mark(int)
* @see java.io.InputStream#reset()
*/