org.apache.wicket.util.upload.FileItem Maven / Gradle / Ivy
Show all versions of org.ops4j.pax.wicket.service Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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.
*/
package org.apache.wicket.util.upload;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.Serializable;
import java.io.UnsupportedEncodingException;
/**
*
* This class represents a file or form item that was received within a
* multipart/form-data POST request.
*
*
* After retrieving an instance of this class from a
* {@link org.apache.wicket.util.upload.FileUpload FileUpload} instance (see
* {@link org.apache.wicket.util.upload.FileUpload #parseRequest(javax.servlet.http.HttpServletRequest)}
* ), you may either request all contents of the file at once using {@link #get()} or request an
* {@link java.io.InputStream InputStream} with {@link #getInputStream()} and process the file
* without attempting to load it into memory, which may come handy with large files.
*
*
* While this interface does not extend javax.activation.DataSource per se (to avoid a
* seldom used dependency), several of the defined methods are specifically defined with the same
* signatures as methods in that interface. This allows an implementation of this interface to also
* implement javax.activation.DataSource with minimal additional work.
*
* @author Rafal Krzewski
* @author Sean Legassick
* @author Jason van Zyl
* @author Martin Cooper
*/
public interface FileItem extends Serializable
{
// ------------------------------- Methods from javax.activation.DataSource
/**
* Returns an {@link java.io.InputStream InputStream} that can be used to retrieve the contents
* of the file.
*
* @return An {@link java.io.InputStream InputStream} that can be used to retrieve the contents
* of the file.
*
* @throws IOException
* if an error occurs.
*/
InputStream getInputStream() throws IOException;
/**
* Returns the content type passed by the browser or null if not defined.
*
* @return The content type passed by the browser or null if not defined.
*/
String getContentType();
/**
* Returns the original filename in the client's filesystem, as provided by the browser (or
* other client software). In most cases, this will be the base file name, without path
* information. However, some clients, such as the Opera browser, do include path information.
*
* @return The original filename in the client's filesystem.
*/
String getName();
// ------------------------------------------------------- FileItem methods
/**
* Provides a hint as to whether or not the file contents will be read from memory.
*
* @return true if the file contents will be read from memory; false
* otherwise.
*/
boolean isInMemory();
/**
* Returns the size of the file item.
*
* @return The size of the file item, in bytes.
*/
long getSize();
/**
* Returns the contents of the file item as an array of bytes.
*
* @return The contents of the file item as an array of bytes.
*/
byte[] get();
/**
* Returns the contents of the file item as a String, using the specified encoding. This method
* uses {@link #get()} to retrieve the contents of the item.
*
* @param encoding
* The character encoding to use.
*
* @return The contents of the item, as a string.
*
* @throws UnsupportedEncodingException
* if the requested character encoding is not available.
*/
String getString(String encoding) throws UnsupportedEncodingException;
/**
* Returns the contents of the file item as a String, using the default character encoding. This
* method uses {@link #get()} to retrieve the contents of the item.
*
* @return The contents of the item, as a string.
*/
String getString();
/**
* A convenience method to write an uploaded item to disk. The client code is not concerned with
* whether or not the item is stored in memory, or on disk in a temporary location. They just
* want to write the uploaded item to a file.
*
* This method is not guaranteed to succeed if called more than once for the same item. This
* allows a particular implementation to use, for example, file renaming, where possible, rather
* than copying all of the underlying data, thus gaining a significant performance benefit.
*
* @param file
* The File into which the uploaded item should be stored.
*
* @throws Exception
* if an error occurs.
*/
void write(File file) throws Exception;
/**
* Deletes the underlying storage for a file item, including deleting any associated temporary
* disk file. Although this storage will be deleted automatically when the FileItem
* instance is garbage collected, this method can be used to ensure that this is done at an
* earlier time, thus preserving system resources.
*/
void delete();
/**
* Returns the name of the field in the multipart form corresponding to this file item.
*
* @return The name of the form field.
*/
String getFieldName();
/**
* Sets the field name used to reference this file item.
*
* @param name
* The name of the form field.
*/
void setFieldName(String name);
/**
* Determines whether or not a FileItem instance represents a simple form field.
*
* @return true if the instance represents a simple form field; false
* if it represents an uploaded file.
*/
boolean isFormField();
/**
* Specifies whether or not a FileItem instance represents a simple form field.
*
* @param state
* true if the instance represents a simple form field;
* false if it represents an uploaded file.
*/
void setFormField(boolean state);
/**
* Returns an {@link java.io.OutputStream OutputStream} that can be used for storing the
* contents of the file.
*
* @return An {@link java.io.OutputStream OutputStream} that can be used for storing the
* contensts of the file.
*
* @throws IOException
* if an error occurs.
*/
OutputStream getOutputStream() throws IOException;
}