KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > HTTPClient > RoResponse


1 /*
2  * @(#)RoResponse.java 0.3-2 18/06/1999
3  *
4  * This file is part of the HTTPClient package
5  * Copyright (C) 1996-1999 Ronald Tschalär
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library; if not, write to the Free
19  * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
20  * MA 02111-1307, USA
21  *
22  * For questions, suggestions, bug-reports, enhancement-requests etc.
23  * I may be contacted at:
24  *
25  * ronald@innovation.ch
26  *
27  */
28
29 package HTTPClient;
30
31 import java.io.InputStream JavaDoc;
32 import java.io.IOException JavaDoc;
33 import java.io.InterruptedIOException JavaDoc;
34 import java.io.EOFException JavaDoc;
35 import java.net.ProtocolException JavaDoc;
36 import java.util.Date JavaDoc;
37
38
39 /**
40  * This interface represents read-only interface of an intermediate http
41  * response. It is the compile-time type passed to various handlers which
42  * might the response info but musn't modify the response.
43  *
44  * @version 0.3-2 18/06/1999
45  * @author Ronald Tschalär
46  */
47
48 public interface RoResponse
49 {
50     /**
51      * give the status code for this request. These are grouped as follows:
52      * <UL>
53      * <LI> 1xx - Informational (new in HTTP/1.1)
54      * <LI> 2xx - Success
55      * <LI> 3xx - Redirection
56      * <LI> 4xx - Client Error
57      * <LI> 5xx - Server Error
58      * </UL>
59      *
60      * @return the status code
61      * @exception IOException If any exception occurs on the socket.
62      */
63     public int getStatusCode() throws IOException JavaDoc;
64
65     /**
66      * @return the reason line associated with the status code.
67      * @exception IOException If any exception occurs on the socket.
68      */
69     public String JavaDoc getReasonLine() throws IOException JavaDoc;
70
71     /**
72      * @return the HTTP version returned by the server.
73      * @exception IOException If any exception occurs on the socket.
74      */
75     public String JavaDoc getVersion() throws IOException JavaDoc;
76
77     /**
78      * retrieves the field for a given header.
79      *
80      * @param hdr the header name.
81      * @return the value for the header, or null if non-existent.
82      * @exception IOException If any exception occurs on the socket.
83      */
84     public String JavaDoc getHeader(String JavaDoc hdr) throws IOException JavaDoc;
85
86     /**
87      * retrieves the field for a given header. The value is parsed as an
88      * int.
89      *
90      * @param hdr the header name.
91      * @return the value for the header if the header exists
92      * @exception NumberFormatException if the header's value is not a number
93      * or if the header does not exist.
94      * @exception IOException if any exception occurs on the socket.
95      */
96     public int getHeaderAsInt(String JavaDoc hdr)
97         throws IOException JavaDoc, NumberFormatException JavaDoc;
98
99     /**
100      * retrieves the field for a given header. The value is parsed as a
101      * date; if this fails it is parsed as a long representing the number
102      * of seconds since 12:00 AM, Jan 1st, 1970. If this also fails an
103      * IllegalArgumentException is thrown.
104      *
105      * @param hdr the header name.
106      * @return the value for the header, or null if non-existent.
107      * @exception IOException If any exception occurs on the socket.
108      * @exception IllegalArgumentException If the header cannot be parsed
109      * as a date or time.
110      */
111     public Date JavaDoc getHeaderAsDate(String JavaDoc hdr)
112         throws IOException JavaDoc, IllegalArgumentException JavaDoc;
113
114     /**
115      * Retrieves the field for a given trailer. Note that this should not
116      * be invoked until all the response data has been read. If invoked
117      * before, it will force the data to be read via <code>getData()</code>.
118      *
119      * @param trailer the trailer name.
120      * @return the value for the trailer, or null if non-existent.
121      * @exception IOException If any exception occurs on the socket.
122      */
123     public String JavaDoc getTrailer(String JavaDoc trailer) throws IOException JavaDoc;
124
125     /**
126      * Retrieves the field for a given tailer. The value is parsed as an
127      * int.
128      *
129      * @param trailer the tailer name.
130      * @return the value for the trailer if the trailer exists
131      * @exception NumberFormatException if the trailer's value is not a number
132      * or if the trailer does not exist.
133      * @exception IOException if any exception occurs on the socket.
134      */
135     public int getTrailerAsInt(String JavaDoc trailer)
136         throws IOException JavaDoc, NumberFormatException JavaDoc;
137
138
139     /**
140      * Retrieves the field for a given trailer. The value is parsed as a
141      * date; if this fails it is parsed as a long representing the number
142      * of seconds since 12:00 AM, Jan 1st, 1970. If this also fails an
143      * IllegalArgumentException is thrown.
144      * <br>Note: When sending dates use Util.httpDate().
145      *
146      * @param trailer the trailer name.
147      * @return the value for the trailer, or null if non-existent.
148      * @exception IllegalArgumentException if the trailer's value is neither a
149      * legal date nor a number.
150      * @exception IOException if any exception occurs on the socket.
151      * @exception IllegalArgumentException If the header cannot be parsed
152      * as a date or time.
153      */
154     public Date JavaDoc getTrailerAsDate(String JavaDoc trailer)
155         throws IOException JavaDoc, IllegalArgumentException JavaDoc;
156
157     /**
158      * Reads all the response data into a byte array. Note that this method
159      * won't return until <em>all</em> the data has been received (so for
160      * instance don't invoke this method if the server is doing a server
161      * push). If getInputStream() had been previously called then this method
162      * only returns any unread data remaining on the stream and then closes
163      * it.
164      *
165      * @see #getInputStream()
166      * @return an array containing the data (body) returned. If no data
167      * was returned then it's set to a zero-length array.
168      * @exception IOException If any io exception occured while reading
169      * the data
170      */
171     public byte[] getData() throws IOException JavaDoc;
172
173     /**
174      * Gets an input stream from which the returned data can be read. Note
175      * that if getData() had been previously called it will actually return
176      * a ByteArrayInputStream created from that data.
177      *
178      * @see #getData()
179      * @return the InputStream.
180      * @exception IOException If any exception occurs on the socket.
181      */
182     public InputStream JavaDoc getInputStream() throws IOException JavaDoc;
183 }
184
185
Popular Tags