001 /*
002 * Copyright 1999,2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package org.apache.commons.feedparser.network;
018
019 import java.io.IOException;
020 import java.io.InputStream;
021 import java.io.OutputStream;
022 import java.util.Iterator;
023
024 /**
025 * A ResourceRequest is a generic interface to a network resource such as an
026 * HTTP URL.
027 *
028 * @author <a href="mailto:burton@openprivacy.org">Kevin A. Burton</a>
029 * @version $Id: ResourceRequest.java 373622 2006-01-30 22:53:00Z mvdb $
030 */
031 public interface ResourceRequest {
032
033 /**
034 * Perform all initialization and connection to the remote server. This
035 * should always be called BEFORE network getInputStream() if you want to
036 * perform other operations first. When using a HEAD request this must be
037 * used and not getInputStream()
038 *
039 *
040 */
041 public void init() throws IOException;
042
043 /**
044 * Get an input stream for this content.
045 *
046 *
047 */
048 public InputStream getInputStream() throws IOException;
049
050 /**
051 * Set the resource for this request.
052 *
053 *
054 */
055 public String getResource();
056 public void setResource( String resource );
057
058 /**
059 * Get the resource but make sure all redirects are taken into
060 * consideration.
061 *
062 *
063 */
064 public String getResourceFromRedirect();
065
066 /**
067 * Get the given Input Stream as a String by calling read() until we have
068 * all the data locally.
069 *
070 *
071 */
072 public String getInputStreamAsString() throws IOException;
073 public byte[] getInputStreamAsByteArray() throws IOException;
074 public InputStream getLocalInputStream() throws NetworkException;
075 public byte[] getLocalInputStreamAsByteArray() throws IOException;
076
077 /**
078 * When true we cache getLocalInputStream() so that multiple requests are
079 * returned from local data. Provides more flexibility but uses more
080 * memory.
081 */
082 public void setLocalCache( boolean v );
083
084 /**
085 * Copy this input stream to an OutputStream
086 *
087 *
088 */
089 public void toOutputStream( OutputStream out ) throws IOException;
090
091 /**
092 * Set the If-Modified-Since header for HTTP URL connections and protocols
093 * that support similar operation.
094 *
095 * A value of -1 means do not use the If-Modified-Since header
096 *
097 * Fri Jun 06 2003 08:34 PM (burton@peerfear.org): Currently just URLResourceRequest
098 *
099 *
100 */
101 public long getIfModifiedSince();
102 public void setIfModifiedSince( long ifModifiedSince );
103
104 /**
105 * The HTTP ETag to use with If-None-Match
106 *
107 *
108 */
109 public String getEtag();
110 public void setEtag( String etag );
111
112 /**
113 * Get and set an HTTP style response code. Only used with HTTP URLs.
114 *
115 *
116 */
117 public long getResponseCode();
118 public void setResponseCode( int responseCode );
119
120 /**
121 * Return the conent length of this request or -1 if not known.
122 *
123 *
124 */
125 public int getContentLength() throws IOException;
126
127 public void setEventListener( NetworkEventListener eventListener );
128
129 /**
130 * Get a given response header.
131 *
132 *
133 */
134 public String getHeaderField( String name );
135
136 /**
137 * Set a given request header such as UserAgent, ETag, etc.
138 *
139 *
140 */
141 public void setRequestHeaderField( String name, String value );
142
143 /**
144 * Get the names of all set request headers.
145 *
146 *
147 */
148 public Iterator getRequestHeaderFields();
149
150 public String getRequestHeaderField( String name );
151
152 public void setRequestMethod( String method ) throws NetworkException;
153
154 public boolean getFollowRedirects();
155 public void setFollowRedirects( boolean v );
156
157 }