View Javadoc
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  }