StemmerPatchTrieBinaryIO.java

1 
/*******************************************************************************
2 
 * Copyright (C) 2026, Leo Galambos
3 
 * All rights reserved.
4 
 *
5 
 * Redistribution and use in source and binary forms, with or without
6 
 * modification, are permitted provided that the following conditions are met:
7 
 *
8 
 * 1. Redistributions of source code must retain the above copyright notice,
9 
 *    this list of conditions and the following disclaimer.
10 
 *
11 
 * 2. Redistributions in binary form must reproduce the above copyright notice,
12 
 *    this list of conditions and the following disclaimer in the documentation
13 
 *    and/or other materials provided with the distribution.
14 
 *
15 
 * 3. Neither the name of the copyright holder nor the names of its contributors
16 
 *    may be used to endorse or promote products derived from this software
17 
 *    without specific prior written permission.
18 
 *
19 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
23 
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 
 * POSSIBILITY OF SUCH DAMAGE.
30 
 ******************************************************************************/
31 
package org.egothor.stemmer;
32
33 
import java.io.BufferedInputStream;
34 
import java.io.BufferedOutputStream;
35 
import java.io.DataInputStream;
36 
import java.io.DataOutputStream;
37 
import java.io.IOException;
38 
import java.io.InputStream;
39 
import java.io.OutputStream;
40 
import java.nio.file.Files;
41 
import java.nio.file.Path;
42 
import java.util.Objects;
43 
import java.util.logging.Level;
44 
import java.util.logging.Logger;
45 
import java.util.zip.GZIPInputStream;
46 
import java.util.zip.GZIPOutputStream;
47
48 
/**
49 
 * Binary persistence helper for patch-command stemmer tries.
50 
 *
51 
 * <p>
52 
 * This class persists {@link FrequencyTrie} instances whose values are compact
53 
 * patch commands represented as {@link String}. The serialized trie payload is
54 
 * the native binary format of {@link FrequencyTrie}, wrapped in GZip
55 
 * compression.
56 
 *
57 
 * <p>
58 
 * The helper centralizes the codec and compression details so that higher-level
59 
 * loader APIs can remain focused on source selection rather than stream
60 
 * mechanics.
61 
 */
