001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.io;
028:
029: import java.io.IOException;
030: import java.io.InputStream;
031: import java.io.OutputStream;
032: import java.lang.String;
033: import javax.microedition.io.ContentConnection;
034:
035: /**
036: * This interface defines the necessary methods and constants
037: * for an HTTP connection.
038: * <P>
039: * HTTP is a request-response protocol in which the parameters of
040: * request must be set before the request is sent.
041: * The connection exists in one of three states:
042: * <UL>
043: * <LI> Setup, in which the request parameters can be set
044: * <LI> Connected, in which request parameters have been sent and the
045: * response is expected
046: * <LI> Closed, the final state, in which the HTTP connection as been
047: * terminated
048: * </UL>
049: * The following methods may be invoked only in the Setup state:
050: * <UL>
051: * <LI> <CODE> setRequestMethod</CODE>
052: * <LI> <CODE> setRequestProperty</CODE>
053: * </UL>
054: *
055: * The transition from Setup to Connected is caused by any method that
056: * requires data to be sent to or received from the server. <p>
057: *
058: * The following methods cause the transition to the Connected state when
059: * the connection is in Setup state.
060: * <UL>
061: * <LI> <CODE> openInputStream</CODE>
062: * <LI> <CODE> openDataInputStream</CODE>
063: * <LI> <CODE> getLength</CODE>
064: * <LI> <CODE> getType</CODE>
065: * <LI> <CODE> getEncoding</CODE>
066: * <LI> <CODE> getHeaderField</CODE>
067: * <LI> <CODE> getResponseCode</CODE>
068: * <LI> <CODE> getResponseMessage</CODE>
069: * <LI> <CODE> getHeaderFieldInt</CODE>
070: * <LI> <CODE> getHeaderFieldDate</CODE>
071: * <LI> <CODE> getExpiration</CODE>
072: * <LI> <CODE> getDate</CODE>
073: * <LI> <CODE> getLastModified</CODE>
074: * <LI> <CODE> getHeaderField</CODE>
075: * <LI> <CODE> getHeaderFieldKey</CODE>
076: * </UL>
077: * <P>
078: * The following methods may be invoked while the connection is in Setup or
079: * Connected state.
080: * <UL>
081: * <LI> <CODE> close</CODE>
082: * <LI> <CODE> getRequestMethod</CODE>
083: * <LI> <CODE> getRequestProperty</CODE>
084: * <LI> <CODE> getURL</CODE>
085: * <LI> <CODE> getProtocol</CODE>
086: * <LI> <CODE> getHost</CODE>
087: * <LI> <CODE> getFile</CODE>
088: * <LI> <CODE> getRef</CODE>
089: * <LI> <CODE> getPort</CODE>
090: * <LI> <CODE> getQuery</CODE>
091: * </UL>
092: *
093: * <P>
094: * After an output stream has been opened by the
095: * <code>openOutputStream</code> or <code>openDataOutputStream</code>
096: * methods, attempts to change the request parameters via
097: * <code>setRequestMethod</code> or the <code>setRequestProperty</code>
098: * are ignored. Once the request parameters have been sent,
099: * these methods will throw an <code>IOException</code>.
100: *
101: * When an output stream is closed via the
102: * <code>OutputStream.close</code> or <code>DataOutputStream.close</code>
103: * methods, the connection enters the Connected state.
104: * When the output stream is flushed via the
105: * <code>OutputStream.flush</code> or <code>DataOutputStream.flush</code>
106: * methods, the request parameters MUST be sent along with any data
107: * written to the stream.
108: * </P>
109: *
110: * The transition to Closed state from any other state is caused by the
111: * <code>close</code> method and the closing all of the streams that were
112: * opened from the connection.
113: * <P>
114: * <STRONG>Example using StreamConnection</STRONG>
115: * <p>
116: * Simple read of a URL using <code>StreamConnection</code>.
117: * No HTTP specific behavior is needed or used.
118: * (<strong>Note:</strong> this example ignores all HTTP response
119: * headers and the HTTP response code. Since a proxy or server
120: * may have sent an error response page, an application
121: * can not distinguish which data is retrieved in
122: * the <code>InputStream</code>.)
123: *
124: * <p>
125: * <code>Connector.open</code> is used to open URL and a
126: * <code>StreamConnection</code> is returned.
127: * From the <code>StreamConnection</code> the
128: * <code>InputStream</code> is opened.
129: * It is used to read every character until end of file (-1).
130: * If an exception is thrown the connection and stream are closed.
131: * <p>
132: * <pre>
133: * void getViaStreamConnection(String url) throws IOException {
134: * StreamConnection c = null;
135: * InputStream s = null;
136: * try {
137: * c = (StreamConnection)Connector.open(url);
138: * s = c.openInputStream();
139: * int ch;
140: * while ((ch = s.read()) != -1) {
141: * ...
142: * }
143: * } finally {
144: * if (s != null)
145: * s.close();
146: * if (c != null)
147: * c.close();
148: * }
149: * }
150: * </pre>
151: * <p>
152: * <STRONG>Example using ContentConnection</STRONG>
153: * <p>
154: * Simple read of a URL using <code>ContentConnection</code>.
155: * No HTTP specific behavior is needed or used.
156: * <p>
157: * <code>Connector.open</code> is used to open url and
158: * a <code>ContentConnection</code> is returned.
159: * The <code>ContentConnection</code> may be able to provide the length.
160: * If the length is available, it is used to read the data in bulk.
161: * From the <code>ContentConnection</code> the
162: * <code>InputStream</code> is opened.
163: * It is used to read every character until end of file (-1).
164: * If an exception is thrown the connection and stream are closed.
165: * <p>
166: * <pre>
167: * void getViaContentConnection(String url) throws IOException {
168: * ContentConnection c = null;
169: * DataInputStream is = null;
170: * try {
171: * c = (ContentConnection)Connector.open(url);
172: * int len = (int)c.getLength();
173: * dis = c.openDataInputStream();
174: * if (len > 0) {
175: * byte[] data = new byte[len];
176: * dis.readFully(data);
177: * } else {
178: * int ch;
179: * while ((ch = dis.read()) != -1) {
180: * ...
181: * }
182: * }
183: * } finally {
184: * if (dis != null)
185: * dis.close();
186: * if (c != null)
187: * c.close();
188: * }
189: * }
190: * </pre>
191: * <p>
192: * <STRONG>Example using HttpConnection</STRONG>
193: * <p>
194: * Read the HTTP headers and the data using <code>HttpConnection</code>.
195: * <p>
196: * <code>Connector.open</code> is used to open url and a
197: * <code>HttpConnection</code> is returned.
198: * The HTTP headers are read and processed.
199: * If the length is available, it is used to read the data in bulk.
200: * From the <code>HttpConnection</code> the
201: * <code>InputStream</code> is opened.
202: * It is used to read every character until end of file (-1).
203: * If an exception is thrown the connection and stream are closed.
204: * <p>
205: * <pre>
206: * void getViaHttpConnection(String url) throws IOException {
207: * HttpConnection c = null;
208: * InputStream is = null;
209: * int rc;
210: *
211: * try {
212: * c = (HttpConnection)Connector.open(url);
213: *
214: * // Getting the response code will open the connection,
215: * // send the request, and read the HTTP response headers.
216: * // The headers are stored until requested.
217: * rc = c.getResponseCode();
218: * if (rc != HttpConnection.HTTP_OK) {
219: * throw new IOException("HTTP response code: " + rc);
220: * }
221: *
222: * is = c.openInputStream();
223: *
224: * // Get the ContentType
225: * String type = c.getType();
226: *
227: * // Get the length and process the data
228: * int len = (int)c.getLength();
229: * if (len > 0) {
230: * int actual = 0;
231: * int bytesread = 0 ;
232: * byte[] data = new byte[len];
233: * while ((bytesread != len) && (actual != -1)) {
234: * actual = is.read(data, bytesread, len - bytesread);
235: * bytesread += actual;
236: * }
237: * } else {
238: * int ch;
239: * while ((ch = is.read()) != -1) {
240: * ...
241: * }
242: * }
243: * } catch (ClassCastException e) {
244: * throw new IllegalArgumentException("Not an HTTP URL");
245: * } finally {
246: * if (is != null)
247: * is.close();
248: * if (c != null)
249: * c.close();
250: * }
251: * }
252: * </pre>
253: * <p>
254: * <STRONG>Example using POST with HttpConnection</STRONG>
255: * <p>
256: *
257: * Post a request with some headers and content to the server and
258: * process the headers and content.
259: * <p>
260: * <code>Connector.open</code> is used to open url and a
261: * <code>HttpConnection</code> is returned.
262: * The request method is set to POST and request headers set.
263: * A simple command is written and flushed.
264: * The HTTP headers are read and processed.
265: * If the length is available, it is used to read the data in bulk.
266: * From the <code>HttpConnection</code> the
267: * <code>InputStream</code> is opened.
268: * It is used to read every character until end of file (-1).
269: * If an exception is thrown the connection and stream is closed.
270: * <p>
271: * <pre>
272: * void postViaHttpConnection(String url) throws IOException {
273: * HttpConnection c = null;
274: * InputStream is = null;
275: * OutputStream os = null;
276: * int rc;
277: *
278: * try {
279: * c = (HttpConnection)Connector.open(url);
280: *
281: * // Set the request method and headers
282: * c.setRequestMethod(HttpConnection.POST);
283: * c.setRequestProperty("If-Modified-Since",
284: * "29 Oct 1999 19:43:31 GMT");
285: * c.setRequestProperty("User-Agent",
286: * "Profile/MIDP-2.0 Configuration/CLDC-1.0");
287: * c.setRequestProperty("Content-Language", "en-US");
288: *
289: * // Getting the output stream may flush the headers
290: * os = c.openOutputStream();
291: * os.write("LIST games\n".getBytes());
292: * os.flush(); // Optional, getResponseCode will flush
293: *
294: * // Getting the response code will open the connection,
295: * // send the request, and read the HTTP response headers.
296: * // The headers are stored until requested.
297: * rc = c.getResponseCode();
298: * if (rc != HttpConnection.HTTP_OK) {
299: * throw new IOException("HTTP response code: " + rc);
300: * }
301: *
302: * is = c.openInputStream();
303: *
304: * // Get the ContentType
305: * String type = c.getType();
306: * processType(type);
307: *
308: * // Get the length and process the data
309: * int len = (int)c.getLength();
310: * if (len > 0) {
311: * int actual = 0;
312: * int bytesread = 0 ;
313: * byte[] data = new byte[len];
314: * while ((bytesread != len) && (actual != -1)) {
315: * actual = is.read(data, bytesread, len - bytesread);
316: * bytesread += actual;
317: * }
318: * process(data);
319: * } else {
320: * int ch;
321: * while ((ch = is.read()) != -1) {
322: * process((byte)ch);
323: * }
324: * }
325: * } catch (ClassCastException e) {
326: * throw new IllegalArgumentException("Not an HTTP URL");
327: * } finally {
328: * if (is != null)
329: * is.close();
330: * if (os != null)
331: * os.close();
332: * if (c != null)
333: * c.close();
334: * }
335: * }
336: * </pre>
337: * <hr>
338: * <p>
339: * <STRONG>Simplified Stream Methods on Connector</STRONG>
340: * <p>
341: * Please note the following: The
342: * <code>Connector</code> class defines the following
343: * convenience methods for retrieving an input or output stream directly
344: * for a specified URL:
345: *
346: * <UL>
347: * <LI> <CODE> InputStream openInputStream(String url) </CODE>
348: * <LI> <CODE> DataInputStream openDataInputStream(String url) </CODE>
349: * <LI> <CODE> OutputStream openOutputStream(String url) </CODE>
350: * <LI> <CODE> DataOutputStream openDataOutputStream(String url) </CODE>
351: * </UL>
352: *
353: * Please be aware that using these methods implies certain restrictions.
354: * You will not get a reference to the actual connection, but rather just
355: * references to the input or output stream of the connection. Not having
356: * a reference to the connection means that you will not be able to manipulate
357: * or query the connection directly. This in turn means that you will not
358: * be able to call any of the following methods:
359: *
360: * <UL>
361: * <LI> <CODE> getRequestMethod() </CODE>
362: * <LI> <CODE> setRequestMethod() </CODE>
363: * <LI> <CODE> getRequestProperty() </CODE>
364: * <LI> <CODE> setRequestProperty() </CODE>
365: * <LI> <CODE> getLength() </CODE>
366: * <LI> <CODE> getType() </CODE>
367: * <LI> <CODE> getEncoding() </CODE>
368: * <LI> <CODE> getHeaderField() </CODE>
369: * <LI> <CODE> getResponseCode() </CODE>
370: * <LI> <CODE> getResponseMessage() </CODE>
371: * <LI> <CODE> getHeaderFieldInt</CODE>
372: * <LI> <CODE> getHeaderFieldDate</CODE>
373: * <LI> <CODE> getExpiration</CODE>
374: * <LI> <CODE> getDate</CODE>
375: * <LI> <CODE> getLastModified</CODE>
376: * <LI> <CODE> getHeaderField</CODE>
377: * <LI> <CODE> getHeaderFieldKey</CODE>
378: * </UL>
379: * @since MIDP 1.0
380: */
381:
382: public interface HttpConnection extends ContentConnection {
383: /** HTTP Head method. */
384: public final static String HEAD = "HEAD";
385: /** HTTP Get method. */
386: public final static String GET = "GET";
387: /** HTTP Post method. */
388: public final static String POST = "POST";
389:
390: /** 2XX: generally "OK" */
391: /** 200: The request has succeeded. */
392: public static final int HTTP_OK = 200;
393:
394: /**
395: * 201: The request has been fulfilled and resulted in a new
396: * resource being created.
397: */
398: public static final int HTTP_CREATED = 201;
399:
400: /**
401: * 202: The request has been accepted for processing, but the processing
402: * has not been completed.
403: */
404: public static final int HTTP_ACCEPTED = 202;
405:
406: /**
407: * 203: The returned meta-information in the entity-header is not the
408: * definitive set as available from the origin server.
409: */
410: public static final int HTTP_NOT_AUTHORITATIVE = 203;
411:
412: /**
413: * 204: The server has fulfilled the request but does not need to
414: * return an entity-body, and might want to return updated
415: * meta-information.
416: */
417: public static final int HTTP_NO_CONTENT = 204;
418:
419: /**
420: * 205: The server has fulfilled the request and the user agent SHOULD reset
421: * the document view which caused the request to be sent.
422: */
423: public static final int HTTP_RESET = 205;
424:
425: /**
426: * 206: The server has fulfilled the partial GET request for the resource.
427: */
428: public static final int HTTP_PARTIAL = 206;
429:
430: /** 3XX: relocation/redirect */
431:
432: /**
433: * 300: The requested resource corresponds to any one of a set of
434: * representations, each with its own specific location, and agent-
435: * driven negotiation information is being provided so that
436: * the user (or user agent) can select a preferred representation and
437: * redirect its request to that location.
438: */
439: public static final int HTTP_MULT_CHOICE = 300;
440:
441: /**
442: * 301: The requested resource has been assigned a new permanent URI and
443: * any future references to this resource SHOULD use one of the returned
444: * URIs.
445: */
446: public static final int HTTP_MOVED_PERM = 301;
447:
448: /**
449: * 302: The requested resource resides temporarily under a
450: * different URI. (<strong>Note:</strong> the name of this
451: * status code
452: * reflects the earlier publication of RFC2068, which
453: * was changed in RFC2616 from "moved temporarily" to
454: * "found". The semantics were not changed. The <code>Location</code>
455: * header indicates where the application should resend
456: * the request.)
457: */
458: public static final int HTTP_MOVED_TEMP = 302;
459:
460: /**
461: * 303: The response to the request can be found under a different URI and
462: * SHOULD be retrieved using a GET method on that resource.
463: */
464: public static final int HTTP_SEE_OTHER = 303;
465:
466: /**
467: * 304: If the client has performed a conditional GET request and access is
468: * allowed, but the document has not been modified, the server SHOULD
469: * respond with this status code.
470: */
471: public static final int HTTP_NOT_MODIFIED = 304;
472:
473: /**
474: * 305: The requested resource MUST be accessed through the proxy given by
475: * the Location field.
476: */
477: public static final int HTTP_USE_PROXY = 305;
478:
479: /**
480: * 307: The requested resource resides temporarily under a different
481: * URI.
482: */
483: public static final int HTTP_TEMP_REDIRECT = 307;
484:
485: /** 4XX: client error */
486: /**
487: * 400: The request could not be understood by the server due to malformed
488: * syntax.
489: */
490: public static final int HTTP_BAD_REQUEST = 400;
491:
492: /**
493: * 401: The request requires user authentication. The response MUST
494: * include a WWW-Authenticate header field containing a challenge
495: * applicable to the requested resource.
496: */
497: public static final int HTTP_UNAUTHORIZED = 401;
498:
499: /** 402: This code is reserved for future use. */
500: public static final int HTTP_PAYMENT_REQUIRED = 402;
501:
502: /**
503: * 403: The server understood the request, but is refusing to fulfill it.
504: * Authorization will not help and the request SHOULD NOT be repeated.
505: */
506: public static final int HTTP_FORBIDDEN = 403;
507:
508: /**
509: * 404: The server has not found anything matching the Request-URI. No
510: * indication is given of whether the condition is temporary or
511: * permanent.
512: */
513: public static final int HTTP_NOT_FOUND = 404;
514:
515: /**
516: * 405: The method specified in the Request-Line is not allowed for the
517: * resource identified by the Request-URI.
518: */
519: public static final int HTTP_BAD_METHOD = 405;
520:
521: /**
522: * 406: The resource identified by the request is only capable of generating
523: * response entities which have content characteristics not acceptable
524: * according to the accept headers sent in the request.
525: */
526: public static final int HTTP_NOT_ACCEPTABLE = 406;
527:
528: /**
529: * 407: This code is similar to 401 (Unauthorized), but indicates that the
530: * client must first authenticate itself with the proxy.
531: */
532: public static final int HTTP_PROXY_AUTH = 407;
533:
534: /**
535: * 408: The client did not produce a request within the time that the server
536: * was prepared to wait. The client MAY repeat the request without
537: * modifications at any later time.
538: */
539: public static final int HTTP_CLIENT_TIMEOUT = 408;
540:
541: /**
542: * 409: The request could not be completed due to a conflict with
543: * the current state of the resource.
544: */
545: public static final int HTTP_CONFLICT = 409;
546:
547: /**
548: * 410: The requested resource is no longer available at the server and no
549: * forwarding address is known.
550: */
551: public static final int HTTP_GONE = 410;
552:
553: /**
554: * 411: The server refuses to accept the request without a defined Content-
555: * Length.
556: */
557: public static final int HTTP_LENGTH_REQUIRED = 411;
558:
559: /**
560: * 412: The precondition given in one or more of the request-header fields
561: * evaluated to false when it was tested on the server.
562: */
563: public static final int HTTP_PRECON_FAILED = 412;
564:
565: /**
566: * 413: The server is refusing to process a request because the request
567: * entity is larger than the server is willing or able to process.
568: */
569: public static final int HTTP_ENTITY_TOO_LARGE = 413;
570:
571: /**
572: * 414: The server is refusing to service the request because the
573: * Request-URI is longer than the server is willing to interpret.
574: */
575: public static final int HTTP_REQ_TOO_LONG = 414;
576:
577: /**
578: * 415: The server is refusing to service the request because the entity of
579: * the request is in a format not supported by the requested resource
580: * for the requested method.
581: */
582: public static final int HTTP_UNSUPPORTED_TYPE = 415;
583:
584: /**
585: * 416: A server SHOULD return a response with this status code if a request
586: * included a Range request-header field , and none of
587: * the range-specifier values in this field overlap the current extent
588: * of the selected resource, and the request did not include an If-Range
589: * request-header field.
590: */
591: public static final int HTTP_UNSUPPORTED_RANGE = 416;
592:
593: /**
594: * 417: The expectation given in an Expect request-header field
595: * could not be met by this server, or, if the server is a proxy,
596: * the server has unambiguous evidence that the request could not be met
597: * by the next-hop server.
598: */
599: public static final int HTTP_EXPECT_FAILED = 417;
600:
601: /** 5XX: server error */
602: /**
603: * 500: The server encountered an unexpected condition which prevented it
604: * from fulfilling the request.
605: */
606: public static final int HTTP_INTERNAL_ERROR = 500;
607:
608: /**
609: * 501: The server does not support the functionality required to
610: * fulfill the request.
611: */
612: public static final int HTTP_NOT_IMPLEMENTED = 501;
613:
614: /**
615: * 502: The server, while acting as a gateway or proxy, received an invalid
616: * response from the upstream server it accessed in attempting to
617: * fulfill the request.
618: */
619: public static final int HTTP_BAD_GATEWAY = 502;
620:
621: /**
622: * 503: The server is currently unable to handle the request due to a
623: * temporary overloading or maintenance of the server.
624: */
625: public static final int HTTP_UNAVAILABLE = 503;
626:
627: /**
628: * 504: The server, while acting as a gateway or proxy, did not receive a
629: * timely response from the upstream server specified by the URI
630: * or some other auxiliary server it needed
631: * to access in attempting to complete the request.
632: */
633: public static final int HTTP_GATEWAY_TIMEOUT = 504;
634:
635: /**
636: * 505: The server does not support, or refuses to support, the HTTP
637: * protocol version that was used in the request message.
638: */
639: public static final int HTTP_VERSION = 505;
640:
641: /**
642: * Return a string representation of the URL for this connection.
643: *
644: * @return the string representation of the URL for this connection.
645: */
646: public String getURL();
647:
648: /**
649: * Returns the protocol name of the URL of this
650: * <code>HttpConnection</code>. e.g., http or https
651: *
652: * @return the protocol of the URL of this <code>HttpConnection</code>.
653: */
654: public String getProtocol();
655:
656: /**
657: * Returns the host information of the URL of
658: * this <code>HttpConnection</code>. e.g. host name or IPv4 address
659: *
660: * @return the host information of the URL of
661: * this <code>HttpConnection</code>.
662: */
663: public String getHost();
664:
665: /**
666: * Returns the file portion of the URL of this <code>HttpConnection</code>.
667: *
668: * @return the file portion of the URL of this <code>HttpConnection</code>.
669: * <code>null</code> is returned if there is no file.
670: */
671: public String getFile();
672:
673: /**
674: * Returns the ref portion of the URL of this <code>HttpConnection</code>.
675: * RFC2396 specifies the optional fragment identifier as the
676: * the text after the crosshatch (#) character in the URL.
677: * This information may be used by the user agent as additional
678: * reference information after the resource is successfully retrieved.
679: * The format and interpretation of the fragment identifier is dependent
680: * on the media type[RFC2046] of the retrieved information.
681: *
682: * @return the ref portion of the URL of this <code>HttpConnection</code>.
683: * <code>null</code> is returned if there is no value.
684: */
685: public String getRef();
686:
687: /**
688: * Returns the query portion of the URL of this
689: * <code>HttpConnection</code>.
690: *
691: * RFC2396 defines the query component as the text after the first
692: * question-mark (?) character in the URL.
693: *
694: * @return the query portion of the URL of this
695: * <code>HttpConnection</code>.
696: * <code>null</code> is returned if there is no value. */
697: public String getQuery();
698:
699: /**
700: * Returns the network port number of the URL for this
701: * <code>HttpConnection</code>.
702: *
703: * @return the network port number of the URL for this
704: * <code>HttpConnection</code>.
705: * The default HTTP port number (80) is returned if there was
706: * no port number in the string passed to <code>Connector.open</code>.
707: */
708: public int getPort();
709:
710: /**
711: * Get the current request method. e.g. HEAD, GET, POST
712: * The default value is GET.
713: * @return the HTTP request method
714: * @see #setRequestMethod
715: */
716: public String getRequestMethod();
717:
718: /**
719: * Set the method for the URL request, one of:
720: * <UL>
721: * <LI>GET
722: * <LI>POST
723: * <LI>HEAD
724: * </UL> are legal, subject to protocol restrictions. The default
725: * method is GET.
726: *
727: * @param method the HTTP method
728: * @exception IOException if the method cannot be reset or if
729: * the requested method isn't valid for HTTP.
730: * @see #getRequestMethod
731: */
732: public void setRequestMethod(String method) throws IOException;
733:
734: /**
735: * Returns the value of the named general request property for this
736: * connection.
737: *
738: * @param key the keyword by which the request property is
739: * known (e.g., "accept").
740: * @return the value of the named general request property for this
741: * connection. If there is no key with the specified name then
742: * <CODE>null</CODE> is returned.
743: * @see #setRequestProperty
744: */
745: public String getRequestProperty(String key);
746:
747: /**
748: * Sets the general request property. If a property with the key already
749: * exists, overwrite its value with the new value.
750: *
751: * <p> <strong>Note:</strong> HTTP requires all request properties
752: * which can legally have multiple instances with the same key
753: * to use a comma-separated list syntax which enables multiple
754: * properties to be appended into a single property.
755: *
756: * @param key the keyword by which the request is known
757: * (e.g., "<code>accept</code>").
758: * @param value the value associated with it.
759: * @exception IOException is thrown if the connection is in the
760: * connected state.
761: * @see #getRequestProperty
762: */
763: public void setRequestProperty(String key, String value)
764: throws IOException;
765:
766: /**
767: * Returns the HTTP response status code.
768: * It parses responses like:
769: * <PRE>
770: * HTTP/1.0 200 OK
771: * HTTP/1.0 401 Unauthorized
772: * </PRE>
773: * and extracts the ints 200 and 401 respectively.
774: * from the response (i.e., the response is not valid HTTP).
775: * @exception IOException if an error occurred connecting to the server.
776: * @return the HTTP Status-Code or -1 if no status code can be discerned.
777: */
778: public int getResponseCode() throws IOException;
779:
780: /**
781: * Gets the HTTP response message, if any, returned along with the
782: * response code from a server. From responses like:
783: * <PRE>
784: * HTTP/1.0 200 OK
785: * HTTP/1.0 404 Not Found
786: * </PRE>
787: * Extracts the Strings "OK" and "Not Found" respectively.
788: * Returns null if none could be discerned from the responses
789: * (the result was not valid HTTP).
790: * @exception IOException if an error occurred connecting to the server.
791: * @return the HTTP response message, or <code>null</code>
792: */
793: public String getResponseMessage() throws IOException;
794:
795: /**
796: * Returns the value of the <code>expires</code> header field.
797: *
798: * @return the expiration date of the resource that this URL references,
799: * or 0 if not known. The value is the number of milliseconds
800: * since January 1, 1970 GMT.
801: * @exception IOException if an error occurred connecting to the server.
802: */
803: public long getExpiration() throws IOException;
804:
805: /**
806: * Returns the value of the <code>date</code> header field.
807: *
808: * @return the sending date of the resource that the URL references,
809: * or <code>0</code> if not known. The value returned is the
810: * number of milliseconds since January 1, 1970 GMT.
811: * @exception IOException if an error occurred connecting to the server.
812: */
813: public long getDate() throws IOException;
814:
815: /**
816: * Returns the value of the <code>last-modified</code> header field.
817: * The result is the number of milliseconds since January 1, 1970 GMT.
818: *
819: * @return the date the resource referenced by this
820: * <code>HttpConnection</code> was last modified, or
821: * 0 if not known.
822: * @exception IOException if an error occurred connecting to the server.
823: */
824: public long getLastModified() throws IOException;
825:
826: /**
827: * Returns the value of the named header field.
828: *
829: * @param name of a header field.
830: * @return the value of the named header field, or <code>null</code>
831: * if there is no such field in the header.
832: * @exception IOException if an error occurred connecting to the server.
833: */
834: public String getHeaderField(String name) throws IOException;
835:
836: /**
837: * Returns the value of the named field parsed as a number.
838: * <p>
839: * This form of <code>getHeaderField</code> exists because some
840: * connection types (e.g., <code>http-ng</code>) have pre-parsed
841: * headers. Classes for that connection type can override this method
842: * and short-circuit the parsing.
843: *
844: * @param name the name of the header field.
845: * @param def the default value.
846: * @return the value of the named field, parsed as an integer. The
847: * <code>def</code> value is returned if the field is
848: * missing or malformed.
849: * @exception IOException if an error occurred connecting to the server.
850: */
851: public int getHeaderFieldInt(String name, int def)
852: throws IOException;
853:
854: /**
855: * Returns the value of the named field parsed as date.
856: * The result is the number of milliseconds since January 1, 1970 GMT
857: * represented by the named field.
858: * <p>
859: * This form of <code>getHeaderField</code> exists because some
860: * connection types (e.g., <code>http-ng</code>) have pre-parsed
861: * headers. Classes for that connection type can override this method
862: * and short-circuit the parsing.
863: *
864: * @param name the name of the header field.
865: * @param def a default value.
866: * @return the value of the field, parsed as a date. The value of the
867: * <code>def</code> argument is returned if the field is
868: * missing or malformed.
869: * @exception IOException if an error occurred connecting to the server.
870: */
871: public long getHeaderFieldDate(String name, long def)
872: throws IOException;
873:
874: /**
875: * Gets a header field value by index.
876: *
877: * @return the value of the nth header field or
878: * <code>null</code> if the array index is out of range.
879: * An empty String is returned if the field does not have a value.
880: * @param n the index of the header field
881: * @exception IOException if an error occurred connecting to the server.
882: */
883: public String getHeaderField(int n) throws IOException;
884:
885: /**
886: * Gets a header field key by index.
887: *
888: * @return the key of the nth header field or
889: * <code>null</code> if the array index is out of range.
890: * @param n the index of the header field
891: * @exception IOException if an error occurred connecting to the server.
892: */
893: public String getHeaderFieldKey(int n) throws IOException;
894:
895: }
|