io.grpc.Detachable Maven / Gradle / Ivy
/*
* Copyright 2021 The gRPC Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.grpc;
import java.io.InputStream;
/**
* An extension of {@link InputStream} that allows the underlying data source to be detached and
* transferred to a new instance of the same kind. The detached InputStream takes over the
* ownership of the underlying data source. That's said, the detached InputStream is responsible
* for releasing its resources after use. The detached InputStream preserves internal states of
* the underlying data source. Data can be consumed through the detached InputStream as if being
* continually consumed through the original instance. The original instance discards internal
* states of detached data source and is no longer consumable as if the data source is exhausted.
*
* A normal usage of this API is to extend the lifetime of the data source owned by the
* original instance for doing extra processing before releasing it. For example, when combined
* with {@link HasByteBuffer}, a custom {@link io.grpc.MethodDescriptor.Marshaller} can take
* over the ownership of buffers containing inbound data and perform delayed deserialization.
*/
public interface Detachable {
/**
* Detaches the underlying data source from this instance and transfers to an {@link
* InputStream}. Detaching data from an already-detached instance gives an InputStream with
* zero bytes of data.
*
*/
InputStream detach();
}