1 /*
2 * Copyright 2021 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.netty5.handler.codec.compression;
17
18 import io.netty5.buffer.api.Buffer;
19 import io.netty5.buffer.api.BufferAllocator;
20
21 /**
22 * Decompressor that takes care of decompress some input.
23 */
24 public interface Decompressor extends AutoCloseable {
25 /**
26 * This method will read from the input {@link Buffer} and decompress into a new {@link Buffer} that will be
27 * allocated (if needed) from the {@link BufferAllocator}. If there is not enough readable data in the
28 * {@link Buffer} to process it will return {@code null}.
29 *
30 * This method should be called in a loop as long:
31 *
32 * <li>
33 * <ul>{@link #isFinished()} is {@code false}</ul>
34 * <ul>something was read from the {@code input}</ul>
35 * <ul>something was returned</ul>
36 * </li>
37 * Otherwise this method should be called again once there is more data in the input buffer.
38 *
39 * @param input the {@link Buffer} that contains the data to be decompressed.
40 * @param allocator the {@link BufferAllocator} that is used to allocate a new buffer (if needed) to write the
41 * decompressed bytes too.
42 * @return the {@link Buffer} that contains the decompressed data. The caller of this method takes
43 * ownership of the buffer. The return value will be {@code null} if there is not enough data
44 * readable in the input to make any progress. In this case the user should call it again once
45 * there is more data ready to be consumed.
46 * @throws DecompressionException thrown if an decompression error was encountered or the decompressor was closed
47 * before.
48 */
49 Buffer decompress(Buffer input, BufferAllocator allocator) throws DecompressionException;
50
51 /**
52 * Returns {@code} true if the decompressor was finish. This might be because the decompressor was explicitly closed
53 * or the end of the compressed stream was detected.
54 *
55 * @return {@code true} if the decompressor is done with decompressing the stream.
56 */
57 boolean isFinished();
58
59 /**
60 * Return {@code true} if the decompressor was closed, {@code false} otherwise.
61 *
62 * @return if {@link #close()} was called.
63 */
64 boolean isClosed();
65
66 /**
67 * Close the decompressor. After this method was called {@link #isFinished()}
68 * will return {@code true} as well and it is not allowed to call {@link #decompress(Buffer, BufferAllocator)}
69 * anymore.
70 */
71 @Override
72 void close();
73 }