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
99 
     * string.
100 
     *
101 
     * @param fileName source file name or path string
102 
     * @return deserialized trie
103 
     * @throws NullPointerException if {@code fileName} is {@code null}
104 
     * @throws IOException          if reading or decompression fails
105 
     */
106 
    public static FrequencyTrie<String> read(final String fileName) throws IOException {
107 
        Objects.requireNonNull(fileName, "fileName");
108 1 1. read : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED
 
        return read(Path.of(fileName));
109 
    }
110
111 
    /**
112 
     * Reads a GZip-compressed binary patch-command trie from an input stream.
113 
     *
114 
     * <p>
115 
     * The supplied stream is consumed but not interpreted as plain trie bytes; it
116 
     * is first decompressed using {@link GZIPInputStream}.
117 
     *
118 
     * @param inputStream source stream
119 
     * @return deserialized trie
120 
     * @throws NullPointerException if {@code inputStream} is {@code null}
121 
     * @throws IOException          if reading or decompression fails
122 
     */
123 
    public static FrequencyTrie<String> read(final InputStream inputStream) throws IOException {
124 
        Objects.requireNonNull(inputStream, "inputStream");
125
126 
        try (GZIPInputStream gzipInputStream = new GZIPInputStream(new BufferedInputStream(inputStream));
127 
                DataInputStream dataInputStream = new DataInputStream(gzipInputStream)) {
128 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);
129
130 
            LOGGER.log(Level.FINE, "Read compressed binary stemmer trie.");
131 1 1. read : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::read → KILLED
 
            return trie;
132 
        }
133 
    }
134
135 
    /**
136 
     * Reads only metadata from a GZip-compressed binary patch-command trie stored
137 
     * at a filesystem path.
138 
     *
139 
     * @param path source file
140 
     * @return deserialized trie metadata
141 
     * @throws NullPointerException if {@code path} is {@code null}
142 
     * @throws IOException          if reading or decompression fails
143 
     */
144 
    public static TrieMetadata readMetadata(final Path path) throws IOException {
145 
        Objects.requireNonNull(path, "path");
146 1 1. readMetadata : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → NO_COVERAGE
 
        return read(path).metadata();
147 
    }
148
149 
    /**
150 
     * Reads only metadata from a GZip-compressed binary patch-command trie stored
151 
     * at a filesystem path string.
152 
     *
153 
     * @param fileName source file name or path string
154 
     * @return deserialized trie metadata
155 
     * @throws NullPointerException if {@code fileName} is {@code null}
156 
     * @throws IOException          if reading or decompression fails
157 
     */
158 
    public static TrieMetadata readMetadata(final String fileName) throws IOException {
159 
        Objects.requireNonNull(fileName, "fileName");
160 1 1. readMetadata : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → NO_COVERAGE
 
        return readMetadata(Path.of(fileName));
161 
    }
162
163 
    /**
164 
     * Reads only metadata from a GZip-compressed binary patch-command trie from an
165 
     * input stream.
166 
     *
167 
     * @param inputStream source stream
168 
     * @return deserialized trie metadata
169 
     * @throws NullPointerException if {@code inputStream} is {@code null}
170 
     * @throws IOException          if reading or decompression fails
171 
     */
172 
    public static TrieMetadata readMetadata(final InputStream inputStream) throws IOException {
173 
        Objects.requireNonNull(inputStream, "inputStream");
174 1 1. readMetadata : replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → NO_COVERAGE
 
        return read(inputStream).metadata();
175 
    }
176
177 
    /**
178 
     * Writes a GZip-compressed binary patch-command trie to a filesystem path.
179 
     *
180 
     * @param trie trie to persist
181 
     * @param path target file
182 
     * @throws NullPointerException if any argument is {@code null}
183 
     * @throws IOException          if writing fails
184 
     */
