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   * 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  }