001: /*
002: * @(#)RoResponse.java 0.3-2 18/06/1999
003: *
004: * This file is part of the HTTPClient package
005: * Copyright (C) 1996-1999 Ronald Tschalär
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation; either
010: * version 2 of the License, or (at your option) any later version.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this library; if not, write to the Free
019: * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
020: * MA 02111-1307, USA
021: *
022: * For questions, suggestions, bug-reports, enhancement-requests etc.
023: * I may be contacted at:
024: *
025: * ronald@innovation.ch
026: *
027: */
028:
029: package HTTPClient;
030:
031: import java.io.InputStream;
032: import java.io.IOException;
033: import java.io.InterruptedIOException;
034: import java.io.EOFException;
035: import java.net.ProtocolException;
036: import java.util.Date;
037:
038: /**
039: * This interface represents read-only interface of an intermediate http
040: * response. It is the compile-time type passed to various handlers which
041: * might the response info but musn't modify the response.
042: *
043: * @version 0.3-2 18/06/1999
044: * @author Ronald Tschalär
045: */
046:
047: public interface RoResponse {
048: /**
049: * give the status code for this request. These are grouped as follows:
050: * <UL>
051: * <LI> 1xx - Informational (new in HTTP/1.1)
052: * <LI> 2xx - Success
053: * <LI> 3xx - Redirection
054: * <LI> 4xx - Client Error
055: * <LI> 5xx - Server Error
056: * </UL>
057: *
058: * @return the status code
059: * @exception IOException If any exception occurs on the socket.
060: */
061: public int getStatusCode() throws IOException;
062:
063: /**
064: * @return the reason line associated with the status code.
065: * @exception IOException If any exception occurs on the socket.
066: */
067: public String getReasonLine() throws IOException;
068:
069: /**
070: * @return the HTTP version returned by the server.
071: * @exception IOException If any exception occurs on the socket.
072: */
073: public String getVersion() throws IOException;
074:
075: /**
076: * retrieves the field for a given header.
077: *
078: * @param hdr the header name.
079: * @return the value for the header, or null if non-existent.
080: * @exception IOException If any exception occurs on the socket.
081: */
082: public String getHeader(String hdr) throws IOException;
083:
084: /**
085: * retrieves the field for a given header. The value is parsed as an
086: * int.
087: *
088: * @param hdr the header name.
089: * @return the value for the header if the header exists
090: * @exception NumberFormatException if the header's value is not a number
091: * or if the header does not exist.
092: * @exception IOException if any exception occurs on the socket.
093: */
094: public int getHeaderAsInt(String hdr) throws IOException,
095: NumberFormatException;
096:
097: /**
098: * retrieves the field for a given header. The value is parsed as a
099: * date; if this fails it is parsed as a long representing the number
100: * of seconds since 12:00 AM, Jan 1st, 1970. If this also fails an
101: * IllegalArgumentException is thrown.
102: *
103: * @param hdr the header name.
104: * @return the value for the header, or null if non-existent.
105: * @exception IOException If any exception occurs on the socket.
106: * @exception IllegalArgumentException If the header cannot be parsed
107: * as a date or time.
108: */
109: public Date getHeaderAsDate(String hdr) throws IOException,
110: IllegalArgumentException;
111:
112: /**
113: * Retrieves the field for a given trailer. Note that this should not
114: * be invoked until all the response data has been read. If invoked
115: * before, it will force the data to be read via <code>getData()</code>.
116: *
117: * @param trailer the trailer name.
118: * @return the value for the trailer, or null if non-existent.
119: * @exception IOException If any exception occurs on the socket.
120: */
121: public String getTrailer(String trailer) throws IOException;
122:
123: /**
124: * Retrieves the field for a given tailer. The value is parsed as an
125: * int.
126: *
127: * @param trailer the tailer name.
128: * @return the value for the trailer if the trailer exists
129: * @exception NumberFormatException if the trailer's value is not a number
130: * or if the trailer does not exist.
131: * @exception IOException if any exception occurs on the socket.
132: */
133: public int getTrailerAsInt(String trailer) throws IOException,
134: NumberFormatException;
135:
136: /**
137: * Retrieves the field for a given trailer. The value is parsed as a
138: * date; if this fails it is parsed as a long representing the number
139: * of seconds since 12:00 AM, Jan 1st, 1970. If this also fails an
140: * IllegalArgumentException is thrown.
141: * <br>Note: When sending dates use Util.httpDate().
142: *
143: * @param trailer the trailer name.
144: * @return the value for the trailer, or null if non-existent.
145: * @exception IllegalArgumentException if the trailer's value is neither a
146: * legal date nor a number.
147: * @exception IOException if any exception occurs on the socket.
148: * @exception IllegalArgumentException If the header cannot be parsed
149: * as a date or time.
150: */
151: public Date getTrailerAsDate(String trailer) throws IOException,
152: IllegalArgumentException;
153:
154: /**
155: * Reads all the response data into a byte array. Note that this method
156: * won't return until <em>all</em> the data has been received (so for
157: * instance don't invoke this method if the server is doing a server
158: * push). If getInputStream() had been previously called then this method
159: * only returns any unread data remaining on the stream and then closes
160: * it.
161: *
162: * @see #getInputStream()
163: * @return an array containing the data (body) returned. If no data
164: * was returned then it's set to a zero-length array.
165: * @exception IOException If any io exception occured while reading
166: * the data
167: */
168: public byte[] getData() throws IOException;
169:
170: /**
171: * Gets an input stream from which the returned data can be read. Note
172: * that if getData() had been previously called it will actually return
173: * a ByteArrayInputStream created from that data.
174: *
175: * @see #getData()
176: * @return the InputStream.
177: * @exception IOException If any exception occurs on the socket.
178: */
179: public InputStream getInputStream() throws IOException;
180: }
|