Package tkrzw

Class File

Object
File
public class File extends Object
Generic file implementation.
Note:
All operations except for "open" and "close" are thread-safe; Multiple threads can access the same file concurrently. You can specify a concrete class when you call the "open" method. Every opened file must be closed explicitly by the "close" method to avoid data corruption. Moreover, every unused file object should be destructed by the "destruct" method to free resources.

  • Constructor Summary

    Constructors
    Constructor
    Description
    File()
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    append(byte[] buf)
    Appends data at the end of the file.
    long
    append(byte[] buf, long size, Status status)
    Appends data at the end of the file.
    long
    append(String str)
    Appends data at the end of the file.
    Status
    close()
    Closes the file.
    void
    destruct()
    Destructs the object and releases resources.
    String
    getPath()
    Gets the path of the file.
    long
    getSize()
    Gets the size of the file.
    Status
    open(String path, boolean writable)
    Opens a file, without optional parameters.
    Status
    open(String path, boolean writable, String params)
    Opens a file, with a string expression for optional parameters.
    Status
    open(String path, boolean writable, Map<String,String> params)
    Opens a file.
    Status
    read(long off, byte[] buf, long size)
    Reads data.
    byte[]
    read(long off, long size)
    Reads data and returns a byte array.
    byte[]
    read(long off, long size, Status status)
    Reads data.
    String
    readString(long off, long size)
    Reads data and returns a byte array.
    String
    readString(long off, long size, Status status)
    Reads data and returns a byte array.
    byte[][]
    search(String mode, byte[] pattern, int capacity)
    Searches the file and get lines which match a pattern.
    String[]
    search(String mode, String pattern, int capacity)
    Searches the file and get lines which match a pattern, with string data.
    Status
    synchronize(boolean hard)
    Synchronizes the entire content of the file to the file system.
    Status
    synchronize(boolean hard, long off, long size)
    Synchronizes the content of the file to the file system.
    String
    toString()
    Gets a string representation of the iterator.
    Status
    truncate(long size)
    Truncates the file.
    Status
    write(long off, byte[] buf)
    Writes data.
    Status
    write(long off, byte[] buf, long size)
    Writes data.
    Status
    write(long off, String str)
    Writes a string.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • File

      public File()
      Constructor.

  • Method Details

    • destruct

      public void destruct()
      Destructs the object and releases resources.
      Note:
      The file is closed implicitly if it has not been closed.

    • open

      public Status open(String path, boolean writable, Map<String,String> params)
      Opens a file.
      Parameters:
      path - The path of the file.
      writable - If true, the file is writable. If false, it is read-only.
      params - Optional parameters. If it is null, it is ignored.
      Returns:
      The result status.
      Note:
      The optional parameters can include options for the file opening operation.
      • truncate (bool): True to truncate the file.
      • no_create (bool): True to omit file creation.
      • no_wait (bool): True to fail if the file is locked by another process.
      • no_lock (bool): True to omit file locking.
      • sync_hard (bool): True to do physical synchronization when closing.

      The optional parameter "file" specifies the internal file implementation class. The default file class is "MemoryMapAtomicFile". The other supported classes are "StdFile", "MemoryMapAtomicFile", "PositionalParallelFile", and "PositionalAtomicFile".

      For the file "PositionalParallelFile" and "PositionalAtomicFile", these optional parameters are supported.

      • block_size (int): The block size to which all blocks should be aligned.
      • access_options (str): Values separated by colon. "direct" for direct I/O. "sync" for synchrnizing I/O, "padding" for file size alignment by padding, "pagecache" for the mini page cache in the process.

    • open

      public Status open(String path, boolean writable, String params)
      Opens a file, with a string expression for optional parameters.
      Parameters:
      path - A path of the file.
      writable - If true, the file is writable. If false, it is read-only.
      params - The optional parameter expression in "key=value,key=value" format.
      Returns:
      The result status.

    • open

      public Status open(String path, boolean writable)
      Opens a file, without optional parameters.
      Parameters:
      path - A path of the file.
      writable - If true, the file is writable. If false, it is read-only.
      Returns:
      The result status.

    • close

      public Status close()
      Closes the file.
      Returns:
      The result status.

    • read

      public Status read(long off, byte[] buf, long size)
      Reads data.
      Parameters:
      off - The offset of a source region.
      buf - The destination buffer.
      size - The size to be read.
      Returns:
      The result status.

    • read

      public byte[] read(long off, long size, Status status)
      Reads data.
      Parameters:
      off - The offset of a source region.
      size - The size to be read.
      status - The status object to store the result status. If it is null, it is ignored.
      Returns:
      A byte array containing read data.

    • read

      public byte[] read(long off, long size)
      Reads data and returns a byte array.
      Parameters:
      off - The offset of a source region.
      size - The size to be read.
      Returns:
      A byte array containing read data.

    • readString

      public String readString(long off, long size, Status status)
      Reads data and returns a byte array.
      Parameters:
      off - The offset of a source region.
      size - The size to be read.
      status - The status object to store the result status. If it is null, it is ignored.
      Returns:
      A string containing read data.

    • readString

      public String readString(long off, long size)
      Reads data and returns a byte array.
      Parameters:
      off - The offset of a source region.
      size - The size to be read.
      Returns:
      A string containing read data.

    • write

      public Status write(long off, byte[] buf, long size)
      Writes data.
      Parameters:
      off - The offset of the destination region.
      buf - The source buffer.
      size - The size to be written.
      Returns:
      The result status.

    • write

      public Status write(long off, byte[] buf)
      Writes data.
      Parameters:
      off - The offset of the destination region.
      buf - The source buffer. The written size is the size of the buffer.
      Returns:
      The result status.

    • write

      public Status write(long off, String str)
      Writes a string.
      Parameters:
      off - The offset of the destination region.
      str - The source string.
      Returns:
      The result status.

    • append

      public long append(byte[] buf, long size, Status status)
      Appends data at the end of the file.
      Parameters:
      buf - The source buffer.
      size - The size to be written.
      status - The status object to store the result status. If it is null, it is ignored.
      Returns:
      The offset at which the data has been put, or -1 on failure.

    • append

      public long append(byte[] buf)
      Appends data at the end of the file.
      Parameters:
      buf - The source buffer. The written size is the size of the buffer.
      Returns:
      The offset at which the data has been put, or -1 on failure.

    • append

      public long append(String str)
      Appends data at the end of the file.
      Parameters:
      str - The source string.
      Returns:
      The offset at which the data has been put, or -1 on failure.

    • truncate

      public Status truncate(long size)
      Truncates the file.
      Parameters:
      size - The new size of the file.
      Returns:
      The result status.
      Note:
      If the file is shrunk, data after the new file end is discarded. If the file is expanded, null codes are filled after the old file end.

    • synchronize

      public Status synchronize(boolean hard, long off, long size)
      Synchronizes the content of the file to the file system.
      Parameters:
      hard - True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
      off - The offset of the region to be synchronized.
      size - The size of the region to be synchronized. If it is zero, the length to the end of file is specified.
      Returns:
      The result status.
      Note:
      The pysical file size can be larger than the logical size in order to improve performance by reducing frequency of allocation. Thus, you should call this function before accessing the file with external tools.

    • synchronize

      public Status synchronize(boolean hard)
      Synchronizes the entire content of the file to the file system.
      Parameters:
      hard - True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
      Returns:
      The result status.

    • getSize

      public long getSize()
      Gets the size of the file.
      Returns:
      The size of the file or -1 on failure.

    • getPath

      public String getPath()
      Gets the path of the file.
      Returns:
      The path of the file or null on failure.

    • search

      public byte[][] search(String mode, byte[] pattern, int capacity)
      Searches the file and get lines which match a pattern.
      Parameters:
      mode - The search mode. "contain" extracts keys containing the pattern. "begin" extracts keys beginning with the pattern. "end" extracts keys ending with the pattern. "regex" extracts keys partially matches the pattern of a regular expression. "edit" extracts keys whose edit distance to the UTF-8 pattern is the least. "editbin" extracts keys whose edit distance to the binary pattern is the least. "containcase", "containword", and "containcaseword" extract keys considering case and word boundary. Ordered databases support "upper" and "lower" which extract keys whose positions are upper/lower than the pattern. "upperinc" and "lowerinc" are their inclusive versions.
      pattern - The pattern for matching.
      capacity - The maximum records to obtain. 0 means unlimited.
      Returns:
      An array of lines matching the condition.

    • search

      public String[] search(String mode, String pattern, int capacity)
      Searches the file and get lines which match a pattern, with string data.
      Parameters:
      mode - The search mode. "contain" extracts keys containing the pattern. "begin" extracts keys beginning with the pattern. "end" extracts keys ending with the pattern. "regex" extracts keys partially matches the pattern of a regular expression. "edit" extracts keys whose edit distance to the UTF-8 pattern is the least. "editbin" extracts keys whose edit distance to the binary pattern is the least. "containcase", "containword", and "containcaseword" extract keys considering case and word boundary. Ordered databases support "upper" and "lower" which extract keys whose positions are upper/lower than the pattern. "upperinc" and "lowerinc" are their inclusive versions.
      pattern - The pattern for matching.
      capacity - The maximum records to obtain. 0 means unlimited.
      Returns:
      An array of lines matching the condition.

    • toString

      public String toString()
      Gets a string representation of the iterator.
      Overrides:
      toString in class Object