Package org.scijava.io.handle

Interface DataHandle<L extends Location>

    • Field Detail

      • DEFAULT_BLOCK_SIZE

        static final int DEFAULT_BLOCK_SIZE
        Default block size to use when searching through the stream.
        See Also:
        Constant Field Values

      • MAX_SEARCH_SIZE

        static final int MAX_SEARCH_SIZE
        Default bound on bytes to search when searching through the stream.
        See Also:
        Constant Field Values

    • Method Detail

      • isReadable

        boolean isReadable()
        Gets whether reading from this handle is supported.

      • isWritable

        boolean isWritable()
        Gets whether writing to this handle is supported.

      • exists

        boolean exists()
        throws IOException
        Tests whether this handle's location actually exists at the source.
        Returns:
        True if the location exists; false if not.
        Throws:
        IOException - If something goes wrong with the existence check.

      • lastModified

        default Date lastModified()
                   throws IOException
        Gets the last modified timestamp of the location.
        Returns:
        The last modified timestamp, or null if the handle does not support this feature or if the location does not exist.
        Throws:
        IOException - If something goes wrong with the last modified check.

      • checksum

        default String checksum()
                 throws IOException
        Gets a "fast" checksum which succinctly represents the contents of the data stream. The term "fast" here refers to the idea that the checksum be retrievable quickly, without actually performing a thorough computation across the entire data stream. Typically, such a thing is feasible because the checksum was calculated a priori; e.g., artifacts deployed to remote Maven repositories are always deployed with corresponding checksum files.

        No guarantee is made about the exact nature of the checksum (e.g., SHA-1 or MD5), only that the value is deterministic for this particular location with its current contents. In other words: if a checksum differs from a previous inquiry, you can be sure the contents have changed; conversely, if the checksum is still the same, the contents are highly likely to be unchanged.

        Returns:
        The checksum, or null if the handle does not support this feature.
        Throws:
        IOException - If something goes wrong when accessing the checksum.

      • seek

        void seek​(long pos)
   throws IOException
        Sets the stream offset, measured from the beginning of the stream, at which the next read or write occurs.
        Throws:
        IOException

      • length

        long length()
     throws IOException
        Returns the length of the data in bytes.
        Returns:
        The length, or -1 if the length is unknown.
        Throws:
        IOException

      • setLength

        void setLength​(long length)
        throws IOException
        Sets the new length of the handle.
        Parameters:
        length - New length.
        Throws:
        IOException - If there is an error changing the handle's length.

      • available

        default long available​(long count)
                throws IOException
        Gets the number of bytes which can be read from, or written to, the data handle, bounded by the specified number of bytes.

        In the case of reading, attempting to read the returned number of bytes is guaranteed not to throw EOFException. However, be aware that the following methods might still process fewer bytes than indicated by this method:

        In the case of writing, attempting to write the returned number of bytes is guaranteed not to expand the length of the handle; i.e., the write will only overwrite bytes already within the handle's bounds.

        Parameters:
        count - Desired number of bytes to read/write.
        Returns:
        The actual number of bytes which could be read/written, which might be less than the requested value.
        Throws:
        IOException - If something goes wrong with the check.

      • ensureReadable

        default void ensureReadable​(long count)
                     throws IOException
        Ensures that the handle has sufficient bytes available to read.
        Parameters:
        count - Number of bytes to read.
        Throws:
        EOFException - If there are insufficient bytes available.
        IOException - If the handle is write-only, or something goes wrong with the check.
        See Also:
        available(long)

      • ensureWritable

        default boolean ensureWritable​(long count)
                        throws IOException
        Ensures that the handle has the correct length to be written to, and extends it as required.
        Parameters:
        count - Number of bytes to write.
        Returns:
        true if the handle's length was sufficient, or false if the handle's length required an extension.
        Throws:
        IOException - If the handle is read-only, or something goes wrong with the check, or there is an error changing the handle's length.

      • setOrder

        void setOrder​(DataHandle.ByteOrder order)
        Sets the byte order of the stream.
        Parameters:
        order - Order to set.

      • getEncoding

        String getEncoding()
        Gets the native encoding of the stream.

      • setEncoding

        void setEncoding​(String encoding)
        Sets the native encoding of the stream.

      • conversionBuffer

        byte[] conversionBuffer()
        Returns:
        a 8 byte long buffer array used for type conversions

      • readCString

        default String readCString()
                    throws IOException
        Reads a string of arbitrary length, terminated by a null char.
        Throws:
        IOException

      • findString

        default String findString​(String... terminators)
                   throws IOException
        Reads a string ending with one of the given terminating substrings.
        Parameters:
        terminators - The strings for which to search.
        Returns:
        The string from the initial position through the end of the terminating sequence, or through the end of the stream if no terminating sequence is found.
        Throws:
        IOException

      • findString

        default String findString​(boolean saveString,
                          String... terminators)
                   throws IOException
        Reads or skips a string ending with one of the given terminating substrings.
        Parameters:
        saveString - Whether to collect the string from the current offset to the terminating bytes, and return it. If false, returns null.
        terminators - The strings for which to search.
        Returns:
        The string from the initial position through the end of the terminating sequence, or through the end of the stream if no terminating sequence is found, or null if saveString flag is unset.
        Throws:
        IOException - If saveString flag is set and the maximum search length (512 MB) is exceeded.

      • findString

        default String findString​(int blockSize,
                          String... terminators)
                   throws IOException
        Reads a string ending with one of the given terminating substrings, using the specified block size for buffering.
        Parameters:
        blockSize - The block size to use when reading bytes in chunks.
        terminators - The strings for which to search.
        Returns:
        The string from the initial position through the end of the terminating sequence, or through the end of the stream if no terminating sequence is found.
        Throws:
        IOException

      • findString

        default String findString​(boolean saveString,
                          int blockSize,
                          String... terminators)
                   throws IOException
        Reads or skips a string ending with one of the given terminating substrings, using the specified block size for buffering.
        Parameters:
        saveString - Whether to collect the string from the current offset to the terminating bytes, and return it. If false, returns null.
        blockSize - The block size to use when reading bytes in chunks.
        terminators - The strings for which to search.
        Returns:
        The string from the initial position through the end of the terminating sequence, or through the end of the stream if no terminating sequence is found, or null if saveString flag is unset.
        Throws:
        IOException - If saveString flag is set and the maximum search length (512 MB) is exceeded.

      • writeLine

        default void writeLine​(String string)
                throws IOException
        Writes the provided string, followed by a newline character.
        Parameters:
        string - The string to write.
        Throws:
        IOException - If an I/O error occurs.

      • read

        default int read()
          throws IOException
        Reads the next byte of data from the stream.
        Returns:
        the next byte of data, or -1 if the end of the stream is reached.
        Throws:
        IOException - - if an I/O error occurs.

      • read

        default int read​(byte[] b)
          throws IOException
        Reads up to b.length bytes of data from the stream into an array of bytes.
        Returns:
        the total number of bytes read into the buffer.
        Throws:
        IOException

      • read

        int read​(byte[] b,
         int off,
         int len)
  throws IOException
        Reads up to len bytes of data from the stream into an array of bytes.
        Returns:
        the total number of bytes read into the buffer.
        Throws:
        IOException

      • skip

        default long skip​(long n)
           throws IOException
        Skips over and discards n bytes of data from the stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. The actual number of bytes skipped is returned. If n is negative, no bytes are skipped.
        Parameters:
        n - - the number of bytes to be skipped.
        Returns:
        the actual number of bytes skipped.
        Throws:
        IOException - - if an I/O error occurs.