Interface FileContent

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable
    All Known Implementing Classes:
    DefaultFileContent

    public interface FileContent
    extends java.io.Closeable
    Represents the data content of a file.

    To read from a file, use the InputStream returned by getInputStream().

    To write to a file, use the OutputStream returned by getOutputStream() method. This will create the file, and the parent folder, if necessary.

    A file may have multiple InputStreams open at the same time.

    See Also:
    FileObject.getContent()
    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      void close()
      Closes all resources used by the content, including any open stream.
      java.lang.Object getAttribute​(java.lang.String attrName)
      Gets the value of an attribute of the file's content.
      java.lang.String[] getAttributeNames()
      Gets the attributes of the file's content.
      java.util.Map<java.lang.String,​java.lang.Object> getAttributes()
      Returns a read-only map of this file's attributes.
      default byte[] getByteArray()
      Returns the content of a file as a byte array.
      java.security.cert.Certificate[] getCertificates()
      Gets the certificates if any used to sign this file or folder.
      FileContentInfo getContentInfo()
      Gets the content info.
      FileObject getFile()
      Gets the file which this is the content of.
      java.io.InputStream getInputStream()
      Gets an input stream for reading the file's content.
      default java.io.InputStream getInputStream​(int bufferSize)
      Gets an input stream for reading the file's content.
      long getLastModifiedTime()
      Gets the last-modified timestamp of the file.
      java.io.OutputStream getOutputStream()
      Gets an output stream for writing the file's content.
      java.io.OutputStream getOutputStream​(boolean bAppend)
      Gets an output stream for writing the file's content.
      default java.io.OutputStream getOutputStream​(boolean bAppend, int bufferSize)
      Gets an output stream for writing the file's content.
      default java.io.OutputStream getOutputStream​(int bufferSize)
      Gets an output stream for writing the file's content.
      RandomAccessContent getRandomAccessContent​(RandomAccessMode mode)
      Gets a stream for reading/writing the file's content.
      long getSize()
      Gets the size of the file, in bytes.
      default java.lang.String getString​(java.lang.String charset)
      Gets the content of a file as a String.
      default java.lang.String getString​(java.nio.charset.Charset charset)
      Returns the content of a file as a String.
      boolean hasAttribute​(java.lang.String attrName)
      Checks if an attribute of the file's content exists.
      default boolean isEmpty()
      Tests if the receiver is empty.
      boolean isOpen()
      Tests if this file has open streams.
      void removeAttribute​(java.lang.String attrName)
      Removes the value of an attribute of the file's content.
      void setAttribute​(java.lang.String attrName, java.lang.Object value)
      Sets the value of an attribute of the file's content.
      void setLastModifiedTime​(long modTime)
      Sets the last-modified timestamp of the file.
      long write​(java.io.OutputStream output)
      Writes this content to an OutputStream.
      long write​(java.io.OutputStream output, int bufferSize)
      Writes this content to an OutputStream.
      long write​(FileContent output)
      Writes this content to another FileContent.
      long write​(FileObject file)
      Writes this content to another FileObject.
    • Method Detail

      • close

        void close()
            throws FileSystemException
        Closes all resources used by the content, including any open stream. Commits pending changes to the file.

        This method is a hint to the implementation that it can release resources. This object can continue to be used after calling this method.

        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        FileSystemException - if an error occurs closing the file.
      • getAttribute

        java.lang.Object getAttribute​(java.lang.String attrName)
                               throws FileSystemException
        Gets the value of an attribute of the file's content.
        Parameters:
        attrName - The name of the attribute. Attribute names are case-insensitive.
        Returns:
        The value of the attribute, or null if the attribute value is unknown.
        Throws:
        FileSystemException - If the file does not exist, or does not support attributes.
      • getAttributeNames

        java.lang.String[] getAttributeNames()
                                      throws FileSystemException
        Gets the attributes of the file's content.
        Returns:
        The names of the attributes. Never returns null;
        Throws:
        FileSystemException - If the file does not exist, or does not support attributes.
      • getAttributes

        java.util.Map<java.lang.String,​java.lang.Object> getAttributes()
                                                                      throws FileSystemException
        Returns a read-only map of this file's attributes.
        Returns:
        The attribute Map.
        Throws:
        FileSystemException - If the file does not exist, or does not support attributes.
      • getByteArray

        default byte[] getByteArray()
                             throws java.io.IOException
        Returns the content of a file as a byte array.
        Returns:
        The content as a byte array.
        Throws:
        java.io.IOException - if the file content cannot be accessed.
        Since:
        2.4
      • getCertificates

        java.security.cert.Certificate[] getCertificates()
                                                  throws FileSystemException
        Gets the certificates if any used to sign this file or folder.
        Returns:
        The certificates, or an empty array if there are no certificates or the file does not support signing.
        Throws:
        FileSystemException - If the file does not exist, or is being written.
      • getFile

        FileObject getFile()
        Gets the file which this is the content of.
        Returns:
        The FileObject this is the content of.
      • getInputStream

        java.io.InputStream getInputStream()
                                    throws FileSystemException
        Gets an input stream for reading the file's content.

        There may only be a single input or output stream open for the file at any time.

        Returns:
        An input stream to read the file's content from. The input stream is buffered, so there is no need to wrap it in a BufferedInputStream.
        Throws:
        FileSystemException - If the file does not exist, or is being read, or is being written, or on error opening the stream.
      • getInputStream

        default java.io.InputStream getInputStream​(int bufferSize)
                                            throws FileSystemException
        Gets an input stream for reading the file's content.

        There may only be a single input or output stream open for the file at any time.

        Parameters:
        bufferSize - The buffer size to use.
        Returns:
        An input stream to read the file's content from. The input stream is buffered, so there is no need to wrap it in a BufferedInputStream.
        Throws:
        FileSystemException - If the file does not exist, or is being read, or is being written, or on error opening the stream.
        Since:
        2.4
      • getLastModifiedTime

        long getLastModifiedTime()
                          throws FileSystemException
        Gets the last-modified timestamp of the file.
        Returns:
        The last-modified timestamp.
        Throws:
        FileSystemException - If the file does not exist, or is being written to, or on error determining the last-modified timestamp.
      • getOutputStream

        java.io.OutputStream getOutputStream()
                                      throws FileSystemException
        Gets an output stream for writing the file's content.

        If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist, it is replaced with whatever is written to the output stream.

        There may only be a single input or output stream open for the file at any time.

        Returns:
        An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it in a BufferedOutputStream.
        Throws:
        FileSystemException - If the file is read-only, or is being read, or is being written, or on error opening the stream.
      • getOutputStream

        java.io.OutputStream getOutputStream​(boolean bAppend)
                                      throws FileSystemException
        Gets an output stream for writing the file's content.

        If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist, it is replaced with whatever is written to the output stream.

        There may only be a single input or output stream open for the file at any time.

        Parameters:
        bAppend - true if you would like to append to the file. This may not be supported by all implementations.
        Returns:
        An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it in a BufferedOutputStream.
        Throws:
        FileSystemException - If the file is read-only, or is being read, or is being written, or bAppend is true and the implementation does not support it, or on error opening the stream.
      • getOutputStream

        default java.io.OutputStream getOutputStream​(boolean bAppend,
                                                     int bufferSize)
                                              throws FileSystemException
        Gets an output stream for writing the file's content.

        If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist, it is replaced with whatever is written to the output stream.

        There may only be a single input or output stream open for the file at any time.

        Parameters:
        bAppend - true if you would like to append to the file. This may not be supported by all implementations.
        bufferSize - The buffer size to use.
        Returns:
        An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it in a BufferedOutputStream.
        Throws:
        FileSystemException - If the file is read-only, or is being read, or is being written, or bAppend is true and the implementation does not support it, or on error opening the stream.
        Since:
        2.4
      • getOutputStream

        default java.io.OutputStream getOutputStream​(int bufferSize)
                                              throws FileSystemException
        Gets an output stream for writing the file's content.

        If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist, it is replaced with whatever is written to the output stream.

        There may only be a single input or output stream open for the file at any time.

        Parameters:
        bufferSize - The buffer size to use.
        Returns:
        An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it in a BufferedOutputStream.
        Throws:
        FileSystemException - If the file is read-only, or is being read, or is being written, or bAppend is true and the implementation does not support it, or on error opening the stream.
        Since:
        2.4
      • getRandomAccessContent

        RandomAccessContent getRandomAccessContent​(RandomAccessMode mode)
                                            throws FileSystemException
        Gets a stream for reading/writing the file's content.

        If the file does not exist, and you use one of the write* methods, this method creates it, and the parent folder, if necessary. If the file does exist, parts of the file are replaced with whatever is written at a given position.

        There may only be a single input or output stream open for the file at any time.

        Parameters:
        mode - The mode to use to access the file.
        Returns:
        the stream for reading and writing the file's content.
        Throws:
        FileSystemException - If the file is read-only, or is being read, or is being written, or on error opening the stream.
      • getSize

        long getSize()
              throws FileSystemException
        Gets the size of the file, in bytes.
        Returns:
        The size of the file, in bytes.
        Throws:
        FileSystemException - If the file does not exist, or is being written to, or on error determining the size.
      • getString

        default java.lang.String getString​(java.nio.charset.Charset charset)
                                    throws java.io.IOException
        Returns the content of a file as a String.
        Parameters:
        charset - The file character set, may be null.
        Returns:
        The content as a byte array.
        Throws:
        java.io.IOException - if the file content cannot be accessed.
        Since:
        2.4
      • getString

        default java.lang.String getString​(java.lang.String charset)
                                    throws java.io.IOException
        Gets the content of a file as a String.
        Parameters:
        charset - The file character set, may be null.
        Returns:
        The content as a byte array.
        Throws:
        java.io.IOException - if the file content cannot be accessed.
        Since:
        2.4
      • hasAttribute

        boolean hasAttribute​(java.lang.String attrName)
                      throws FileSystemException
        Checks if an attribute of the file's content exists.
        Parameters:
        attrName - The name of the attribute.
        Returns:
        true if the attribute exists, false otherwise.
        Throws:
        FileSystemException - If the file does not exist, or does not support attributes.
      • isEmpty

        default boolean isEmpty()
                         throws FileSystemException
        Tests if the receiver is empty.
        Returns:
        true if the receiver is empty, false otherwise.
        Throws:
        FileSystemException - If the file does not exist, or is being written to, or on error determining the size.
        Since:
        2.5.0
      • isOpen

        boolean isOpen()
        Tests if this file has open streams.
        Returns:
        true if the file is open, false otherwise.
      • removeAttribute

        void removeAttribute​(java.lang.String attrName)
                      throws FileSystemException
        Removes the value of an attribute of the file's content.
        Parameters:
        attrName - The name of the attribute.
        Throws:
        FileSystemException - If the file does not exist, or is read-only, or does not support attributes, or on error removing the attribute.
      • setAttribute

        void setAttribute​(java.lang.String attrName,
                          java.lang.Object value)
                   throws FileSystemException
        Sets the value of an attribute of the file's content. Creates the file if it does not exist.
        Parameters:
        attrName - The name of the attribute.
        value - The value of the attribute.
        Throws:
        FileSystemException - If the file does not exist, or is read-only, or does not support attributes, or on error setting the attribute.
      • setLastModifiedTime

        void setLastModifiedTime​(long modTime)
                          throws FileSystemException
        Sets the last-modified timestamp of the file. Creates the file if it does not exist.
        Parameters:
        modTime - The time to set the last-modified timestamp to.
        Throws:
        FileSystemException - If the file is read-only, or is being written to, or on error setting the last-modified timestamp.
      • write

        long write​(FileContent output)
            throws java.io.IOException
        Writes this content to another FileContent.
        Parameters:
        output - The target OutputStream.
        Returns:
        the total number of bytes written
        Throws:
        java.io.IOException - if an error occurs writing the content.
        Since:
        2.1
      • write

        long write​(FileObject file)
            throws java.io.IOException
        Writes this content to another FileObject.
        Parameters:
        file - The target FileObject.
        Returns:
        the total number of bytes written
        Throws:
        java.io.IOException - if an error occurs writing the content.
        Since:
        2.1
      • write

        long write​(java.io.OutputStream output)
            throws java.io.IOException
        Writes this content to an OutputStream.
        Parameters:
        output - The target OutputStream.
        Returns:
        the total number of bytes written
        Throws:
        java.io.IOException - if an error occurs writing the content.
        Since:
        2.1
      • write

        long write​(java.io.OutputStream output,
                   int bufferSize)
            throws java.io.IOException
        Writes this content to an OutputStream.
        Parameters:
        output - The target OutputStream.
        bufferSize - The buffer size to write data chunks.
        Returns:
        the total number of bytes written
        Throws:
        java.io.IOException - if an error occurs writing the file.
        Since:
        2.1