1 package nom.tam.util;
2
3 /*
4 * #%L
5 * nom.tam FITS library
6 * %%
7 * Copyright (C) 1996 - 2024 nom-tam-fits
8 * %%
9 * This is free and unencumbered software released into the public domain.
10 *
11 * Anyone is free to copy, modify, publish, use, compile, sell, or
12 * distribute this software, either in source code form or as a compiled
13 * binary, for any purpose, commercial or non-commercial, and by any
14 * means.
15 *
16 * In jurisdictions that recognize copyright laws, the author or authors
17 * of this software dedicate any and all copyright interest in the
18 * software to the public domain. We make this dedication for the benefit
19 * of the public at large and to the detriment of our heirs and
20 * successors. We intend this dedication to be an overt act of
21 * relinquishment in perpetuity of all present and future rights to this
22 * software under copyright law.
23 *
24 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
25 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
26 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
27 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
28 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
29 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
30 * OTHER DEALINGS IN THE SOFTWARE.
31 * #L%
32 */
33
34 import java.io.Closeable;
35 import java.io.FileDescriptor;
36 import java.io.IOException;
37 import java.io.RandomAccessFile;
38 import java.nio.channels.FileChannel;
39
40 /**
41 * Interface for IO objects that support file-like random access. The methods defined here are those used by FitsFile to
42 * access a RandomAccessFile. The RandomAccessFileExt class adds this interface to RandomAccessFile, but other systems
43 * could provide an alternate implementation of this interface to access an arbitrary FITS data object.
44 *
45 * @author pdowler
46 */
47 public interface RandomAccessFileIO extends ReadWriteAccess, Closeable {
48
49 /**
50 * Reads data, fully populating the supplied array.
51 *
52 * @param bytes An array which to fill with data from the input
53 *
54 * @return The number of bytes read, which may be fewer than the destination array size.
55 *
56 * @throws IOException if there was an error reading the requisite data from the input
57 *
58 * @see #read(byte[], int, int)
59 * @see #write(byte[])
60 */
61 default int read(byte[] bytes) throws IOException {
62 return read(bytes, 0, bytes.length);
63 }
64
65 /**
66 * See {@link RandomAccessFile#readUTF()} for a contract of this method.
67 *
68 * @return Reads a UTF string from the input, up to an EOL termination (with <code>\n</code>) or until
69 * the end of file, whichever comes first.
70 *
71 * @throws IOException if there was an error reading the requisite data from the input
72 *
73 * @see #writeUTF(String)
74 * @see RandomAccessFile#readUTF()
75 */
76 String readUTF() throws IOException;
77
78 /**
79 * Obtain the current FileChannel instance. For instances that do not use File backed sources
80 *
81 * @see RandomAccessFile#getChannel()
82 *
83 * @return FileChannel instance, possibly null.
84 */
85 FileChannel getChannel();
86
87 /**
88 * Obtain the current FileDescriptor instance.
89 *
90 * @see RandomAccessFile#getFD()
91 *
92 * @return FileDescriptor instance, or possibly null.
93 *
94 * @throws IOException For any I/O errors.
95 */
96 FileDescriptor getFD() throws IOException;
97
98 /**
99 * Write all data from the the supplied array.
100 *
101 * @param bytes the data array
102 *
103 * @throws IOException if there was an error writing the data to the output
104 *
105 * @see #write(byte[], int, int)
106 * @see #read(byte[])
107 */
108 default void write(byte[] bytes) throws IOException {
109 write(bytes, 0, bytes.length);
110 }
111
112 /**
113 * See {@link RandomAccessFile#setLength(long)} for a contract of this method.
114 *
115 * @param length The new file length.
116 *
117 * @throws IOException if there was an error executing the request.
118 *
119 * @see RandomAccessFile#setLength(long)
120 */
121 void setLength(long length) throws IOException;
122
123 /**
124 * See {@link RandomAccessFile#writeUTF(String)} for a contract of this method.
125 *
126 * @param s A java string.
127 *
128 * @throws IOException if there was an error writing the requisite data to the output
129 *
130 * @see #readUTF()
131 * @see RandomAccessFile#writeUTF(String)
132 */
133 void writeUTF(String s) throws IOException;
134 }