001    // Copyright 2004, 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry.request;
016    
017    import java.io.File;
018    import java.io.InputStream;
019    
020    /**
021     * Represents a file uploaded from a client side form.
022     * 
023     * @author Howard Lewis Ship
024     * @since 1.0.8
025     */
026    
027    public interface IUploadFile
028    {
029    
030        /**
031         * Returns the name of the file that was uploaded. This is just the filename
032         * portion of the complete path.
033         */
034    
035        String getFileName();
036    
037        /**
038         * Returns the complete path, as reported by the client browser. Different
039         * browsers report different things here.
040         * 
041         * @since 2.0.4
042         */
043    
044        String getFilePath();
045    
046        /**
047         * Returns an input stream of the content of the file. There is no guarantee
048         * that this stream will be valid after the end of the current request
049         * cycle, so it should be processed immediately.
050         * <p>
051         * As of release 1.0.8, this will be a a
052         * {@link java.io.ByteArrayInputStream}, but that, too, may change (a
053         * future implementation may upload the stream to a temporary file and
054         * return an input stream from that).
055         */
056    
057        InputStream getStream();
058    
059        /**
060         * Returns the MIME type specified when the file was uploaded. May return
061         * null if the content type is not known.
062         * 
063         * @since 2.2
064         */
065    
066        String getContentType();
067    
068        /**
069         * Writes the content of the file to a known location. This should be
070         * invoked at most once. In a standard implementation based on Jakarta
071         * FileUpload, this will often be implemented efficiently as a file rename.
072         * 
073         * @since 3.0
074         */
075    
076        void write(File file);
077    
078        /**
079         * Returns true if the uploaded content is in memory. False generally means
080         * the content is stored in a temporary file.
081         */
082    
083        boolean isInMemory();
084    
085        /**
086         * Returns the size, in bytes, of the uploaded content.
087         * 
088         * @since 3.0
089         */
090    
091        long getSize();
092    }