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
015package org.apache.tapestry.request;
016
017import java.io.File;
018import 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
028public interface IUploadFile
029{
030        /**
031         *  Returns the name of the file that was uploaded.  This
032         *  is just the filename portion of the complete path.
033         * 
034         **/
035
036        public String getFileName();
037
038        /**
039         *  Returns the complete path, as reported by the client
040         *  browser.  Different browsers report different things
041         *  here.
042         * 
043         * 
044         *  @since 2.0.4
045         * 
046         **/
047        
048        public String getFilePath();
049
050        /**
051         *  Returns an input stream of the content of the file.  There is no guarantee
052         *  that this stream will be valid after the end of the current request cycle,
053         *  so it should be processed immediately.
054         * 
055         *  <p>As of release 1.0.8, this will be a a {@link java.io.ByteArrayInputStream},
056         *  but that, too, may change (a future implementation may upload the stream
057         *  to a temporary file and return an input stream from that).
058         * 
059         **/
060
061        public InputStream getStream();
062    
063    /**
064     *  Returns the MIME type specified when the file was uploaded.  May return null
065     *  if the content type is not known.
066     * 
067     *  @since 2.2
068     * 
069     **/
070    
071    public String getContentType();
072    
073    /**
074     * Writes the content of the file to a known location.  This should
075     * be invoked at most once.  In a standard
076     * implementation based on Jakarta FileUpload, this will often
077     * be implemented efficiently as a file rename.
078     * 
079     * @since 3.0
080     */
081    
082    public void write(File file);
083    
084    /**
085     * Returns true if the uploaded content is in memory.  False generally
086     * means the content is stored in a temporary file.
087     */
088    
089    public boolean isInMemory();
090    
091    /**
092     * Returns the size, in bytes, of the uploaded content.
093     * 
094     * @since 3.0
095     **/
096    
097    public long getSize(); 
098}