ObjectInput.java revision fdb2704414a9ed92394ada0d1395e4db86889465 
1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.io;
19
20/**
21 * Streams to be used with serialization to read objects must implement this
22 * interface. ObjectInputStream is one example.
23 *
24 * @see ObjectInputStream
25 * @see ObjectOutput
26 */
27public interface ObjectInput extends DataInput {
28    /**
29     * Returns a int representing then number of bytes of primitive data that
30     * are available.
31     *
32     * @return int the number of primitive bytes available.
33     *
34     * @throws IOException
35     *             If an error occurs in this ObjectInput.
36     */
37    public int available() throws IOException;
38
39    /**
40     * Close this ObjectInput. Concrete implementations of this class should
41     * free any resources during close.
42     *
43     * @throws IOException
44     *             If an error occurs attempting to close this ObjectInput.
45     */
46    public void close() throws IOException;
47
48    /**
49     * Reads a single byte from this ObjectInput and returns the result as an
50     * int. The low-order byte is returned or -1 of the end of stream was
51     * encountered.
52     *
53     * @return int The byte read or -1 if end of ObjectInput.
54     *
55     * @throws IOException
56     *             If the ObjectInput is already closed or another IOException
57     *             occurs.
58     */
59    public int read() throws IOException;
60
61    /**
62     * Reads bytes from the <code>ObjectInput</code> and stores them in byte
63     * array <code>buffer</code>. Blocks while waiting for input.
64     *
65     * @param buffer
66     *            the array in which to store the read bytes.
67     * @return how many bytes were read or <code>-1</code> if encountered end
68     *         of <code>ObjectInput</code>.
69     *
70     * @throws IOException
71     *             If the <code>ObjectInput</code> is already closed or
72     *             another IOException occurs.
73     */
74    public int read(byte[] buffer) throws IOException;
75
76    /**
77     * Reads at most <code>count</code> bytes from the ObjectInput and stores
78     * them in byte array <code>buffer</code> starting at offset
79     * <code>count</code>. Answer the number of bytes actually read or -1 if
80     * no bytes were read and end of ObjectInput was encountered.
81     *
82     * @param buffer
83     *            the byte array in which to store the read bytes.
84     * @param offset
85     *            the offset in <code>buffer</code> to store the read bytes.
86     * @param count
87     *            the maximum number of bytes to store in <code>buffer</code>.
88     * @return the number of bytes actually read or -1 if end of ObjectInput.
89     *
90     * @throws IOException
91     *             If the ObjectInput is already closed or another IOException
92     *             occurs.
93     */
94    public int read(byte[] buffer, int offset, int count) throws IOException;
95
96    /**
97     * Reads the next object from this ObjectInput.
98     *
99     * @return the next object read from this ObjectInput
100     *
101     * @throws IOException
102     *             If an error occurs attempting to read from this ObjectInput.
103     * @throws ClassNotFoundException
104     *             If the object's class cannot be found
105     */
106    public Object readObject() throws ClassNotFoundException, IOException;
107
108    /**
109     * Skips <code>toSkip</code> number of bytes in this ObjectInput.
110     * Subsequent <code>read()</code>'s will not return these bytes.
111     *
112     * @param toSkip
113     *            the number of bytes to skip.
114     * @return the number of bytes actually skipped.
115     *
116     * @throws IOException
117     *             If the ObjectInput is already closed or another IOException
118     *             occurs.
119     */
120    public long skip(long toSkip) throws IOException;
121}
122