3.0.1: 2011-11-10

net.sf.basedb.core
Class File

java.lang.Object
  extended by net.sf.basedb.core.BasicItem<D>
      extended by net.sf.basedb.core.OwnedItem<D>
          extended by net.sf.basedb.core.SharedItem<D>
              extended by net.sf.basedb.core.CommonItem<FileData>
                  extended by net.sf.basedb.core.File
All Implemented Interfaces:
AccessControlled, Controlled, DiskConsumable, Identifiable, Nameable, Ownable, Removable, Shareable, Subtypable, Transactional, ToTransferable<FileInfo>

public class File
extends CommonItem<FileData>
implements Transactional, DiskConsumable, Subtypable, ToTransferable<FileInfo>

This class is used to represent individual file items and information about them. This item also handels the physical file on disk. It should work as expected, but under very unfortunate circumstances, ie. an error happens during rollback or commit after the changers has been written to the database, it may not delete all files that should be deleted.

Version:
2.0
Author:
enell
Last modified
$Date: 2011-09-06 12:44:53 +0200 (Tue, 06 Sep 2011) $

Nested Class Summary
static class File.Action
          A fileaction describes if a file should be moved to secondary storage or brought back from it.
private  class File.UploadStream
          This class is used for uploading a file.
 
Field Summary
static String ALIGNED_SEQUENCE
          The id for the FileType item representing a file containing aligned sequence data.
private  StreamCacher downloadCache
          Files that are EXTERNAL are cached locally per transaction
static String EXTRAVALUE_DATA
          The id for the FileType item representing a file containing analysed extra value data.
static String IMAGE
          The id for the FileType item representing an image file.
private  File internalFile
          The path to the internal file.
static int MAX_CHARSET_LENGTH
          The maximum length of the character set that can be stored in the database.
static int MAX_MIMETYPE_LENGTH
          The maximum length of the MIME type that can be stored in the database.
static int MAX_URL_LENGTH
          The maximum length of the URL type that can be stored in the database.
private  File newInternalFile
          The path to a newly uploaded file.
static String PLATE
          The id for the FileType item representing a plate file.
static String PLATE_MAPPING
          The id for the FileType item representing a plate mapping file.
static String PRINT_MAP
          The id for the FileType item representing a print map file.
static String PROTOCOL
          The id for the FileType item representing a protocol.
static String RAW_DATA
          The id for the FileType item representing a raw data file.
static String REPORTER
          The id for the FileType item representing a reporter file.
static String REPORTER_MAP
          The id for the FileType item representing a reporter map file.
private static String separator
           
static String SPOT_DATA
          The id for the FileType item representing a file containing analysed spot data.
static String SPOT_IMAGES
          The id for the FileType item representing a spot images file.
private static SimpleDateFormat SUBDIR_FORMAT
           
static Item TYPE
          The type of item represented by this class.
private  boolean uploadCompressed
          If the next upload should use compression or not.
private  File.UploadStream uploadStream
          A stream for uploading a physical file.
 
Fields inherited from interface net.sf.basedb.core.Nameable
MAX_DESCRIPTION_LENGTH, MAX_NAME_LENGTH
 
Constructor Summary
File(FileData data)
          Creates a new file item from the given data.
 
Method Summary
 void compress(ProgressReporter progress)
          Compress the file stored on the disk.
private  void compressOrDecompress(ProgressReporter progress, boolean compress)
           
 void decompress(ProgressReporter progress)
          Decompress the file stored on the disk.
 void download(OutputStream out, long offset)
          Download the physical file for this file item.
static boolean exists(DbControl dc, Directory directory, String fileName)
          Checks if a file with the specified name exists in the directory.
(package private) static File getAbsolutePath(String relativePath)
          Convert a relative path back to an absolute file path.
 File.Action getAction()
          Get the File.Action of this file.
static File getById(DbControl dc, int id)
          Get a File item when you know the id.
