| <?xml version="1.0"?> |
| <!-- |
| /* |
| * Copyright 2001-2004 The Apache Software Foundation. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| --> |
| |
| <document> |
| |
| <properties> |
| <title>Turbine Services - Upload Service</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Upload Service"> |
| |
| <p> |
| The Upload Service handles the parsing of multi-part/form-data from POST |
| Requests, making the multi-part files available from either memory or from a |
| specified location on the file system. |
| </p> |
| |
| </section> |
| |
| <section name="Configuration"> |
| |
| <source><![CDATA[ |
| # ------------------------------------------------------------------- |
| # |
| # S E R V I C E S |
| # |
| # ------------------------------------------------------------------- |
| # Classes for Turbine Services should be defined here. |
| # Format: services.[name].classname=[implementing class] |
| # |
| # To specify properties of a service use the following syntax: |
| # service.[name].[property]=[value] |
| |
| services.UploadService.classname=org.apache.turbine.services.upload.TurbineUploadService |
| . |
| . |
| . |
| # ------------------------------------------------------------------- |
| # |
| # U P L O A D S E R V I C E |
| # |
| # ------------------------------------------------------------------- |
| |
| # Whether the files should be automatically picked up by |
| # ParameterParser. |
| |
| services.UploadService.automatic=false |
| |
| # |
| # The directory where files will be temporarily stored. |
| # |
| services.UploadService.repository=. |
| |
| # |
| # The maximum size of a request that will be processed. |
| # |
| services.UploadService.size.max=1048576 |
| |
| # |
| # The maximum size of a request that will have it's elements cached in |
| # memory by TurbineUploadService class. |
| # |
| services.UploadService.size.threshold=10240 |
| ]]></source> |
| |
| </section> |
| |
| <section name="Usage"> |
| |
| <p> |
| Change the automatic directive to true. With this set to true any |
| multi-part/form-data requests which Turbine fields, will be parsed and the |
| appropriate files made available to ParameterParser as FileItem objects. If |
| this is set as false, the FileItems will have to be parsed out of RunData |
| manually with the method getRequest() available from TurbineUpload. |
| </p> |
| |
| <p> |
| Set the remaining values to ones approriate for your installation. On Win32 |
| file systems for the repository directive, an entry of the form: |
| <ul> |
| <code>f:\path\to\upload\repository</code> |
| </ul> |
| is most likely necessary. |
| </p> |
| |
| |
| <p> |
| Create an HTML form of the type: |
| </p> |
| |
| <source test=""><![CDATA[ |
| |
| <form enctype="multipart/form-data" method="POST"> |
| <input type="hidden" name="action" value="UploadExample" /> |
| <input type="file" name="filename"> |
| <input type="submit" value="upload" /> |
| </form> |
| |
| ]]></source> |
| |
| <p> |
| The Upload Service manages if the FileItem is stored in Memory or in the |
| Repository specified in TurbineReources.properties. It is also possible to |
| overide the TurbineResources setting for the repository by using |
| TurbineUpload.getRequest() to parse the request with a custom repository |
| directory. The TurbineUpload object serves as a Facade to the Upload Service |
| by making available static methods to manage the upload internally in your |
| application. The FileItems can be accessed in an UploadExample Action class by: |
| </p> |
| |
| <source test=""><![CDATA[ |
| public void doPerform(RunData data, Context context) throws Exception |
| { |
| //get the ParameterParser from RunData |
| ParameterParser params = data.getParameters(); |
| |
| //grab the FileItems available in ParameterParser |
| FileItem fi = params.getFileItem("filename"); |
| |
| //do work on the FileItem |
| //get the file as a File |
| //or outputstream etc. |
| |
| } |
| |
| ]]></source> |
| |
| <p> |
| Once a new instance of the FileItem is created many public methods are |
| available to work on the object, whether it is in temporary storage as memory or as |
| a temporary file on part of the file system. All the temporary storage management and |
| clean up occurs behind the scenes and is transparent to the application being |
| based on Turbine. There is no need to manually clean up the FileItems as the |
| FileItem object doesn't span Requests ( or RunData instances ) and the temporary |
| files that use the file system are cleaned up in a finalize() method inherited |
| from Object(). |
| </p> |
| |
| <p> |
| The TurbineUpload object and the FileItem object give all the functionality |
| needed to manage this sort of operation or action at the application level. |
| For more detailed information on the methods available to deal with uploaded |
| files, view the relevant Javadocs for TurbineUpload, ParameterParser and |
| FileItem. |
| </p> |
| |
| </section> |
| |
| </body> |
| </document> |
