Tinker around for an POSIX file APIwip-FileAbstraction-20230113

1 files changed, 70 insertions, 0 deletions

diff --git a/xtra4j-misc/src/main/java/ch/hiddenalpha/xtra4j/file/File.java b/xtra4j-misc/src/main/java/ch/hiddenalpha/xtra4j/file/File.java
new file mode 100644
index 0000000..be9110d
--- /dev/null
+++ b/xtra4j-misc/src/main/java/ch/hiddenalpha/xtra4j/file/File.java
@@ -0,0 +1,70 @@
+package ch.hiddenalpha.xtra4j.file;
+
+import java.io.IOException;
+
+
+public interface File {
+
+    /**
+     * <p>Based on <a href="https://pubs.opengroup.org/onlinepubs/009695399/functions/fread.html">
+     * POSIX fread</a>. Nevertheless there are some differences (keep reading below).</p>
+     *
+     * <p>If at least one of 'off', 'size' or 'count' is negative, behavior is
+     * undefined</p>
+     *
+     * <p>If 'size' times 'count' is outside range 0 to INT_MAX, behavior is
+     * undefined.</p>
+     *
+     * <p>If 'off', 'size' and 'count' provocate to write outside bounds of given
+     * 'buf', behavior is undefined.</p>
+     *
+     * @param buf
+     *      Buffer where requested data gets written to. MUST NOT be null.
+     * @param off
+     *      Index of buf where the first byte gets written.
+     * @param size
+     *      Size in bytes of one element. If you don't care, pass 1.
+     * @param count
+     *      How many times 'size' bytes get read maximally.
+     * @return
+     *      Count of read elements. This equals to bytes if 'size' is 1. Be aware
+     *      that in future, this may return negative values. For now those are
+     *      not defined but a caller has to be aware that this may be the case
+     *      in future.
+     */
+    int read(byte[] buf, int off, int size, int count) throws IOException;
+
+    /**
+     * <p>Based on <a href="https://pubs.opengroup.org/onlinepubs/009695399/functions/fwrite.html">
+     * POSIX fwrite</a></p>.
+     *
+     * <p>Caller has to ensure that combination of passed arguments always stay
+     * inside bounds and especially that 'size' times 'count' does NOT overflow.
+     * Ignoring those, results in undefined behavior.</p>
+     *
+     * @param buf
+     *      Buffer holding the data to write.
+     * @param off
+     *      Index of 'buf' where first byte gets read from.
+     * @param size
+     *      Size in bytes of one element. If you don't care, pass 1.
+     * @param count
+     *      How many elements of size 'size' are to read.
+     * @return
+     *      Count of written elements. This equals to bytes if 'size' is 1. For
+     *      now those are not defined but a caller has to be aware that this may
+     *      be the case in future.
+     */
+    int write(byte[] buf, int off, int size, int count) throws IOException;
+
+    /**
+     * <p>Based on <a href="https://pubs.opengroup.org/onlinepubs/009695399/functions/fseek.html">
+     * POSIX fseek</a>.</p>
+     *
+     * @param offset
+     * @param whence
+     * @return
+     */
+    int fseek(long offset, int whence);
+
+}