62 
public final class StemmerPatchTrieBinaryIO {
63
64 
    /**
65 
     * Logger of this class.
66 
     */
67 
    private static final Logger LOGGER = Logger.getLogger(StemmerPatchTrieBinaryIO.class.getName());
68
69 
    /**
70 
     * Value codec for persisted patch-command strings.
71 
     */
72 
    private static final FrequencyTrie.ValueStreamCodec<String> STRING_CODEC = new StringValueStreamCodec();
73
74 
    /**
75 
     * Utility class.
76 
     */
77 
    private StemmerPatchTrieBinaryIO() {
78 
        throw new AssertionError("No instances.");
79 
    }
80
81 
    /**
82 
     * Reads a GZip-compressed binary patch-command trie from a filesystem path.
83 
     *
84 
     * @param path source file
85 
     * @return deserialized trie
86 
     * @throws NullPointerException if {@code path} is {@code null}
87 
     * @throws IOException          if reading or decompression fails
88 
     */
89 
    public static FrequencyTrie<String> read(final Path path) throws IOException {
90 
        Objects.requireNonNull(path, "path");
91
92 
        try (InputStream fileInputStream = Files.newInputStream(path)) {
93 1 1. read : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED
 
            return read(fileInputStream);
94 
        }
95 
    }
96
97 
    /**
98 
     * Reads a GZip-compressed binary patch-command trie from a filesystem path with
99 
     * an optional dense child lookup span override.
100 
     * <p>
101 
     * This is a runtime-only tuning parameter. The dense-span setting is not
102 
     * persisted in the file and does not change the compiled metadata.
103 
     * </p>
104 
     *
105 
     * @param path             source file
106 
     * @param maxExpandedIndex dense lookup span override; negative values use
107 
     *                         {@link FrequencyTrie#DEFAULT_MAX_EXPANDED_INDEX}
108 
     * @return deserialized trie
109 
     * @throws NullPointerException if {@code path} is {@code null}
110 
     * @throws IOException          if reading or decompression fails
111 
     */
112 
    public static FrequencyTrie<String> read(final Path path, final int maxExpandedIndex) throws IOException {
113 
        Objects.requireNonNull(path, "path");
114
115 
        try (InputStream fileInputStream = Files.newInputStream(path)) {
116 1 1. read : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED
 
            return read(fileInputStream, maxExpandedIndex);
117 
        }
118 
    }
119
120 
    /**
121 
     * Reads a GZip-compressed binary patch-command trie from a filesystem path
122 
     * string.
123 
     *
124 
     * @param fileName source file name or path string
125 
     * @return deserialized trie
126 
     * @throws NullPointerException if {@code fileName} is {@code null}
127 
     * @throws IOException          if reading or decompression fails
128 
     */
129 
    public static FrequencyTrie<String> read(final String fileName) throws IOException {
130 
        Objects.requireNonNull(fileName, "fileName");
131 1 1. read : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED
 
        return read(Path.of(fileName));
132 
    }
133
134 
    /**
135 
     * Reads a GZip-compressed binary patch-command trie from a filesystem path
136 
     * string with an optional dense child lookup span override.
137 
     * <p>
138 
     * This is a runtime-only tuning parameter. The dense-span setting is not
139 
     * persisted in the file and does not change the compiled metadata.
140 
     * </p>
141 
     *
142 
     * @param fileName         source file name or path string
143 
     * @param maxExpandedIndex dense lookup span override; negative values use
144 
     *                         {@link FrequencyTrie#DEFAULT_MAX_EXPANDED_INDEX}
145 
     * @return deserialized trie
146 
     * @throws NullPointerException if {@code fileName} is {@code null}
147 
     * @throws IOException          if reading or decompression fails
148 
     */
149 
    public static FrequencyTrie<String> read(final String fileName, final int maxExpandedIndex) throws IOException {
150 
        Objects.requireNonNull(fileName, "fileName");
151 1 1. read : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED
 
        return read(Path.of(fileName), maxExpandedIndex);
152 
    }
153
154 
    /**
155 
     * Reads a GZip-compressed binary patch-command trie from an input stream.
156 
     *
157 
     * <p>
158 
     * The supplied stream is consumed but not interpreted as plain trie bytes; it
159 
     * is first decompressed using {@link GZIPInputStream}.
160 
     *
161 
     * @param inputStream source stream
162 
     * @return deserialized trie
163 
     * @throws NullPointerException if {@code inputStream} is {@code null}
164 
     * @throws IOException          if reading or decompression fails
165 
     */
166 
    public static FrequencyTrie<String> read(final InputStream inputStream) throws IOException {
167 
        Objects.requireNonNull(inputStream, "inputStream");
168
169 
        try (GZIPInputStream gzipInputStream = new GZIPInputStream(new BufferedInputStream(inputStream));
170 
                DataInputStream dataInputStream = new DataInputStream(gzipInputStream)) {
171 1 1. lambda$read$0 : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::lambda$read$0 → KILLED
 
            final FrequencyTrie<String> trie = FrequencyTrie.readFrom(dataInputStream, String[]::new, STRING_CODEC);
172
173 
            LOGGER.log(Level.FINE, "Read compressed binary stemmer trie.");
174 1 1. read : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED
 
            return trie;
175 
        }
176 
    }
177
178 
    /**
179 
     * Reads a GZip-compressed binary patch-command trie from an input stream with
180 
     * an optional dense child lookup span override.
181 
     * <p>
182 
     * This is a runtime-only tuning parameter. The dense-span setting is not
183 
     * persisted in the file and does not change the compiled metadata.
184 
     * </p>
185 
     *
186 
     * @param inputStream      source stream
187 
     * @param maxExpandedIndex dense lookup span override; negative values use
188 
     *                         {@link FrequencyTrie#DEFAULT_MAX_EXPANDED_INDEX}
189 
     * @return deserialized trie
190 
     * @throws NullPointerException if {@code inputStream} is {@code null}
191 
     * @throws IOException          if reading or decompression fails
192 
     */
193 
    public static FrequencyTrie<String> read(final InputStream inputStream, final int maxExpandedIndex)
194 
            throws IOException {
195 
        Objects.requireNonNull(inputStream, "inputStream");
196
197 
        try (GZIPInputStream gzipInputStream = new GZIPInputStream(new BufferedInputStream(inputStream));
198 
                DataInputStream dataInputStream = new DataInputStream(gzipInputStream)) {
199 1 1. lambda$read$1 : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::lambda$read$1 → NO_COVERAGE
 
            final FrequencyTrie<String> trie = FrequencyTrie.readFrom(dataInputStream, String[]::new, STRING_CODEC,
200 
                    maxExpandedIndex);
201
202 
            LOGGER.log(Level.FINE, "Read compressed binary stemmer trie.");
203 1 1. read : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED
 
            return trie;
204 
        }
205 
    }
206
207 
    /**
208 
     * Reads only metadata from a GZip-compressed binary patch-command trie stored
209 
     * at a filesystem path.
210 
     *
211 
     * @param path source file
212 
     * @return deserialized trie metadata
213 
     * @throws NullPointerException if {@code path} is {@code null}
214 
     * @throws IOException          if reading or decompression fails
215 
     */
216 
    public static TrieMetadata readMetadata(final Path path) throws IOException {
217 
        Objects.requireNonNull(path, "path");
218 1 1. readMetadata : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → KILLED
 
        return read(path).metadata();
219 
    }
220
221 
    /**
222 
     * Reads only metadata from a GZip-compressed binary patch-command trie stored
223 
     * at a filesystem path string.
224 
     *
225 
     * @param fileName source file name or path string
226 
     * @return deserialized trie metadata
227 
     * @throws NullPointerException if {@code fileName} is {@code null}
228 
     * @throws IOException          if reading or decompression fails
229 
     */
230 
    public static TrieMetadata readMetadata(final String fileName) throws IOException {
231 
        Objects.requireNonNull(fileName, "fileName");
232 1 1. readMetadata : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → KILLED
 
        return readMetadata(Path.of(fileName));
233 
    }
234
235 
    /**
236 
     * Reads only metadata from a GZip-compressed binary patch-command trie from an
237 
     * input stream.
238 
     *
239 
     * @param inputStream source stream
240 
     * @return deserialized trie metadata
241 
     * @throws NullPointerException if {@code inputStream} is {@code null}
242 
     * @throws IOException          if reading or decompression fails
243 
     */
244 
    public static TrieMetadata readMetadata(final InputStream inputStream) throws IOException {
245 
        Objects.requireNonNull(inputStream, "inputStream");
246 1 1. readMetadata : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → KILLED
 
        return read(inputStream).metadata();
247 
    }
248
249 
    /**
250 
     * Writes a GZip-compressed binary patch-command trie to a filesystem path.
251 
     *
252 
     * @param trie trie to persist
253 
     * @param path target file
254 
     * @throws NullPointerException if any argument is {@code null}
255 
     * @throws IOException          if writing fails
256 
     */
257 
    public static void write(final FrequencyTrie<String> trie, final Path path) throws IOException {
258 
        Objects.requireNonNull(trie, "trie");
259 
        Objects.requireNonNull(path, "path");
260
261 
        final Path parent = path.toAbsolutePath().getParent();
262 1 1. write : negated conditional → KILLED
 
        if (parent != null) {
263 
            Files.createDirectories(parent);
264 
        }
265
266 
        try (OutputStream fileOutputStream = Files.newOutputStream(path)) {
267 1 1. write : removed call to org/egothor/stemmer/StemmerPatchTrieBinaryIO::write → KILLED
 
            write(trie, fileOutputStream);
268 
        }
269 
    }
270
271 
    /**
272 
     * Writes a GZip-compressed binary patch-command trie to a filesystem path
273 
     * string.
274 
     *
275 
     * @param trie     trie to persist
276 
     * @param fileName target file name or path string
277 
     * @throws NullPointerException if any argument is {@code null}
278 
     * @throws IOException          if writing fails
279 
     */
280 
    public static void write(final FrequencyTrie<String> trie, final String fileName) throws IOException {
281 
        Objects.requireNonNull(fileName, "fileName");
282 1 1. write : removed call to org/egothor/stemmer/StemmerPatchTrieBinaryIO::write → KILLED
 
        write(trie, Path.of(fileName));
283 
    }
284
285 
    /**
286 
     * Writes a GZip-compressed binary patch-command trie to an output stream.
287 
     *
288 
     * @param trie         trie to persist
289 
     * @param outputStream target stream
290 
     * @throws NullPointerException if any argument is {@code null}
291 
     * @throws IOException          if writing fails
292 
     */
293 
    public static void write(final FrequencyTrie<String> trie, final OutputStream outputStream) throws IOException {
294 
        Objects.requireNonNull(trie, "trie");
295 
        Objects.requireNonNull(outputStream, "outputStream");
296
297 
        try (GZIPOutputStream gzipOutputStream = new GZIPOutputStream(new BufferedOutputStream(outputStream));
298 
                DataOutputStream dataOutputStream = new DataOutputStream(gzipOutputStream)) {
299 1 1. write : removed call to org/egothor/stemmer/FrequencyTrie::writeTo → KILLED
 
            trie.writeTo(dataOutputStream, STRING_CODEC);
300 
        }
301
302 
        LOGGER.log(Level.FINE, "Wrote compressed binary stemmer trie.");
303 
    }
304
305 
    /**
306 
     * Binary stream codec for persisted patch-command strings.
307 
     */
308 
    private static final class StringValueStreamCodec implements FrequencyTrie.ValueStreamCodec<String> {
309
310 
        /**
311 
         * Creates a codec instance.
312 
         */
313 
        private StringValueStreamCodec() {
314 
        }
315
316 
        @Override
317 
        public void write(final DataOutputStream dataOutput, final String value) throws IOException {
318 1 1. write : removed call to java/io/DataOutputStream::writeUTF → KILLED
 
            dataOutput.writeUTF(value);
319 
        }
320
321 
        @Override
322 
        public String read(final DataInputStream dataInput) throws IOException {
323 1 1. read : replaced return value with "" for org/egothor/stemmer/StemmerPatchTrieBinaryIO$StringValueStreamCodec::read → KILLED
 
            return dataInput.readUTF();
324 
        }
325 
    }
326 
}

Mutations

93

1.1
Location : read
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldReadGzipPayloadFromFileNameString()] replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED

116

1.1
Location : read
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldDelegatePathReadWithDenseSpanOverride()] replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED

131

1.1
Location : read
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldReadGzipPayloadFromFileNameString()] replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED

151

1.1
Location : read
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldDelegateStringReadWithDenseSpanOverride()] replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED

171

1.1
Location : lambda$read$0
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldReadMetadataFromGzipPayload()] replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::lambda$read$0 → KILLED

174

1.1
Location : read
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldReadGzipPayloadFromPath()] replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED

199

1.1
Location : lambda$read$1
Killed by : none replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::lambda$read$1 → NO_COVERAGE

203

1.1
Location : read
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldDelegateInputStreamReadWithDenseSpanOverride()] replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED

218

1.1
Location : readMetadata
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldReadMetadataFromPath()] replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → KILLED

232

1.1
Location : readMetadata
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldReadMetadataFromStringPath()] replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → KILLED

246

1.1
Location : readMetadata
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldReadMetadataFromGzipPayload()] replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → KILLED

262

1.1
Location : write
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:WriteTests]/[method:shouldCreateParentDirectoriesAndWriteGzipFile()] negated conditional → KILLED

