Package net.sf.basedb.core

Class File

java.lang.Object
net.sf.basedb.core.BasicItem
net.sf.basedb.core.OwnedItem
net.sf.basedb.core.SharedItem
net.sf.basedb.core.CommonItem
net.sf.basedb.core.AnnotatedItem
net.sf.basedb.core.File
All Implemented Interfaces:
AccessControlled, Annotatable, Controlled, DiskConsumable, Identifiable, Nameable, Ownable, Removable, Shareable, Subtypable, Transactional
public class File extends AnnotatedItem implements Transactional, DiskConsumable, Subtypable
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: 2023-12-20 14:32:15 +0100 (Wed, 20 Dec 2023) $

  • Field Details

    • TYPE

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

    • PROTOCOL

      public static final String PROTOCOL
      The id for the FileType item representing a protocol.
      Since:
      3.0
      See Also:

    • RAW_DATA

      public static final String RAW_DATA
      The id for the FileType item representing a raw data file.
      Since:
      3.0
      See Also:

    • PLATE_MAPPING

      public static final String PLATE_MAPPING
      The id for the FileType item representing a plate mapping file.
      Since:
      3.0
      See Also:

    • REPORTER_MAP

      public static final String REPORTER_MAP
      The id for the FileType item representing a reporter map file.
      Since:
      3.0
      See Also:

    • IMAGE

      public static final String IMAGE
      The id for the FileType item representing an image file.
      Since:
      3.0
      See Also:

    • REPORTER

      public static final String REPORTER
      The id for the FileType item representing a reporter file.
      Since:
      3.0
      See Also:

    • PLATE

      public static final String PLATE
      The id for the FileType item representing a plate file.
      Since:
      3.0
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • separator

      private static final String separator

    • SUBDIR_FORMAT

      private static final org.apache.commons.lang3.time.FastDateFormat SUBDIR_FORMAT

  • Constructor Details

    • File

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

  • Method Details

    • 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 is also created if needed.
      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

    • getData

      FileData getData()
      Description copied from class: BasicItem
      Get the BasicData object that holds all data for this item.
      Overrides:
      getData in class AnnotatedItem

    • 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
      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:

    • 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:

    • 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:

    • 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:

    • getAnnotatableParents

      public Set<Annotatable> getAnnotatableParents()
      Description copied from interface: Annotatable
      Get all parents objects which are annotatable and the logged in user has read permission to. If the item doesn't have any annotatable parents, it may return null or an empty set. The method should only return the immediate parent(s), not parents to parents, etc. As of BASE 3.1 this method may also return child items if the child item is a Subtypable item that has a subtype with the ItemSubtype.getPushAnnotations() flag set.
      Specified by:
      getAnnotatableParents in interface Annotatable
      Returns:
      A set containing annotatable items, or null

    • isUsed

      public boolean isUsed() throws BaseException
      Checks if:
      Overrides:
      isUsed in class BasicItem
      Returns:
      TRUE if this item is used, FALSE otherwise
      Throws:
      BaseException - If there is another error
      See Also:

    • getUsingItems

      public Set<ItemProxy> getUsingItems()
      Get all:
      Overrides:
      getUsingItems in class BasicItem
      Returns:
      A set containing proxies for the items, or an empty set if no items are using this item
      Since:
      2.2
      See Also:

    • 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
      Throws:
      BaseException - If there is another error
      See Also:

    • 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
      See Also:

    • 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
      See Also:

    • initPermissions

      void initPermissions(int granted, int denied)
      Check the write protected flag and deny DELETE if it is set.
      Overrides:
      initPermissions in class SharedItem
      Parameters:
      granted - Permissions that have been granted by the subclass
      denied - Permissions that have been denied by the subclass

    • 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

    • getSize

      public long getSize()
      Get the (uncompressed) size of this file.
      Returns:
      The size in bytes or -1 if not known
      See Also:

    • 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

      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:

    • 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

    • setUrl

      public void setUrl(String url, UriMetadata metadata)
      Set the URL to an external file that should represent this file object and update the metadata without going to the remote server.
      Parameters:
      url - The url to the file (null is not allowed)
      metadata - Metadata for the URL (or null to not update the metadata)
      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:
      3.11

    • updateURLMetadata

      public void updateURLMetadata()
      If this is an external file, try to update the metadata.
      Since:
      3.3

    • 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

      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:

    • 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

      static File getAbsolutePath(String relativePath)
      Convert a relative path back to an absolute file path.
      Since:
      2.2
      See Also: