1 /*
2 * Copyright 2025 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.handler.codec.compression;
17
18 import io.netty.buffer.ByteBuf;
19 import io.netty.buffer.ByteBufAllocator;
20 import io.netty.util.internal.UnstableApi;
21
22 /**
23 * Shared API for various decompression algorithms. A decompressor reports its current status using {@link #status()}.
24 * Status documentation lists which operations are permitted for which status. Callers must observe the current
25 * status before invoking an operation that is only valid for that status.
26 * <p>
27 * All methods may throw exceptions. If an exception is thrown, no further operations are permitted, except for
28 * {@link #close()}.
29 * <p>
30 * This API is still in progress as part of the decompression migration tracked by
31 * <a href="https://github.com/netty/netty/issues/16743">#16743</a>.
32 */
33 @UnstableApi
34 public interface Decompressor extends AutoCloseable {
35 /**
36 * Get the current status. Like the other operations on this class, calling this method is not permitted if the
37 * decompressor has failed or was closed.
38 *
39 * @return The current status
40 */
41 Status status() throws DecompressionException;
42
43 /**
44 * Add a new input buffer. Only permitted for {@link Status#NEED_INPUT}.
45 *
46 * @param buf The input buffer. Buffer ownership transfers to the decompressor (also on exception).
47 */
48 void addInput(ByteBuf buf) throws DecompressionException;
49
50 /**
51 * Notify the decompressor that the end of input has been reached. Some implementations may flush remaining data or
52 * throw an exception if the input is truncated, but most implementations do nothing. Only permitted for
53 * {@link Status#NEED_INPUT}.
54 */
55 void endOfInput() throws DecompressionException;
56
57 /**
58 * Take a decompressed buffer from this decompressor. Only permitted for {@link Status#NEED_OUTPUT}. Buffer
59 * ownership transfers to the caller.
60 *
61 * @return The decompressed buffer. May be empty.
62 */
63 ByteBuf takeOutput() throws DecompressionException;
64
65 /**
66 * Close this decompressor, cleaning up any associated resources. <b>This method is idempotent.</b>
67 */
68 @Override
69 void close() throws DecompressionException;
70
71 /**
72 * Current status of the decompressor. The status indicates which method may be called to make progress on
73 * decompression.
74 */
75 @UnstableApi
76 enum Status {
77 /**
78 * More input is required before decompression can proceed. Only calls to {@link #addInput} and
79 * {@link #endOfInput()} are permitted.
80 */
81 NEED_INPUT,
82 /**
83 * Output must be consumed before more input can be received. Only calls to {@link #takeOutput()} are
84 * permitted.
85 */
86 NEED_OUTPUT,
87 /**
88 * All data has been processed, and the format indicates that no more input may arrive. No further
89 * decompression operations are permitted, except {@link Decompressor#close()} to release resources.
90 */
91 COMPLETE,
92 }
93
94 @UnstableApi
95 abstract class AbstractDecompressorBuilder {
96
97 protected AbstractDecompressorBuilder() {
98 }
99
100 public abstract Decompressor build(ByteBufAllocator allocator) throws DecompressionException;
101 }
102 }