static File getByPath(DbControl dc, Path path, boolean create)
          Get a File item when you know the path.
 long getBytes()
          Get the absolute number of bytes this item uses.
 InputStream getCachedDownloadStream()
          Get a (possible) cached stream for reading from the file.
 String getCharacterSet()
          Get the character set used in this file (for text-files only).
 long getCompressedSize()
          Get the compressed size of this file.
 long getDifference()
          Always 0.
 Directory getDirectory()
          Get the associated Directory item.
 InputStream getDownloadStream(long offset)
          Get an InputStream that can be used to download the physical file for this file item.
static File getFile(DbControl dc, Directory directory, String fileName, boolean create)
          Get a File item when you know the directory and filename.
 FileServer getFileServer()
          Get the file server on which the external file is located.
private  String getInternalName()
          Get the internal name of this file.
 ItemSubtype getItemSubtype()
          Get the subtype of the item.
 Date getLastUpdate()
          Get the date and time the actual file data was last updated.
 Location getLocation()
          Get the Location the items is stored at.
 String getMd5()
          Get the MD5 hash of the file contents, or null if not known.
 String getMimeType()
          The mimetype of this File.
static File getNew(DbControl dc, Directory directory)
          Create a new File item.
private  File getNewFile(boolean compress)
          Get a new random file path.
 Path getPath()
          Get the complete path of this file.
static ItemQuery<File> getQuery()
          Get a query configured to retrieve File items.
 String getQuotaTypeSystemId()
          Always QuotaType.FILE.
(package private) static String getRelativePath(File file)
          Get the relative path of the specified file from the base upload directory and convert directory separator to forward slash.
private  ConnectionParameters getServerInfo()
           
 long getSize()
          Get the (uncompressed) size of this file.
 Item getType()
          Get the type of item represented by the object.
 OutputStream getUploadStream(boolean checkMd5)
          Get an OutputStream that can be used to upload a physical file for this file item.
 OutputStream getUploadStream(boolean checkMd5, Boolean compress)
          Get an OutputStream that can be used to upload a physical file for this file item.
 URI getURI()
          Get the URL of an external file as an URI.
 String getUrl()
          Get the URL to the (external) file.
 Set<ItemProxy> getUsingItems()
          Get all: FileAttachable items with this file attached SpotImages using this file
(package private)  void initPermissions(int granted, int denied)
          Check the write protected flag and deny DELETE if it is set.
 boolean isCompressed()
          If this file is stored in a compressed format or not.
 boolean isUsed()
          Checks if: A FileAttachable item is using this key.
 boolean isWriteProtected()
          Check if the file data is write protected.
(package private)  void onAfterCommit(Transactional.Action action)
          This method is called on each Transactional object after a successful commit to the database.
(package private)  void onBeforeCommit(Transactional.Action action)
          If a project is active, automatically share the new item according to the settings of that project, unless a project or item key has been explicitely set (including null).
(package private)  void onRollback(Transactional.Action action)
          This method is called on each Transactional object after an unsuccessful commit to the database.
 void setAction(File.Action action)
          Set the action of this File item.
 void setCharacterSet(String charset)
          Set the character set used in this file (for text-files only).
 void setDirectory(Directory directory)
          Set the directory of this File item.
 void setFileServer(FileServer fileServer)
          Set the file server on which this external file is located.
private  void setInternalName(String internalName)
          Set the internal name of this file.
 void setItemSubtype(ItemSubtype subtype)
          Set the subtype on the item.
 void setLocation(Location location)
          Set the location of this File item.
private  void setMetadataFromURI(UriMetadata metadata)
           
 void setMimeType(String mimeType)
          Set the mime type for this File item.
 void setMimeTypeAuto(String defaultMimeType, ItemSubtype defaultFileType)
          Set the mime type automatically by checking the extension of the name.
 void setName(String name)
          Set the name of the item.
 void setUrl(String url, boolean loadMetadata)
          Set the URL to an external file that should represent this file object.
 void setWriteProtected(boolean writeProtected)
          Set the write protected flag for this file.
 FileInfo toTransferable(FileInfo info)
          Transfer the internal state to a transferable object.
 void upload(InputStream in, boolean checkMd5)
          Upload a physical file for this file item.
 void upload(InputStream in, boolean checkMd5, Boolean compress)
          Upload a physical file for this file item.
 boolean uploadCompressed()
          Return the result of auto-compress check from the last call to setMimeTypeAuto(String, ItemSubtype).
 boolean useDifference()
          Always FALSE.
 
Methods inherited from class net.sf.basedb.core.CommonItem
getDescription, getName, isRemoved, setDescription, setRemoved, toTransferable
 
Methods inherited from class net.sf.basedb.core.SharedItem
getItemKey, getProjectKey, isShared, setItemKey, setProjectKey, toTransferable
 
Methods inherited from class net.sf.basedb.core.OwnedItem
getOwner, isOwner, setOwner, takeOwnership, toTransferable
 
Methods inherited from class net.sf.basedb.core.BasicItem
addUsingItems, addUsingItems, checkPermission, equals, getData, getDbControl, getId, getPermissions, getPluginPermissions, getSessionControl, getVersion, hashCode, hasPermission, isDetached, isInDatabase, onAfterInsert, setDbControl, setProjectDefaults, toString, toTransferable, validate
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface net.sf.basedb.core.Ownable
getOwner, isOwner, setOwner, takeOwnership
 
Methods inherited from interface net.sf.basedb.core.Identifiable
getId, getVersion
 
Methods inherited from interface net.sf.basedb.core.AccessControlled
checkPermission, getPermissions, hasPermission
 

Field Detail

TYPE

public static final Item TYPE
The type of item represented by this class.

See Also:
ITEM.FILE, getType()

PROTOCOL

public static final String PROTOCOL
The id for the FileType item representing a protocol.

Since:
3.0
See Also:
Constant Field Values

RAW_DATA

public static final String RAW_DATA
The id for the FileType item representing a raw data file.

Since:
3.0
See Also:
Constant Field Values

PLATE_MAPPING

public static final String PLATE_MAPPING
The id for the FileType item representing a plate mapping file.

Since:
3.0
See Also:
Constant Field Values

REPORTER_MAP

public static final String REPORTER_MAP
The id for the FileType item representing a reporter map file.

Since:
3.0
See Also:
Constant Field Values

PRINT_MAP

public static final String PRINT_MAP
The id for the FileType item representing a print map file.

Since:
3.0
See Also:
Constant Field Values

IMAGE

public static final String IMAGE
The id for the FileType item representing an image file.

Since:
3.0
See Also:
Constant Field Values

SPOT_IMAGES

public static final String SPOT_IMAGES
The id for the FileType item representing a spot images file.

Since:
3.0
See Also:
Constant Field Values

REPORTER

public static final String REPORTER
The id for the FileType item representing a reporter file.

Since:
3.0
See Also:
Constant Field Values

PLATE

public static final String PLATE
The id for the FileType item representing a plate file.

Since:
3.0
See Also:
Constant Field Values

SPOT_DATA

public static final String SPOT_DATA
The id for the FileType item representing a file containing analysed spot data.

Since:
3.0
See Also:
Constant Field Values

EXTRAVALUE_DATA

public static final String EXTRAVALUE_DATA
The id for the FileType item representing a file containing analysed extra value data.

Since:
3.0
See Also:
Constant Field Values

ALIGNED_SEQUENCE

public static final String ALIGNED_SEQUENCE
The id for the FileType item representing a file containing aligned sequence data.

Since:
3.0
See Also:
Constant Field Values

newInternalFile

private File newInternalFile
The path to a newly uploaded file.


downloadCache

private StreamCacher downloadCache
Files that are EXTERNAL are cached locally per transaction


internalFile

private File internalFile
The path to the internal file.


uploadStream

private File.UploadStream uploadStream
A stream for uploading a physical file.


uploadCompressed

private boolean uploadCompressed
If the next upload should use compression or not.


MAX_MIMETYPE_LENGTH

public static final int MAX_MIMETYPE_LENGTH
The maximum length of the MIME type that can be stored in the database.

See Also:
setMimeType(String), Constant Field Values

MAX_CHARSET_LENGTH

public static final int MAX_CHARSET_LENGTH
The maximum length of the character set that can be stored in the database.

Since:
2.9
See Also:
setCharacterSet(String), Constant Field Values

MAX_URL_LENGTH

public static final int MAX_URL_LENGTH
The maximum length of the URL type that can be stored in the database.

Since:
2.16
See Also:
setUrl(String, boolean), Constant Field Values

separator

private static final String separator

SUBDIR_FORMAT

private static final SimpleDateFormat SUBDIR_FORMAT
Constructor Detail

File

File(FileData data)
Creates a new file item from the given data.

Parameters:
data - the data.
Method Detail

getNew

public static File getNew(DbControl dc,
                          Directory directory)
                   throws BaseException
Create a new File item.

Parameters:
dc - The DbControl which will be used for permission checking and database access.
directory - The Directory that holds the file. It may not be null.
Returns:
The new File item
Throws:
BaseException - This exception is thrown if there is another error

getById

public static File getById(DbControl dc,
                           int id)
                    throws ItemNotFoundException,
                           PermissionDeniedException,
                           BaseException
Get a File item when you know the id.

Parameters:
dc - The DbControl which will be used for permission checking and database access.
id - The id of the item to load
Returns:
The File item
Throws:
ItemNotFoundException - If an item with the specified id is not found
PermissionDeniedException - If the logged in user doesn't have Permission.READ permission to the item
BaseException - If there is another error

getByPath

public static File getByPath(DbControl dc,
                             Path path,
                             boolean create)
                      throws ItemNotFoundException,
                             PermissionDeniedException,
                             BaseException
Get a File item when you know the path. Use the create parameter to specify if a new file should be create if it doesn't exists. The directory part of the path must still be an existing path, otherwise an ItemNotFoundException is thrown.

Parameters:
dc - The DbControl which will be used for permission checking and database access.
path - The path to the file to load
create - TRUE if a new file should be created if one doesn't eixts, FALSE to throw an exception (DbControl.saveItem must always be called)
Returns:
The File item
Throws:
ItemNotFoundException - If an item with the specified path is not found and create is FALSE
PermissionDeniedException - If the logged in user doesn't have Permission.READ permission to the item
BaseException - If there is another error

getFile

public static File getFile(DbControl dc,
                           Directory directory,
                           String fileName,
                           boolean create)
                    throws ItemNotFoundException,
                           PermissionDeniedException,
                           BaseException
Get a File item when you know the directory and filename. Use the create parameter to specify if a new file should be create if it doesn't exists.

Parameters:
dc - The DbControl which will be used for permission checking and database access.
directory - The directory where the file is located.
fileName - The name of the file.
create - TRUE if a new file should be created if one doesn't eixts, FALSE to throw an exception (DbControl.saveItem must always be called)
Returns:
The File item
Throws:
ItemNotFoundException - If an item with the specified path is not found and create is FALSE
PermissionDeniedException - If the logged in user doesn't have Permission.READ permission to the item
BaseException - If there is another error

exists

public static boolean exists(DbControl dc,
                             Directory directory,
                             String fileName)
                      throws BaseException
Checks if a file with the specified name exists in the directory.

Parameters:
dc - The DbControl which will be used for permission checking and database access.
directory - The directory to check in.
fileName - The name of the file to look for.
Returns:
TRUE if the file exists, FALSE otherwise.
Throws:
BaseException

getQuery

public static ItemQuery<File> getQuery()
Get a query configured to retrieve File items.

Returns:
An ItemQuery object

getType

public Item getType()
Description copied from interface: Identifiable
Get the type of item represented by the object. The returned value is one of the values defined in the Item enumeration.

Specified by:
getType in interface Identifiable
Returns:
A value indicating the type of item

setName

public void setName(String name)
             throws PermissionDeniedException,
                    InvalidDataException
Description copied from interface: Nameable
Set the name of the item. The name cannot be null and mustn't be longer than the value specified by the Nameable.MAX_NAME_LENGTH constant.

