KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > crypto > CipherInputStream


1 /*
2  * @(#)CipherInputStream.java 1.6 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7   
8 /*
9  * NOTE:
10  * Because of various external restrictions (i.e. US export
11  * regulations, etc.), the actual source code can not be provided
12  * at this time. This file represents the skeleton of the source
13  * file, so that javadocs of the API can be created.
14  */
15
16 package javax.crypto;
17
18 import java.io.*;
19
20 /**
21  * A CipherInputStream is composed of an InputStream and a Cipher so
22  * that read() methods return data that are read in from the
23  * underlying InputStream but have been additionally processed by the
24  * Cipher. The Cipher must be fully initialized before being used by
25  * a CipherInputStream.
26  *
27  * <p> For example, if the Cipher is initialized for decryption, the
28  * CipherInputStream will attempt to read in data and decrypt them,
29  * before returning the decrypted data.
30  *
31  * <p> This class adheres strictly to the semantics, especially the
32  * failure semantics, of its ancestor classes
33  * java.io.FilterInputStream and java.io.InputStream. This class has
34  * exactly those methods specified in its ancestor classes, and
35  * overrides them all. Moreover, this class catches all exceptions
36  * that are not thrown by its ancestor classes. In particular, the
37  * <code>skip</code> method skips, and the <code>available</code>
38  * method counts only data that have been processed by the encapsulated Cipher.
39  *
40  * <p> It is crucial for a programmer using this class not to use
41  * methods that are not defined or overriden in this class (such as a
42  * new method or constructor that is later added to one of the super
43  * classes), because the design and implementation of those methods
44  * are unlikely to have considered security impact with regard to
45  * CipherInputStream.
46  *
47  * @author Li Gong
48  * @version 1.27, 10/29/03
49  * @see java.io.InputStream
50  * @see java.io.FilterInputStream
51  * @see javax.crypto.Cipher
52  * @see javax.crypto.CipherOutputStream
53  *
54  * @since 1.4
55  */
56 public class CipherInputStream extends FilterInputStream
57 {
58
59     /**
60      * Constructs a CipherInputStream from an InputStream and a
61      * Cipher.
62      * <br>Note: if the specified input stream or cipher is
63      * null, a NullPointerException may be thrown later when
64      * they are used.
65      * @param is the to-be-processed input stream
66      * @param c an initialized Cipher object
67      */
68     public CipherInputStream(InputStream is, Cipher c) { }
69
70     /**
71      * Constructs a CipherInputStream from an InputStream without
72      * specifying a Cipher. This has the effect of constructing a
73      * CipherInputStream using a NullCipher.
74      * <br>Note: if the specified input stream is null, a
75      * NullPointerException may be thrown later when it is used.
76      * @param is the to-be-processed input stream
77      */
78     protected CipherInputStream(InputStream is) { }
79
80     /**
81      * Reads the next byte of data from this input stream. The value
82      * byte is returned as an <code>int</code> in the range
83      * <code>0</code> to <code>255</code>. If no byte is available
84      * because the end of the stream has been reached, the value
85      * <code>-1</code> is returned. This method blocks until input data
86      * is available, the end of the stream is detected, or an exception
87      * is thrown.
88      * <p>
89      *
90      * @return the next byte of data, or <code>-1</code> if the end of the
91      * stream is reached.
92      * @exception IOException if an I/O error occurs.
93      * @since JCE1.2
94      */
95     public int read() throws IOException { }
96
97     /**
98      * Reads up to <code>b.length</code> bytes of data from this input
99      * stream into an array of bytes.
100      * <p>
101      * The <code>read</code> method of <code>InputStream</code> calls
102      * the <code>read</code> method of three arguments with the arguments
103      * <code>b</code>, <code>0</code>, and <code>b.length</code>.
104      *
105      * @param b the buffer into which the data is read.
106      * @return the total number of bytes read into the buffer, or
107      * <code>-1</code> is there is no more data because the end of
108      * the stream has been reached.
109      * @exception IOException if an I/O error occurs.
110      * @see java.io.InputStream#read(byte[], int, int)
111      * @since JCE1.2
112      */
113     public int read(byte[] b) throws IOException { }
114
115     /**
116      * Reads up to <code>len</code> bytes of data from this input stream
117      * into an array of bytes. This method blocks until some input is
118      * available. If the first argument is <code>null,</code> up to
119      * <code>len</code> bytes are read and discarded.
120      *
121      * @param b the buffer into which the data is read.
122      * @param off the start offset of the data.
123      * @param len the maximum number of bytes read.
124      * @return the total number of bytes read into the buffer, or
125      * <code>-1</code> if there is no more data because the end of
126      * the stream has been reached.
127      * @exception IOException if an I/O error occurs.
128      * @see java.io.InputStream#read()
129      * @since JCE1.2
130      */
131     public int read(byte[] b, int off, int len) throws IOException { }
132
133     /**
134      * Skips <code>n</code> bytes of input from the bytes that can be read
135      * from this input stream without blocking.
136      *
137      * <p>Fewer bytes than requested might be skipped.
138      * The actual number of bytes skipped is equal to <code>n</code> or
139      * the result of a call to
140      * {@link #available() <code>available</code>},
141      * whichever is smaller.
142      * If <code>n</code> is less than zero, no bytes are skipped.
143      *
144      * <p>The actual number of bytes skipped is returned.
145      *
146      * @param n the number of bytes to be skipped.
147      * @return the actual number of bytes skipped.
148      * @exception IOException if an I/O error occurs.
149      * @since JCE1.2
150      */
151     public long skip(long n) throws IOException { }
152
153     /**
154      * Returns the number of bytes that can be read from this input
155      * stream without blocking. The <code>available</code> method of
156      * <code>InputStream</code> returns <code>0</code>. This method
157      * <B>should</B> be overridden by subclasses.
158      *
159      * @return the number of bytes that can be read from this input stream
160      * without blocking.
161      * @exception IOException if an I/O error occurs.
162      * @since JCE1.2
163      */
164     public int available() throws IOException { }
165
166     /**
167      * Closes this input stream and releases any system resources
168      * associated with the stream.
169      * <p>
170      * The <code>close</code> method of <code>CipherInputStream</code>
171      * calls the <code>close</code> method of its underlying input
172      * stream.
173      *
174      * @exception IOException if an I/O error occurs.
175      * @since JCE1.2
176      */
177     public void close() throws IOException { }
178
179     /**
180      * Tests if this input stream supports the <code>mark</code>
181      * and <code>reset</code> methods, which it does not.
182      *
183      * @return <code>false</code>, since this class does not support the
184      * <code>mark</code> and <code>reset</code> methods.
185      * @see java.io.InputStream#mark(int)
186      * @see java.io.InputStream#reset()
187      * @since JCE1.2
188      */
189     public boolean markSupported() { }
190 }
191
Popular Tags