View Javadoc

1   /*
2    * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/methods/multipart/FilePart.java,v 1.19 2004/04/18 23:51:37 jsdever Exp $
3    * $Revision: 155418 $
4    * $Date: 2005-02-26 08:01:52 -0500 (Sat, 26 Feb 2005) $
5    *
6    * ====================================================================
7    *
8    *  Copyright 2002-2004 The Apache Software Foundation
9    *
10   *  Licensed under the Apache License, Version 2.0 (the "License");
11   *  you may not use this file except in compliance with the License.
12   *  You may obtain a copy of the License at
13   *
14   *      http://www.apache.org/licenses/LICENSE-2.0
15   *
16   *  Unless required by applicable law or agreed to in writing, software
17   *  distributed under the License is distributed on an "AS IS" BASIS,
18   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19   *  See the License for the specific language governing permissions and
20   *  limitations under the License.
21   * ====================================================================
22   *
23   * This software consists of voluntary contributions made by many
24   * individuals on behalf of the Apache Software Foundation.  For more
25   * information on the Apache Software Foundation, please see
26   * <http://www.apache.org/>.
27   *
28   */
29  
30  package org.apache.commons.httpclient.methods.multipart;
31  
32  import java.io.File;
33  import java.io.FileNotFoundException;
34  import java.io.IOException;
35  import java.io.InputStream;
36  import java.io.OutputStream;
37  import org.apache.commons.httpclient.util.EncodingUtil;
38  import org.apache.commons.logging.Log;
39  import org.apache.commons.logging.LogFactory;
40  
41  /***
42   * This class implements a part of a Multipart post object that
43   * consists of a file.  
44   *
45   * @author <a href="mailto:mattalbright@yahoo.com">Matthew Albright</a>
46   * @author <a href="mailto:jsdever@apache.org">Jeff Dever</a>
47   * @author <a href="mailto:adrian@ephox.com">Adrian Sutton</a>
48   * @author <a href="mailto:becke@u.washington.edu">Michael Becke</a>
49   * @author <a href="mailto:mdiggory@latte.harvard.edu">Mark Diggory</a>
50   * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
51   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
52   *   
53   * @since 2.0 
54   *
55   */
56  public class FilePart extends PartBase {
57  
58      /*** Default content encoding of file attachments. */
59      public static final String DEFAULT_CONTENT_TYPE = "application/octet-stream";
60  
61      /*** Default charset of file attachments. */
62      public static final String DEFAULT_CHARSET = "ISO-8859-1";
63  
64      /*** Default transfer encoding of file attachments. */
65      public static final String DEFAULT_TRANSFER_ENCODING = "binary";
66  
67      /*** Log object for this class. */
68      private static final Log LOG = LogFactory.getLog(FilePart.class);
69  
70      /*** Attachment's file name */
71      protected static final String FILE_NAME = "; filename=";
72  
73      /*** Attachment's file name as a byte array */
74      protected static final byte[] FILE_NAME_BYTES = 
75          EncodingUtil.getAsciiBytes(FILE_NAME);
76  
77      /*** Source of the file part. */
78      private PartSource source;
79  
80      /***
81       * FilePart Constructor.
82       *
83       * @param name the name for this part
84       * @param partSource the source for this part
85       * @param contentType the content type for this part, if <code>null</code> the 
86       * {@link #DEFAULT_CONTENT_TYPE default} is used
87       * @param charset the charset encoding for this part, if <code>null</code> the 
88       * {@link #DEFAULT_CHARSET default} is used
89       */
90      public FilePart(String name, PartSource partSource, String contentType, String charset) {
91          
92          super(
93              name, 
94              contentType == null ? DEFAULT_CONTENT_TYPE : contentType, 
95              charset == null ? "ISO-8859-1" : charset, 
96              DEFAULT_TRANSFER_ENCODING
97          );
98  
99          if (partSource == null) {
100             throw new IllegalArgumentException("Source may not be null");
101         }
102         if (partSource.getLength() < 0) {
103             throw new IllegalArgumentException("Source length must be >= 0");
104         }
105         this.source = partSource;
106     }
107         
108     /***
109      * FilePart Constructor.
110      *
111      * @param name the name for this part
112      * @param partSource the source for this part
113      */
114     public FilePart(String name, PartSource partSource) {
115         this(name, partSource, null, null);
116     }
117 
118     /***
119      * FilePart Constructor.
120      *
121      * @param name the name of the file part
122      * @param file the file to post
123      *
124      * @throws FileNotFoundException if the <i>file</i> is not a normal
125      * file or if it is not readable.
126      */
127     public FilePart(String name, File file) 
128     throws FileNotFoundException {
129         this(name, new FilePartSource(file), null, null);
130     }
131 
132     /***
133      * FilePart Constructor.
134      *
135      * @param name the name of the file part
136      * @param file the file to post
137      * @param contentType the content type for this part, if <code>null</code> the 
138      * {@link #DEFAULT_CONTENT_TYPE default} is used
139      * @param charset the charset encoding for this part, if <code>null</code> the 
140      * {@link #DEFAULT_CHARSET default} is used
141      *
142      * @throws FileNotFoundException if the <i>file</i> is not a normal
143      * file or if it is not readable.
144      */
145     public FilePart(String name, File file, String contentType, String charset) 
146     throws FileNotFoundException {
147         this(name, new FilePartSource(file), contentType, charset);
148     }
149 
150      /***
151      * FilePart Constructor.
152      *
153      * @param name the name of the file part
154      * @param fileName the file name 
155      * @param file the file to post
156      *
157      * @throws FileNotFoundException if the <i>file</i> is not a normal
158      * file or if it is not readable.
159      */
160     public FilePart(String name, String fileName, File file) 
161     throws FileNotFoundException {
162         this(name, new FilePartSource(fileName, file), null, null);
163     }
164     
165      /***
166      * FilePart Constructor.
167      *
168      * @param name the name of the file part
169      * @param fileName the file name 
170      * @param file the file to post
171      * @param contentType the content type for this part, if <code>null</code> the 
172      * {@link #DEFAULT_CONTENT_TYPE default} is used
173      * @param charset the charset encoding for this part, if <code>null</code> the 
174      * {@link #DEFAULT_CHARSET default} is used
175      *
176      * @throws FileNotFoundException if the <i>file</i> is not a normal
177      * file or if it is not readable.
178      */
179     public FilePart(String name, String fileName, File file, String contentType, String charset) 
180     throws FileNotFoundException {
181         this(name, new FilePartSource(fileName, file), contentType, charset);
182     }
183     
184     /***
185      * Write the disposition header to the output stream
186      * @param out The output stream
187      * @throws IOException If an IO problem occurs
188      * @see Part#sendDispositionHeader(OutputStream)
189      */
190     protected void sendDispositionHeader(OutputStream out) 
191     throws IOException {
192         LOG.trace("enter sendDispositionHeader(OutputStream out)");
193         super.sendDispositionHeader(out);
194         String filename = this.source.getFileName();
195         if (filename != null) {
196             out.write(FILE_NAME_BYTES);
197             out.write(QUOTE_BYTES);
198             out.write(EncodingUtil.getAsciiBytes(filename));
199             out.write(QUOTE_BYTES);
200         }
201     }
202     
203     /***
204      * Write the data in "source" to the specified stream.
205      * @param out The output stream.
206      * @throws IOException if an IO problem occurs.
207      * @see org.apache.commons.httpclient.methods.multipart.Part#sendData(OutputStream)
208      */
209     protected void sendData(OutputStream out) throws IOException {
210         LOG.trace("enter sendData(OutputStream out)");
211         if (lengthOfData() == 0) {
212             
213             // this file contains no data, so there is nothing to send.
214             // we don't want to create a zero length buffer as this will
215             // cause an infinite loop when reading.
216             LOG.debug("No data to send.");
217             return;
218         }
219         
220         byte[] tmp = new byte[4096];
221         InputStream instream = source.createInputStream();
222         try {
223             int len;
224             while ((len = instream.read(tmp)) >= 0) {
225                 out.write(tmp, 0, len);
226             }
227         } finally {
228             // we're done with the stream, close it
229             instream.close();
230         }
231     }
232 
233     /*** 
234      * Returns the source of the file part.
235      *  
236      * @return The source.
237      */
238     protected PartSource getSource() {
239         LOG.trace("enter getSource()");
240         return this.source;
241     }
242 
243     /***
244      * Return the length of the data.
245      * @return The length.
246      * @throws IOException if an IO problem occurs
247      * @see org.apache.commons.httpclient.methods.multipart.Part#lengthOfData()
248      */    
249     protected long lengthOfData() throws IOException {
250         LOG.trace("enter lengthOfData()");
251         return source.getLength();
252     }    
253 
254 }