Specified by:
setName in interface Nameable
Overrides:
setName in class CommonItem<FileData>
Parameters:
name - The new name for the item
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission
InvalidDataException - If the name is null or longer than specified by the Nameable.MAX_NAME_LENGTH constant

useDifference

public boolean useDifference()
Always FALSE.

Specified by:
useDifference in interface DiskConsumable
Returns:
TRUE if the item reports the difference, FALSE if it reports the absolute
See Also:
DiskConsumable.getBytes(), DiskConsumable.getDifference()

getBytes

public long getBytes()
Description copied from interface: DiskConsumable
Get the absolute number of bytes this item uses. All items must report this number.

Specified by:
getBytes in interface DiskConsumable
Returns:
The absolute number of bytes the item uses
See Also:
DiskConsumable.useDifference(), DiskConsumable.getDifference()

getDifference

public long getDifference()
Always 0.

Specified by:
getDifference in interface DiskConsumable
Returns:
The difference in bytes between now and when the item was loaded, or 0 if this item doesn't report differences

getQuotaTypeSystemId

public String getQuotaTypeSystemId()
Always QuotaType.FILE.

Specified by:
getQuotaTypeSystemId in interface DiskConsumable
Returns:
The systemid of the QuotaType

getLocation

public Location getLocation()
Description copied from interface: DiskConsumable
Get the Location the items is stored at.

Specified by:
getLocation in interface DiskConsumable
Returns:
The location

getItemSubtype

public ItemSubtype getItemSubtype()
Description copied from interface: Subtypable
Get the subtype of the item.

Specified by:
getItemSubtype in interface Subtypable
Returns:
A subtype of null if not set
See Also:
SubtypableRelatedItems

setItemSubtype

public void setItemSubtype(ItemSubtype subtype)
Description copied from interface: Subtypable
Set the subtype on the item.

Specified by:
setItemSubtype in interface Subtypable
Parameters:
subtype - A subtype or null
See Also:
ItemSubtype.setOnItem(Subtypable)

isUsed

public boolean isUsed()
               throws BaseException
Checks if:

Overrides:
isUsed in class BasicItem<FileData>
Returns:
TRUE if this item is used, FALSE otherwise
Throws:
BaseException - If there is another error
See Also:
BasicItem.getUsingItems()

getUsingItems

public Set<ItemProxy> getUsingItems()
Get all:

onBeforeCommit

void onBeforeCommit(Transactional.Action action)
              throws BaseException
Description copied from class: SharedItem
If a project is active, automatically share the new item according to the settings of that project, unless a project or item key has been explicitely set (including null).

Overrides:
onBeforeCommit in class SharedItem<FileData>
Throws:
BaseException - If there is another error
See Also:
Transactional, Developer documentation: Transactions, Developer documentation: Coding rules and guidelines for item classes

onAfterCommit

void onAfterCommit(Transactional.Action action)
Description copied from class: BasicItem
This method is called on each Transactional object after a successful commit to the database. If the subclass overrides this method it should also propagate the call to the superclass, ie. super.onAfterCommit(action). It is forbidden to access the DbControl object from this method and it must not throw any exceptions. All exceptions should be logged using the Application.getLogger() object.

Overrides:
onAfterCommit in class BasicItem<FileData>
See Also:
Transactional, Developer documentation: Transactions, Developer documentation: Coding rules and guidelines for item classes

onRollback

void onRollback(Transactional.Action action)
Description copied from class: BasicItem
This method is called on each Transactional object after an unsuccessful commit to the database. If the subclass overrides this method it should also propagate the call to the superclass, ie. super.onRollback(action). It is forbidden to access the DbControl object from this method and it must not throw any exceptions. All exceptions should be logged using the Application.getLogger() object.

Overrides:
onRollback in class BasicItem<FileData>
See Also:
Transactional, Developer documentation: Transactions, Developer documentation: Coding rules and guidelines for item classes

initPermissions

void initPermissions(int granted,
                     int denied)
Check the write protected flag and deny DELETE if it is set.

