All Downloads are FREE. Search and download functionalities are using the official Maven repository.

io.grpc.ServerCall Maven / Gradle / Ivy

There is a newer version: 1.66.0
Show newest version
/*
 * 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;

import javax.annotation.Nullable;

/**
 * Encapsulates a single call received from a remote client. Calls may not simply be unary
 * request-response even though this is the most common pattern. Calls may stream any number of
 * requests and responses. This API is generally intended for use by generated handlers,
 * but applications may use it directly if they need to.
 *
 * 

Headers must be sent before any messages, which must be sent before closing. * *

No generic method for determining message receipt or providing acknowledgement is provided. * Applications are expected to utilize normal messages for such signals, as a response * naturally acknowledges its request. * *

Methods are guaranteed to be non-blocking. Implementations are not required to be thread-safe. * *

DO NOT MOCK: Use InProcessTransport and make a fake server instead. * * @param parsed type of request message. * @param parsed type of response message. */ public abstract class ServerCall { /** * Callbacks for consuming incoming RPC messages. * *

Any contexts are guaranteed to arrive before any messages, which are guaranteed before half * close, which is guaranteed before completion. * *

Implementations are free to block for extended periods of time. Implementations are not * required to be thread-safe, but they must not be thread-hostile. The caller is free to call * an instance from multiple threads, but only one call simultaneously. A single thread may * interleave calls to multiple instances, so implementations using ThreadLocals must be careful * to avoid leaking inappropriate state (e.g., clearing the ThreadLocal before returning). */ // TODO(ejona86): We need to decide what to do in the case of server closing with non-cancellation // before client half closes. It may be that we treat such a case as an error. If we permit such // a case then we either get to generate a half close or purposefully omit it. public abstract static class Listener { /** * A request message has been received. For streaming calls, there may be zero or more request * messages. * * @param message a received request message. */ public void onMessage(ReqT message) {} /** * The client completed all message sending. However, the call may still be cancelled. */ public void onHalfClose() {} /** * The call was cancelled and the server is encouraged to abort processing to save resources, * since the client will not process any further messages. Cancellations can be caused by * timeouts, explicit cancellation by the client, network errors, etc. * *

There will be no further callbacks for the call. */ public void onCancel() {} /** * The call is considered complete and {@link #onCancel} is guaranteed not to be called. * However, the client is not guaranteed to have received all messages. * *

There will be no further callbacks for the call. */ public void onComplete() {} /** * This indicates that the call may now be capable of sending additional messages (via * {@link #sendMessage}) without requiring excessive buffering internally. This event is * just a suggestion and the application is free to ignore it, however doing so may * result in excessive buffering within the call. * *

Because there is a processing delay to deliver this notification, it is possible for * concurrent writes to cause {@code isReady() == false} within this callback. Handle "spurious" * notifications by checking {@code isReady()}'s current value instead of assuming it is now * {@code true}. If {@code isReady() == false} the normal expectations apply, so there would be * another {@code onReady()} callback. */ public void onReady() {} } /** * Requests up to the given number of messages from the call to be delivered to * {@link Listener#onMessage(Object)}. Once {@code numMessages} have been delivered * no further request messages will be delivered until more messages are requested by * calling this method again. * *

Servers use this mechanism to provide back-pressure to the client for flow-control. * *

This method is safe to call from multiple threads without external synchronization. * * @param numMessages the requested number of messages to be delivered to the listener. */ public abstract void request(int numMessages); /** * Send response header metadata prior to sending a response message. This method may * only be called once and cannot be called after calls to {@link #sendMessage} or {@link #close}. * *

Since {@link Metadata} is not thread-safe, the caller must not access (read or write) {@code * headers} after this point. * * @param headers metadata to send prior to any response body. * @throws IllegalStateException if {@code close} has been called, a message has been sent, or * headers have already been sent */ public abstract void sendHeaders(Metadata headers); /** * Send a response message. Messages are the primary form of communication associated with * RPCs. Multiple response messages may exist for streaming calls. * * @param message response message. * @throws IllegalStateException if headers not sent or call is {@link #close}d */ public abstract void sendMessage(RespT message); /** * If {@code true}, indicates that the call is capable of sending additional messages * without requiring excessive buffering internally. This event is * just a suggestion and the application is free to ignore it, however doing so may * result in excessive buffering within the call. * *

If {@code false}, {@link Listener#onReady()} will be called after {@code isReady()} * transitions to {@code true}. * *

This abstract class's implementation always returns {@code true}. Implementations generally * override the method. */ public boolean isReady() { return true; } /** * Close the call with the provided status. No further sending or receiving will occur. If {@link * Status#isOk} is {@code false}, then the call is said to have failed. * *

If no errors or cancellations are known to have occurred, then a {@link Listener#onComplete} * notification should be expected, independent of {@code status}. Otherwise {@link * Listener#onCancel} has been or will be called. * *

Since {@link Metadata} is not thread-safe, the caller must not access (read or write) {@code * trailers} after this point. * *

This method implies the caller completed processing the RPC, but it does not imply the RPC * is complete. The call implementation will need additional time to complete the RPC and during * this time the client is still able to cancel the request or a network error might cause the * RPC to fail. If you wish to know when the call is actually completed/closed, you have to use * {@link Listener#onComplete} or {@link Listener#onCancel} instead. This method is not * necessarily invoked when Listener.onCancel() is called. * * @throws IllegalStateException if call is already {@code close}d */ public abstract void close(Status status, Metadata trailers); /** * Returns {@code true} when the call is cancelled and the server is encouraged to abort * processing to save resources, since the client will not be processing any further methods. * Cancellations can be caused by timeouts, explicit cancel by client, network errors, and * similar. * *

This method may safely be called concurrently from multiple threads. */ public abstract boolean isCancelled(); /** * Enables per-message compression, if an encoding type has been negotiated. If no message * encoding has been negotiated, this is a no-op. By default per-message compression is enabled, * but may not have any effect if compression is not enabled on the call. */ public void setMessageCompression(boolean enabled) { // noop } /** * Sets the compression algorithm for this call. This compression is utilized for sending. If * the server does not support the compression algorithm, the call will fail. This method may * only be called before {@link #sendHeaders}. The compressor to use will be looked up in the * {@link CompressorRegistry}. Default gRPC servers support the "gzip" compressor. * *

It is safe to call this even if the client does not support the compression format chosen. * The implementation will handle negotiation with the client and may fall back to no compression. * * @param compressor the name of the compressor to use. * @throws IllegalArgumentException if the compressor name can not be found. */ public void setCompression(String compressor) { // noop } /** * Returns the level of security guarantee in communications * *

Determining the level of security offered by the transport for RPCs on server-side. * This can be approximated by looking for the SSLSession, but that doesn't work for ALTS and * maybe some future TLS approaches. May return a lower security level when it cannot be * determined precisely. * * @return non-{@code null} SecurityLevel enum */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4692") public SecurityLevel getSecurityLevel() { return SecurityLevel.NONE; } /** * Returns properties of a single call. * *

Attributes originate from the transport and can be altered by {@link ServerTransportFilter}. * * @return non-{@code null} Attributes container */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1779") @Grpc.TransportAttr public Attributes getAttributes() { return Attributes.EMPTY; } /** * Gets the authority this call is addressed to. * * @return the authority string. {@code null} if not available. */ @Nullable public String getAuthority() { return null; } /** * The {@link MethodDescriptor} for the call. */ public abstract MethodDescriptor getMethodDescriptor(); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy