1 /*
2 * #%L
3 * nom.tam FITS library
4 * %%
5 * Copyright (C) 1996 - 2024 nom-tam-fits
6 * %%
7 * This is free and unencumbered software released into the public domain.
8 *
9 * Anyone is free to copy, modify, publish, use, compile, sell, or
10 * distribute this software, either in source code form or as a compiled
11 * binary, for any purpose, commercial or non-commercial, and by any
12 * means.
13 *
14 * In jurisdictions that recognize copyright laws, the author or authors
15 * of this software dedicate any and all copyright interest in the
16 * software to the public domain. We make this dedication for the benefit
17 * of the public at large and to the detriment of our heirs and
18 * successors. We intend this dedication to be an overt act of
19 * relinquishment in perpetuity of all present and future rights to this
20 * software under copyright law.
21 *
22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
23 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
25 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
26 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
27 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
28 * OTHER DEALINGS IN THE SOFTWARE.
29 * #L%
30 */
31
32 package nom.tam.util;
33
34 import java.io.BufferedOutputStream;
35 import java.io.IOException;
36 import java.io.OutputStream;
37
38 /**
39 * Efficient writing of binary arrays to streams with custom binary encoding.
40 *
41 * @author Attila Kovacs
42 * @since 1.16
43 * @see ArrayInputStream
44 * @see ArrayDataFile
45 */
46 public class ArrayOutputStream extends BufferedOutputStream implements OutputWriter {
47
48 /** conversion from Java arrays to FITS binary representation */
49 private OutputEncoder encoder;
50
51 /**
52 * Instantiates a new output stream for efficient array transactions. For
53 * use by subclass constructors only.
54 *
55 * @param o
56 * the underlying output stream
57 * @param bufLength
58 * the buffer size in bytes.
59 */
60 protected ArrayOutputStream(OutputStream o, int bufLength) {
61 super(o, bufLength);
62 }
63
64 /**
65 * Instantiates a new output stream for efficient array transactions.
66 *
67 * @param o
68 * the underlying output stream
69 * @param bufLength
70 * the buffer size in bytes.
71 * @param java2bin
72 * the conversion from Java arrays to the binary representation
73 * in the stream.
74 */
75 public ArrayOutputStream(OutputStream o, int bufLength, OutputEncoder java2bin) {
76 this(o, bufLength);
77 setEncoder(java2bin);
78 }
79
80 /**
81 * Sets the conversion from Java arrays to their binary representation in
82 * the stream. For use by subclass constructors only.
83 *
84 * @param java2bin
85 * the conversion from Java arrays to their binary representation
86 * in stream
87 * @see #getEncoder()
88 */
89 protected void setEncoder(OutputEncoder java2bin) {
90 encoder = java2bin;
91 }
92
93 /**
94 * Returns the conversion from Java arrays to their binary representation in
95 * the stream. Subclass implementeations can use this to access the required
96 * conversion when writing data to file.
97 *
98 * @return the conversion from Java arrays to their binary representation in
99 * stream
100 * @see #setEncoder(OutputEncoder)
101 */
102 protected OutputEncoder getEncoder() {
103 return encoder;
104 }
105
106 /**
107 * See {@link ArrayDataOutput#writeArray(Object)} for a contract of this
108 * method.
109 *
110 * @param o
111 * an array ot any type.
112 * @throws IllegalArgumentException
113 * if the argument is not an array or if it contains an element
114 * that is not supported for encoding.
115 * @throws IOException
116 * if there was an IO error writing to the output.
117 */
118 public synchronized void writeArray(Object o) throws IOException, IllegalArgumentException {
119 try {
120 encoder.writeArray(o);
121 } catch (IllegalArgumentException e) {
122 throw new IOException(e);
123 }
124 }
125 }