Overrides:
initPermissions in class SharedItem<FileData>
Parameters:
granted - Permissions that have been granted by the subclass
denied - Permissions that have been denied by the subclass

toTransferable

public FileInfo toTransferable(FileInfo info)
Description copied from interface: ToTransferable
Transfer the internal state to a transferable object. The method should return the same object that is passed in as an argument.

Specified by:
toTransferable in interface ToTransferable<FileInfo>
Parameters:
info - The transferable object to use
Returns:
The transferable object with values set.
Since:
3.0

getInternalName

private String getInternalName()
Get the internal name of this file.

Returns:
The internal name.

setInternalName

private void setInternalName(String internalName)
Set the internal name of this file.

Parameters:
internalName - The internal filename.

setLocation

public void setLocation(Location location)
                 throws PermissionDeniedException,
                        InvalidUseOfNullException
Set the location of this File item.

Parameters:
location - The new Location
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission, or if the file is write protected and the new location isn't Location.PRIMARY
InvalidUseOfNullException - If location is null

getAction

public File.Action getAction()
Get the File.Action of this file.

Returns:
the action

setAction

public void setAction(File.Action action)
               throws PermissionDeniedException,
                      InvalidUseOfNullException
Set the action of this File item. This method call has no affect on external files.

Parameters:
action - The new File.Action
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission
InvalidUseOfNullException - If action is null

getSize

public long getSize()
Get the (uncompressed) size of this file.

Returns:
The size in bytes or -1 if not known
See Also:
getCompressedSize()

getCompressedSize

public long getCompressedSize()
Get the compressed size of this file. If the file is not stored in a compressed format this method return the same value as getSize()

Returns:
The compressed size in bytes or -1 if not known
Since:
2.5
See Also:
isCompressed()

isCompressed

public boolean isCompressed()
If this file is stored in a compressed format or not.

Returns:
TRUE if the file is compressed
Since:
2.5

getMd5

public String getMd5()
Get the MD5 hash of the file contents, or null if not known.

Returns:
A 32-character hexadecimal string

getMimeType

public String getMimeType()
The mimetype of this File. It can be a defined MimeType , any mimetype or null.

Returns:
the mimetype of this file

setMimeType

public void setMimeType(String mimeType)
                 throws PermissionDeniedException,
                        InvalidDataException
Set the mime type for this File item. It can be any mimetype or one avalible in the mimetype table.

Parameters:
mimeType - The new mime type for this item
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission
InvalidDataException - If the mime type is longer than MAX_MIMETYPE_LENGTH

getCharacterSet

public String getCharacterSet()
Get the character set used in this file (for text-files only).

Returns:
The name of the character set as returned by Charset.name(), or null if not known or applicable to the file type
Since:
2.9

setCharacterSet

public void setCharacterSet(String charset)
Set the character set used in this file (for text-files only).

Parameters:
charset - The name of the character set as returned by Charset.name()
Since:
2.9

getDirectory

public Directory getDirectory()
                       throws PermissionDeniedException,
                              BaseException
Get the associated Directory item.

Returns:
The Directory item
Throws:
PermissionDeniedException - This exception is thrown if the logged in user doesn't have READ permission to the items
BaseException - If there is another error

setDirectory

public void setDirectory(Directory directory)
                  throws PermissionDeniedException,
                         InvalidUseOfNullException
Set the directory of this File item.

Parameters:
directory - The new Directory
Throws:
PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission to the file or Permission.USE permission to the directory
InvalidUseOfNullException - If directory is null

isWriteProtected

public boolean isWriteProtected()
Check if the file data is write protected. A write protected file can't be deleted, moved offline or to the secondary storage, or replaced with another file. This setting doesn't affect metadata about the file, such as the name, description, file type, mime type, etc.

Returns:
TRUE if the file is write protected, FALSE otherwise
Since:
2.4

setWriteProtected

public void setWriteProtected(boolean writeProtected)
                       throws PermissionDeniedException
Set the write protected flag for this file.

