View Javadoc

1   /*
2    * Copyright 1999,2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.apache.commons.feedparser.network;
18  
19  import java.io.IOException;
20  import java.io.InputStream;
21  import java.io.OutputStream;
22  import java.util.Iterator;
23  
24  /**
25   * A ResourceRequest is a generic interface to a network resource such as an
26   * HTTP URL.
27   * 
28   * @author <a href="mailto:burton@openprivacy.org">Kevin A. Burton</a>
29   * @version $Id: ResourceRequest.java 373622 2006-01-30 22:53:00Z mvdb $
30   */
31  public interface ResourceRequest {
32  
33      /**
34       * Perform all initialization and connection to the remote server.  This
35       * should always be called BEFORE network getInputStream() if you want to
36       * perform other operations first.  When using a HEAD request this must be
37       * used and not getInputStream()
38       *
39       * 
40       */
41      public void init() throws IOException;
42      
43      /**
44       * Get an input stream for this content.
45       *
46       * 
47       */
48      public InputStream getInputStream() throws IOException;
49  
50      /**
51       * Set the resource for this request.
52       *
53       * 
54       */
55      public String getResource();
56      public void setResource( String resource );
57  
58      /**
59       * Get the resource but make sure all redirects are taken into
60       * consideration.
61       *
62       * 
63       */
64      public String getResourceFromRedirect();
65      
66      /**
67       * Get the given Input Stream as a String by calling read() until we have
68       * all the data locally.
69       *
70       * 
71       */
72      public String getInputStreamAsString() throws IOException;
73      public byte[] getInputStreamAsByteArray() throws IOException;
74      public InputStream getLocalInputStream() throws NetworkException;
75      public byte[] getLocalInputStreamAsByteArray() throws IOException;
76  
77      /**
78       * When true we cache getLocalInputStream() so that multiple requests are
79       * returned from local data.  Provides more flexibility but uses more
80       * memory.
81       */
82      public void setLocalCache( boolean v );
83  
84      /**
85       * Copy this input stream to an OutputStream
86       *
87       * 
88       */
89      public void toOutputStream( OutputStream out ) throws IOException;
90  
91      /**
92       * Set the If-Modified-Since header for HTTP URL connections and protocols
93       * that support similar operation.
94       *
95       * A value of -1 means do not use the If-Modified-Since header
96       *
97       * Fri Jun 06 2003 08:34 PM (burton@peerfear.org): Currently just URLResourceRequest     
98       *
99       * 
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 }