267

1.1
Location : write
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:WriteTests]/[method:shouldWriteToFilesystemWhenFileNameStringIsUsed()] removed call to org/egothor/stemmer/StemmerPatchTrieBinaryIO::write → KILLED

282

1.1
Location : write
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:WriteTests]/[method:shouldRejectNullArgumentsAcrossAllWriteOverloads()] removed call to org/egothor/stemmer/StemmerPatchTrieBinaryIO::write → KILLED

299

1.1
Location : write
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:WriteTests]/[method:shouldPropagateWriteFailureFromTrieSerialization()] removed call to org/egothor/stemmer/FrequencyTrie::writeTo → KILLED

318

1.1
Location : write
Killed by : org.egothor.stemmer.StemmerPatchTrieBinaryIOTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.StemmerPatchTrieBinaryIOTest]/[nested-class:ReadTests]/[method:shouldReadMetadataFromGzipPayload()] removed call to java/io/DataOutputStream::writeUTF → KILLED

323

1.1
Location : read
Killed by : org.egothor.stemmer.CompiledTrieArtifactRegressionTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.CompiledTrieArtifactRegressionTest]/[test-template:shouldKeepGoldenArtifactReadableAndHashStable(org.egothor.stemmer.CompiledTrieArtifactRegressionTest$ArtifactCase)]/[test-template-invocation:#3] replaced return value with "" for org/egothor/stemmer/StemmerPatchTrieBinaryIO$StringValueStreamCodec::read → KILLED

Active mutators

Tests examined


Report generated by PIT 1.22.1