Parameters:
writeProtected - TRUE if the file should be write protected
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission on the file item.
Since:
2.4
See Also:
isWriteProtected()

getLastUpdate

public Date getLastUpdate()
Get the date and time the actual file data was last updated. This value is only affected by file uploads, not by changing the name, description or any other metadata.

Returns:
The date or null if no file has been uploaded
Since:
2.4

getUrl

public String getUrl()
Get the URL to the (external) file. This property is only set/valid for files that are stored externally (getLocation() == Location.EXTERNAL)

Returns:
The URL or null if the file is stored internally
Since:
2.16

getURI

public URI getURI()
Get the URL of an external file as an URI. This property is only set/valid for files that are stored externally (getLocation() == Location.EXTERNAL). If the URL is is not a valid URI an exception is thrown.

Returns:
An URI or null
Since:
3.0

setUrl

public void setUrl(String url,
                   boolean loadMetadata)
Set the URL to an external file that should represent this file object. NOTE! The location, size, md5, internal file, etc. will be reset as a result of this call. NOTE 2! If the file server is also updated at the same time it is important that the file server has been changed before setting the URL, otherwise the old file server is used.

Parameters:
url - The url to the file (null is not allowed)
loadMetadata - If TRUE, a HEAD request will be issued to the given URL and metadata such as size, MIME type, etc. will be extracted if given in the response
Throws:
InvalidDataException - If the URL is null, too long, or not a valid URL
PermissionDeniedException - If the logged in user doesn't have write permission
Since:
2.16

getFileServer

public FileServer getFileServer()
Get the file server on which the external file is located. The file server can be used to store username/password that is required to access the file. External files that doesn't require authentication usually don't need to be associated with a server.

Returns:
A FileServer or null if no file server has been set
Since:
2.16

setFileServer

public void setFileServer(FileServer fileServer)
                   throws PermissionDeniedException,
                          InvalidUseOfNullException
Set the file server on which this external file is located.

Parameters:
fileServer - The new FileServer
Throws:
PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission to the file or Permission.USE permission to the file server
InvalidUseOfNullException
Since:
2.16

getServerInfo

private ConnectionParameters getServerInfo()

setMetadataFromURI

private void setMetadataFromURI(UriMetadata metadata)

getPath

public Path getPath()
Get the complete path of this file.

Returns:
A Path object

setMimeTypeAuto

public void setMimeTypeAuto(String defaultMimeType,
                            ItemSubtype defaultFileType)
                     throws PermissionDeniedException
Set the mime type automatically by checking the extension of the name. If no match is found, the mime type is set to the default value if specified, or left unchanged if the default is null. This method will also check the MimeType.getAutoCompress() flag and select auto-compression for the next upload if it is set. Auto-compression is also selected if the Directory.getAutoCompress() flag is set.

Parameters:
defaultMimeType - The default value to use if no match is found for the file extension
defaultFileType - The default file type to set if no match is found or null to leave it unchanged
Throws:
PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission
Since:
3.0
See Also:
uploadCompressed()

uploadCompressed

public boolean uploadCompressed()
Return the result of auto-compress check from the last call to setMimeTypeAuto(String, ItemSubtype). If this method returns true, the next call to upload(InputStream, boolean) or getUploadStream(boolean) will store the uploaded file in a compressed format.

Returns:
TRUE if the next upload should be compressed
Since:
2.5

compress

public void compress(ProgressReporter progress)
Compress the file stored on the disk. If the file is already compressed or not located in the Location.PRIMARY location this method does nothing.

Parameters:
progress - An optional progress reporter
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission on the file
Since:
2.5

decompress

public void decompress(ProgressReporter progress)
Decompress the file stored on the disk. If the file isn't compressed or not located in the Location.PRIMARY location this method does nothing.

Parameters:
progress - An optional progress reporter
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission on the file
Since:
2.5

compressOrDecompress

private void compressOrDecompress(ProgressReporter progress,
                                  boolean compress)

upload

public void upload(InputStream in,
                   boolean checkMd5)
            throws PermissionDeniedException,
                   BaseException
