Class File

    • 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
      • 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.
      • separator

        private static final String separator
    • 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
      • 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
      • 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
      • 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.
      • 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
      • 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
      • 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
      • 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
      • 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()
      • 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)
      • 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)