185 
    public static void write(final FrequencyTrie<String> trie, final Path path) throws IOException {
186 
        Objects.requireNonNull(trie, "trie");
187 
        Objects.requireNonNull(path, "path");
188
189 
        final Path parent = path.toAbsolutePath().getParent();
190 1 1. write : negated conditional → KILLED
 
        if (parent != null) {
191 
            Files.createDirectories(parent);
192 
        }
193
194 
        try (OutputStream fileOutputStream = Files.newOutputStream(path)) {
195 1 1. write : removed call to org/egothor/stemmer/StemmerPatchTrieBinaryIO::write → KILLED
 
            write(trie, fileOutputStream);
196 
        }
197 
    }
198
199 
    /**
200 
     * Writes a GZip-compressed binary patch-command trie to a filesystem path
201 
     * string.
202 
     *
203 
     * @param trie     trie to persist
204 
     * @param fileName target file name or path string
205 
     * @throws NullPointerException if any argument is {@code null}
206 
     * @throws IOException          if writing fails
207 
     */
208 
    public static void write(final FrequencyTrie<String> trie, final String fileName) throws IOException {
209 
        Objects.requireNonNull(fileName, "fileName");
210 1 1. write : removed call to org/egothor/stemmer/StemmerPatchTrieBinaryIO::write → KILLED
 
        write(trie, Path.of(fileName));
211 
    }
212
213 
    /**
214 
     * Writes a GZip-compressed binary patch-command trie to an output stream.
215 
     *
216 
     * @param trie         trie to persist
217 
     * @param outputStream target stream
218 
     * @throws NullPointerException if any argument is {@code null}
219 
     * @throws IOException          if writing fails
220 
     */
221 
    public static void write(final FrequencyTrie<String> trie, final OutputStream outputStream) throws IOException {
222 
        Objects.requireNonNull(trie, "trie");
223 
        Objects.requireNonNull(outputStream, "outputStream");
224
225 
        try (GZIPOutputStream gzipOutputStream = new GZIPOutputStream(new BufferedOutputStream(outputStream));
226 
                DataOutputStream dataOutputStream = new DataOutputStream(gzipOutputStream)) {
227 1 1. write : removed call to org/egothor/stemmer/FrequencyTrie::writeTo → KILLED
 
            trie.writeTo(dataOutputStream, STRING_CODEC);
228 
        }
229
230 
        LOGGER.log(Level.FINE, "Wrote compressed binary stemmer trie.");
231 
    }
232
233 
    /**
234 
     * Binary stream codec for persisted patch-command strings.
235 
     */
236 
    private static final class StringValueStreamCodec implements FrequencyTrie.ValueStreamCodec<String> {
237
238 
        /**
239 
         * Creates a codec instance.
240 
         */
241 
        private StringValueStreamCodec() {
242 
        }
243
244 
        @Override
245 
        public void write(final DataOutputStream dataOutput, final String value) throws IOException {
246 1 1. write : removed call to java/io/DataOutputStream::writeUTF → KILLED
 
            dataOutput.writeUTF(value);
247 
        }
248
249 
        @Override
250 
        public String read(final DataInputStream dataInput) throws IOException {
251 1 1. read : replaced return value with "" for org/egothor/stemmer/StemmerPatchTrieBinaryIO$StringValueStreamCodec::read → KILLED
 
            return dataInput.readUTF();
252 
        }
253 
    }
254 
}

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

108

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

128

1.1
Location : lambda$read$0
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 null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::lambda$read$0 → 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

146

1.1
Location : readMetadata
Killed by : none replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → NO_COVERAGE

160

1.1
Location : readMetadata
Killed by : none replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → NO_COVERAGE

174

1.1
Location : readMetadata
Killed by : none replaced return value with null for org/egothor/stemmer/StemmerPatchTrieBinaryIO::readMetadata → NO_COVERAGE

190

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

195

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

210

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

227

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

246

1.1
Location : write
Killed by : org.egothor.stemmer.CompiledTrieArtifactRegressionTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.CompiledTrieArtifactRegressionTest]/[test-template:shouldPreserveRepresentativeSemanticProbes(org.egothor.stemmer.CompiledTrieArtifactRegressionTest$ArtifactCase)]/[test-template-invocation:#1] removed call to java/io/DataOutputStream::writeUTF → KILLED

251

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