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 * Compressor that takes care of compress some input.
23 */
24 public interface Compressor extends AutoCloseable {
25 /**
26 * This method will read from the input {@link Buffer} and compress into a new {@link Buffer} that will be
27 * allocated (if needed) from the {@link BufferAllocator}. This method is expected to consume all data from the
28 * input but <strong>not</strong> take ownership. The caller is responsible to release the input buffer after
29 * this method returns.
30 *
31 * @param input the {@link Buffer} that contains the data to be compressed.
32 * @param allocator the {@link BufferAllocator} that is used to allocate a new buffer (if needed) to write the
33 * compressed bytes too.
34 * @return the {@link Buffer} that contains the compressed data. The caller of this method takes
35 * ownership of the buffer. The return value will <strong>never</strong> be {@code null}.
36 * @throws CompressionException thrown if an compression error was encountered or the compressor was closed
37 * already.
38 */
39 Buffer compress(Buffer input, BufferAllocator allocator) throws CompressionException;
40
41 /**
42 * By calling this method we signal that the compression stream is marked as finish. The returned {@link Buffer}
43 * might contain a "trailer" which marks the end of the stream.
44 *
45 * @return the {@link Buffer} which represent the end of the compression stream, which might be empty if the
46 * compressor don't need a trailer to signal the end. The caller of this method takes
47 * ownership of the buffer. The return value will <strong>never</strong> be {@code null}.
48 * @throws CompressionException thrown if a compression error was encountered or the compressor was closed
49 * already.
50 */
51 Buffer finish(BufferAllocator allocator) throws CompressionException;
52
53 /**
54 * Returns {@code} true if the compressor was finished or closed. This might happen because someone explicit called
55 * {@link #finish(BufferAllocator)} / {@link #close()} or the compressor implementation did decide to close itself
56 * due a compression error which can't be recovered. After {@link #isFinished()} returns {@code true} the
57 * {@link #compress(Buffer, BufferAllocator)} method will just return an empty buffer without consuming anything
58 * from its input buffer.
59 *
60 * @return {@code true }if the compressor was marked as finished, {@code false} otherwise.
61 */
62 boolean isFinished();
63
64 /**
65 * Return {@code true} if the decompressor was closed, {@code false} otherwise.
66 *
67 * @return {@code true} if the decompressor was closed, {@code false} otherwise.
68 */
69 boolean isClosed();
70
71 /**#
72 * Close the compressor. After this method was called {@link #isFinished()}
73 * will return {@code true} as well and it is not allowed to call {@link #compress(Buffer, BufferAllocator)} or
74 * {@link #finish(BufferAllocator)} anymore
75 - */
76 @Override
77 void close();
78 }