io.grpc.internal.ClientStream Maven / Gradle / Ivy
/*
* Copyright 2014 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.internal;
import io.grpc.Attributes;
import io.grpc.Deadline;
import io.grpc.DecompressorRegistry;
import io.grpc.Status;
import javax.annotation.Nonnull;
/**
* Extension of {@link Stream} to support client-side termination semantics.
*
* An implementation doesn't need to be thread-safe. All methods are expected to execute quickly.
*/
public interface ClientStream extends Stream {
/**
* Abnormally terminates the stream. After calling this method, no further messages will be
* sent or received, however it may still be possible to receive buffered messages for a brief
* period until {@link ClientStreamListener#closed} is called. This method may only be called
* after {@link #start}, but else is safe to be called at any time and multiple times and
* from any thread.
*
* @param reason must be non-OK
*/
void cancel(Status reason);
/**
* Closes the local side of this stream and flushes any remaining messages. After this is called,
* no further messages may be sent on this stream, but additional messages may be received until
* the remote end-point is closed. This method may only be called once, and only after
* {@link #start}.
*/
void halfClose();
/**
* Override the default authority with {@code authority}. May only be called before {@link
* #start}.
*/
void setAuthority(String authority);
/**
* Enables full-stream decompression, allowing the client stream to use {@link
* GzipInflatingBuffer} to decode inbound GZIP compressed streams.
*/
void setFullStreamDecompression(boolean fullStreamDecompression);
/**
* Sets the registry to find a decompressor for the framer. May only be called before {@link
* #start}. If the transport does not support compression, this may do nothing.
*
* @param decompressorRegistry the registry of decompressors for decoding responses
*/
void setDecompressorRegistry(DecompressorRegistry decompressorRegistry);
/**
* Starts stream. This method may only be called once. It is safe to do latent initialization of
* the stream up until {@link #start} is called.
*
*
This method should not throw any exceptions.
*
* @param listener non-{@code null} listener of stream events
*/
void start(ClientStreamListener listener);
/**
* Sets the max size accepted from the remote endpoint.
*/
void setMaxInboundMessageSize(int maxSize);
/**
* Sets the max size sent to the remote endpoint.
*/
void setMaxOutboundMessageSize(int maxSize);
/**
* Sets the effective deadline of the RPC.
*/
void setDeadline(@Nonnull Deadline deadline);
/**
* Attributes that the stream holds at the current moment. Thread-safe and can be called at any
* time, although some attributes are there only after a certain point.
*/
Attributes getAttributes();
/**
* Append information that will be included in the locally generated DEADLINE_EXCEEDED errors to
* the given {@link InsightBuilder}, in order to tell the user about the state of the stream so
* that they can better diagnose the cause of the error.
*/
void appendTimeoutInsight(InsightBuilder insight);
}