Upload a physical file for this file item. This method calls upload(InputStream, boolean, Boolean). A null value is used for the compress parameter to enable auto-compression.

Parameters:
in - Input stream from the file to be uploaded.
checkMd5 - TRUE if the Md5 sum should be checked, FALSE otherwise.
Throws:
PermissionDeniedException - If the logged in user doesn't have permission to upload the file
BaseException - If there is some other error.

upload

public void upload(InputStream in,
                   boolean checkMd5,
                   Boolean compress)
            throws PermissionDeniedException,
                   BaseException
Upload a physical file for this file item.

Parameters:
in - An InputStream which will be read until end of file is found
checkMd5 - If the MD5 sum of the uploaded data should be checked against the MD5 sum already stored in the database. If no MD5 exists in the database this parameter is ignored
compress - TRUE to store the file in a compressed format, or null to use whatever the Directory.getAutoCompress() is specifying or what auto-detection from the setMimeTypeAuto(String, ItemSubtype) found
Throws:
PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for this item, or if the file is write protected
BaseException - If there is another error
Since:
2.5

getUploadStream

public OutputStream getUploadStream(boolean checkMd5)
Get an OutputStream that can be used to upload a physical file for this file item. This method calls getUploadStream(boolean, Boolean). A null value is used for the compress parameter to enable auto-compression.

Parameters:
checkMd5 - TRUE if the Md5 sum should be checked, FALSE otherwise
Returns:
An output stream to upload file to.

getUploadStream

public OutputStream getUploadStream(boolean checkMd5,
                                    Boolean compress)
                             throws PermissionDeniedException,
                                    BaseException
Get an OutputStream that can be used to upload a physical file for this file item. The client application should call close() method to finish the upload. Note! Calling this method multiple times without closing the returned stream will return the same stream and the checkMd5 and compress parameters are ignored.

Parameters:
checkMd5 - If the MD5 sum of the uploaded data should be checked against the MD5 sum already stored in the database. If no MD5 exists in the database this parameter is ignored
compress - TRUE to store the file in a compressed format, or null to use whatever the Directory.getAutoCompress() is specifying or what auto-detection from the setMimeTypeAuto(String, ItemSubtype) found
Returns:
An OutputStream object
Throws:
PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for this item or if the file is write protected
BaseException - If there is another error
Since:
2.5

download

public void download(OutputStream out,
                     long offset)
              throws BaseException
Download the physical file for this file item.

Parameters:
out - An OutputStream object which will be used to write the file
offset - Start reading the physical at the specified offset, use 0 to start reading from the beginning
Throws:
BaseException - If there is an error

getDownloadStream

public InputStream getDownloadStream(long offset)
                              throws BaseException
Get an InputStream that can be used to download the physical file for this file item. The client application should call close() method to finish the download. If the file is an external file, the file will be loaded from the URL given by getUrl(), otherwise if the physical file isn't at the primary location an empty stream is returned.

Parameters:
offset - Start reading the physical at the specified offset, use 0 to start reading from the beginning
Returns:
An InputStream object
Throws:
BaseException - If there is an error

getCachedDownloadStream

public InputStream getCachedDownloadStream()
Get a (possible) cached stream for reading from the file. This method will enable caching (to the local disk) for external or compressed files. This method is useful if you need to read the file multiple times in the same transaction (for example, when trying to auto-detect a file format). The cached data is cleared at the end of the transaction.

Returns:
An InputStream object
Since:
2.16
See Also:
StreamCacher

getNewFile

private File getNewFile(boolean compress)
                 throws BaseException
Get a new random file path.

Returns:
A new random unique file.
Throws:
BaseException - If there is an error.

getRelativePath

static String getRelativePath(File file)
Get the relative path of the specified file from the base upload directory and convert directory separator to forward slash.

Since:
2.2
See Also:
getAbsolutePath(String)

getAbsolutePath

static File getAbsolutePath(String relativePath)
Convert a relative path back to an absolute file path.

Since:
2.2
See Also:
getRelativePath(java.io.File)

3.0.1: 2011-11-10