org.proteios.core
Class File

java.lang.Object
  org.proteios.core.BasicItem<D>
      org.proteios.core.OwnedItem<D>
          org.proteios.core.SharedItem<D>
              org.proteios.core.CommonItem<D>
                  org.proteios.core.AnnotatedItem<FileData>
                      org.proteios.core.File

All Implemented Interfaces:

AccessControlled, Annotatable, Controlled, DiskConsumable, Identifiable, Nameable, Ownable, Removable, Shareable, Transactional

public class File
extends AnnotatedItem<FileData>
implements Transactional, DiskConsumable

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-03-22 14:38:33 +0100 (Tue, 22 Mar 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.

Field Summary

static int	MAX_MIMETYPE_LENGTH The maximum length of the MIME type that can be stored in the database.
static int	MAX_URI_LENGTH The maximum length of the URI that can be stored in the database.
static Item	TYPE The type of item represented by this class.

Fields inherited from interface org.proteios.core.Nameable

MAX_DESCRIPTION_LENGTH, MAX_NAME_LENGTH

Method Summary

void	addBioMaterial(BioMaterial bioMaterial) Add a BioMaterial
void	compress(ProgressReporter progress) Compress the file if stored on an internal disk.
void	decompress(ProgressReporter progress) Decompress the file if stored on an internal 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.
File.Action	getAction() Get the File.Action of this file.
Set<BioMaterial>	getBioMaterials()
long	getCompressedSizeInBytes() Get the compressed size in bytes of this file.
Date	getCreated()
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.
FileType	getFileType() Get the associated FileType item.
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.
Path	getPath() Get the complete path of this file.
static ItemQuery<File>	getQuery() Get a query configured to retrieve File items.
String	getQuotaTypeSystemId() Get the QuotaType system id of this item.
InputStream	getRawDownloadStream(long offset) Get an InputStream that can be used to download the physical file for this file item.
long	getSize() Get the size of this file.
long	getSizeInBytes() Get the (uncompressed) size in bytes of this file.
Item	getType() Get the type of item represented by the object.
String	getUniformResourceIdentifier()
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.
OutputStream	getUploadStream(boolean checkMd5, Boolean compress, boolean append) Get an OutputStream that can be used to upload a physical file for this file item.
boolean	isCompressed() If this file is stored in a compressed format or not.
boolean	isUsed() Checks if: A FileAttachable item is using this key.
void	setAction(File.Action action) Set the action of this File item.
void	setBioMaterials(Set<BioMaterial> bioMaterials) Set the BioMaterial bioMaterials set.
void	setCompressed(boolean compressed) Set the flag indicating that this file is stored in a compressed format or not.
void	setCompressedSizeInBytes(long size) Set the compressed size in bytes of this file.
void	setDirectory(Directory directory) Set the directory of this File item.
void	setFileType(FileType filetype) Set the filetype of this File item.
void	setLocation(Location location) Set the location of this File item.
void	setMd5(String Md5) Set the MD5 hash of the file contents.
void	setMimeType(String mimeType) Set the mime type for this File item.
void	setMimeTypeAuto(String defaultMimeType) Set the mime type automatically by checking the extension of the name.
void	setName(String name) Set the name of the item.
void	setSizeInBytes(long size) Set the (uncompressed) size in bytes of this file.
void	setUniformResourceIdentifier(String uniformResourceIdentifier) Set the URI for this File item.
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.

Methods inherited from class org.proteios.core.CommonItem

getDescription, getName, isRemoved, setDescription, setRemoved

Methods inherited from class org.proteios.core.SharedItem

getItemKey, getProjectKey, isShared, setItemKey, setProjectKey

Methods inherited from class org.proteios.core.OwnedItem

getOwner, setOwner

Methods inherited from class org.proteios.core.BasicItem

checkPermission, equals, getDbControl, getId, getPermissions, getSessionControl, getVersion, hashCode, hasPermission, isDetached, isInDatabase, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.proteios.core.Ownable

getOwner, setOwner

Methods inherited from interface org.proteios.core.Identifiable

getId, getVersion

Methods inherited from interface org.proteios.core.AccessControlled

checkPermission, hasPermission

Field Detail

TYPE

public static final Item TYPE

The type of item represented by this class.

See Also:

ITEM.FILE, getType()

MAX_URI_LENGTH

public static final int MAX_URI_LENGTH

The maximum length of the URI that can be stored in the database.

See Also:

setUniformResourceIdentifier(String), Constant Field Values

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

Method Detail

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

compress

public void compress(ProgressReporter progress)

Compress the file if stored on an internal disk. If the file is already registered as compressed, this method does nothing. If the file is located in the Location.PRIMARY location, the file is compressed on the disk, otherwise only the "compress" flag is set to `true`, in order to trigger a requested download stream to be decompressed.

Parameters:

progress - ProgressReporter An optional progress reporter.

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission on the file.

decompress

public void decompress(ProgressReporter progress)

Decompress the file if stored on an internal disk. If the file is already registered as not compressed, this method does nothing. If the file is located in the Location.PRIMARY location, the file is decompressed on the disk, otherwise only the "compress" flag is set to `false`, in order to trigger a requested download stream to be unmodified.

Parameters:

progress - ProgressReporter An optional progress reporter.

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission on the file.

getUniformResourceIdentifier

public String getUniformResourceIdentifier()

Returns:

the uniform resource identifier of this file if one is set, null otherwise

setUniformResourceIdentifier

public void setUniformResourceIdentifier(String uniformResourceIdentifier)
                                  throws InvalidDataException

Set the URI for this File item. The value may be null but must not be longer than the value specified by the MAX_URI_LENGTH constant.

Throws:

InvalidDataException - If the URI is longer than MAX_URI_LENGTH or protocol is different from http

getCreated

public Date getCreated()

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

getSizeInBytes

public long getSizeInBytes()

Get the (uncompressed) size in bytes of this file.

Specified by:

getSizeInBytes in interface DiskConsumable

Returns:

long The (uncompressed) size in bytes of this file.

setSizeInBytes

public void setSizeInBytes(long size)

Set the (uncompressed) size in bytes of this file. Only changes the value if the file is remote.

Parameters:

size - long The (uncompressed) size in bytes of this file to set.

getCompressedSizeInBytes

public long getCompressedSizeInBytes()

Get the compressed size in bytes of this file. If the file is not stored in a compressed format, this method return the same value as getSizeInBytes().

Returns:

long The compressed size in bytes of this file.

setCompressedSizeInBytes

public void setCompressedSizeInBytes(long size)

Set the compressed size in bytes of this file. Only changes the value if the file is remote.

Parameters:

size - long The compressed size in bytes of this file to set.

isCompressed

public boolean isCompressed()

If this file is stored in a compressed format or not.

Returns:

boolean Returns true if if the file is compressed.

setCompressed

public void setCompressed(boolean compressed)

Set the flag indicating that this file is stored in a compressed format or not. Only changes the value if the file is remote.

Parameters:

compressed - boolean The flag indicating that this file is stored in a compressed format.

getQuotaTypeSystemId

public String getQuotaTypeSystemId()

Description copied from interface: DiskConsumable

Get the QuotaType system id of this item. It is not allowed to return the QuotaType.TOTAL quota type.

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

addBioMaterial

public void addBioMaterial(BioMaterial bioMaterial)

Add a BioMaterial

Parameters:

bioMaterial - The BioMaterial to add to the Set

getBioMaterials

public Set<BioMaterial> getBioMaterials()
                                 throws ItemNotFoundException,
                                        BaseException

Returns:

Returns the bioMaterials.

Throws:

ItemNotFoundException

BaseException

setBioMaterials

public void setBioMaterials(Set<BioMaterial> bioMaterials)

Set the BioMaterial bioMaterials set.

Parameters:

bioMaterials - The new Set item.

isUsed

public boolean isUsed()
               throws BaseException

Checks if:

• A FileAttachable item is using this key.

Specified by:

isUsed in class BasicItem<FileData>

Returns:

TRUE if this item is used, FALSE otherwise

Throws:

BaseException - If there is another error

getFileType

public FileType getFileType()
                     throws PermissionDeniedException,
                            BaseException

Get the associated FileType item.

Returns:

The FileType item, or null if no type has been specified

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

setFileType

public void setFileType(FileType filetype)
                 throws PermissionDeniedException

Set the filetype of this File item.

Parameters:

filetype - The new FileType, or null

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

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

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.

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 size of this file.

Returns:

the size in bytes

getMd5

public String getMd5()

Get the MD5 hash of the file contents, or null if not known.

Returns:

A 32-character hexadecimal string

setMd5

public void setMd5(String Md5)

Set the MD5 hash of the file contents. Only changes the value if the file is remote.

Parameters:

Md5 - String A 32-character hexadecimal string to set.

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

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

getPath

public Path getPath()

Get the complete path of this file.

Returns:

A Path object

setMimeTypeAuto

public void setMimeTypeAuto(String defaultMimeType)
                     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.

Parameters:

defaultMimeType - The default value to use if no match is found for the file extension

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission

upload

public void upload(InputStream in,
                   boolean checkMd5)
            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

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for this item

BaseException - If there is another 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 - Boolean TRUE to store the file in a compressed format.

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for this item

BaseException - If there is another error

getUploadStream

public OutputStream getUploadStream(boolean checkMd5)
                             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. If the file exists it will be overwritten.

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

Returns:

An OutputStream object

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for this item

BaseException - If there is another error

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. If the file exists it will be overwritten.

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 - Boolean Whether the file will be stored in compressed format or not.

Returns:

An OutputStream object

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for this item

BaseException - If there is another error

getUploadStream

public OutputStream getUploadStream(boolean checkMd5,
                                    Boolean compress,
                                    boolean append)
                             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.

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 - Boolean Whether the file will be stored in compressed format or not.

append - boolean Whether the stream will be appended to an existing file or not. If there is no existing file this parameter has no effect.

Returns:

An OutputStream object

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for this item

BaseException - If there is another error

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 physical file isn't at the primary location there is an attempt at downloading the file from the URI. If no URI is given 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

getRawDownloadStream

public InputStream getRawDownloadStream(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 physical file isn't at the primary location there is an attempt at downloading the file from the URI. If no URI is given an empty stream is returned. Does not attempt to decompress contents of a file stored compressed internally.

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