#19533

Committed 30 Oct 2024 01:19PM CUT coverage: 84.562% (-0.01%) from 84.573%

Build # #19533

Build Type

push

github

Committed by

web-flow

Commit Message

api: Add java.time.Duration overloads to CallOptions, AbstractStub taking TimeUnit and a time value (#11562)

Run Details

33927 of 40121 relevant lines covered (84.56%)

0.85 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

69.57

/../stub/src/main/java/io/grpc/stub/AbstractStub.java

/*
 * 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.stub;

import static com.google.common.base.Preconditions.checkNotNull;
import static io.grpc.InternalTimeUtils.convert;

import io.grpc.CallCredentials;
import io.grpc.CallOptions;
import io.grpc.Channel;
import io.grpc.ClientInterceptor;
import io.grpc.ClientInterceptors;
import io.grpc.Deadline;
import io.grpc.ExperimentalApi;
import io.grpc.ManagedChannelBuilder;
import java.time.Duration;
import java.util.concurrent.Executor;
import java.util.concurrent.TimeUnit;
import javax.annotation.CheckReturnValue;
import javax.annotation.Nullable;
import javax.annotation.concurrent.ThreadSafe;

/**
 * Common base type for stub implementations. Stub configuration is immutable; changing the
 * configuration returns a new stub with updated configuration. Changing the configuration is cheap
 * and may be done before every RPC, such as would be common when using {@link #withDeadlineAfter}.
 *
 * <p>Configuration is stored in {@link CallOptions} and is passed to the {@link Channel} when
 * performing an RPC.
 *
 * <p>DO NOT MOCK: Customizing options doesn't work properly in mocks. Use InProcessChannelBuilder
 * to create a real channel suitable for testing. It is also possible to mock Channel instead.
 *
 * @since 1.0.0
 * @param <S> the concrete type of this stub.
 */
@ThreadSafe
@CheckReturnValue
public abstract class AbstractStub<S extends AbstractStub<S>> {
  private final Channel channel;
  private final CallOptions callOptions;

  /**
   * Constructor for use by subclasses, with the default {@code CallOptions}.
   *
   * @since 1.0.0
   * @param channel the channel that this stub will use to do communications
   */
  protected AbstractStub(Channel channel) {
    this(channel, CallOptions.DEFAULT);
  }

  /**
   * Constructor for use by subclasses.
   *
   * @since 1.0.0
   * @param channel the channel that this stub will use to do communications
   * @param callOptions the runtime call options to be applied to every call on this stub
   */
  protected AbstractStub(Channel channel, CallOptions callOptions) {
    this.channel = checkNotNull(channel, "channel");
    this.callOptions = checkNotNull(callOptions, "callOptions");
  }

  /**
   * The underlying channel of the stub.
   *
   * @since 1.0.0
   */
  public final Channel getChannel() {
    return channel;
  }

  /**
   * The {@code CallOptions} of the stub.
   *
   * @since 1.0.0
   */
  public final CallOptions getCallOptions() {
    return callOptions;
  }

  /**
   * Returns a new stub with the given channel for the provided method configurations.
   *
   * @since 1.0.0
   * @param channel the channel that this stub will use to do communications
   * @param callOptions the runtime call options to be applied to every call on this stub
   */
  protected abstract S build(Channel channel, CallOptions callOptions);

  /**
   * Returns a new stub with the given channel for the provided method configurations.
   *
   * @since 1.26.0
   * @param factory the factory to create a stub
   * @param channel the channel that this stub will use to do communications
   */
  public static <T extends AbstractStub<T>> T newStub(
      StubFactory<T> factory, Channel channel) {
    return newStub(factory, channel, CallOptions.DEFAULT);
  }

  /**
   * Returns a new stub with the given channel for the provided method configurations.
   *
   * @since 1.26.0
   * @param factory the factory to create a stub
   * @param channel the channel that this stub will use to do communications
   * @param callOptions the runtime call options to be applied to every call on this stub
   */
  public static <T extends AbstractStub<T>> T newStub(
      StubFactory<T> factory, Channel channel, CallOptions callOptions) {
    return factory.newStub(channel, callOptions);
  }

  /**
   * Returns a new stub with an absolute deadline.
   *
   * <p>This is mostly used for propagating an existing deadline. {@link #withDeadlineAfter} is the
   * recommended way of setting a new deadline,
   *
   * @since 1.0.0
   * @param deadline the deadline or {@code null} for unsetting the deadline.
   */
  public final S withDeadline(@Nullable Deadline deadline) {
    return build(channel, callOptions.withDeadline(deadline));
  }

  /**
   * Returns a new stub with a deadline that is after the given {@code duration} from now.
   *
   * @since 1.0.0
   * @see CallOptions#withDeadlineAfter
   */
  public final S withDeadlineAfter(long duration, TimeUnit unit) {
    return build(channel, callOptions.withDeadlineAfter(duration, unit));
  }

  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/11657")
  public final S withDeadlineAfter(Duration duration) {
    return withDeadlineAfter(convert(duration), TimeUnit.NANOSECONDS);
  }

  /**
   * Returns a new stub with the given executor that is to be used instead of the default one
   * specified with {@link ManagedChannelBuilder#executor}. Note that setting this option may not
   * take effect for blocking calls.
   *
   * @since 1.8.0
   */
  public final S withExecutor(Executor executor) {
    return build(channel, callOptions.withExecutor(executor));
  }

  /**
   *  Set's the compressor name to use for the call.  It is the responsibility of the application
   *  to make sure the server supports decoding the compressor picked by the client.  To be clear,
   *  this is the compressor used by the stub to compress messages to the server.
   *
   * @since 1.0.0
   * @param compressorName the name (e.g. "gzip") of the compressor to use.
   */
  public final S withCompression(String compressorName) {
    return build(channel, callOptions.withCompression(compressorName));
  }

  /**
   * Returns a new stub that uses the given channel.
   *
   * <p>This method is vestigial and is unlikely to be useful.  Instead, users should prefer to
   * use {@link #withInterceptors}.
   *
   * @since 1.0.0
   */
  @Deprecated // use withInterceptors() instead
  public final S withChannel(Channel newChannel) {
    return build(newChannel, callOptions);
  }

  /**
   * Sets a custom option to be passed to client interceptors on the channel
   * {@link io.grpc.ClientInterceptor} via the CallOptions parameter.
   *
   * @since 1.0.0
   * @param key the option being set
   * @param value the value for the key
   */
  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1869")
  public final <T> S withOption(CallOptions.Key<T> key, T value) {
    return build(channel, callOptions.withOption(key, value));
  }

  /**
   * Returns a new stub that has the given interceptors attached to the underlying channel.
   *
   * @since 1.0.0
   */
  public final S withInterceptors(ClientInterceptor... interceptors) {
    return build(ClientInterceptors.intercept(channel, interceptors), callOptions);
  }

  /**
   * Returns a new stub that uses the given call credentials.
   *
   * @since 1.0.0
   */
  public final S withCallCredentials(CallCredentials credentials) {
    return build(channel, callOptions.withCallCredentials(credentials));
  }

  /**
   * Returns a new stub that uses
   * <a href="https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md">'wait for ready'</a>
   * for the call. Wait-for-ready queues the RPC until a connection is available. This may
   * dramatically increase the latency of the RPC, but avoids failing "unnecessarily." The default
   * queues the RPC until an attempt to connect has completed, but fails RPCs without sending them
   * if unable to connect.
   *
   * @since 1.1.0
   */
  public final S withWaitForReady() {
    return build(channel, callOptions.withWaitForReady());
  }

  /**
   * Returns a new stub that limits the maximum acceptable message size from a remote peer.
   *
   * <p>If unset, the {@link ManagedChannelBuilder#maxInboundMessageSize(int)} limit is used.
   *
   * @since 1.1.0
   */
  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563")
  public final S withMaxInboundMessageSize(int maxSize) {
    return build(channel, callOptions.withMaxInboundMessageSize(maxSize));
  }

  /**
   * Returns a new stub that limits the maximum acceptable message size to send a remote peer.
   *
   * @since 1.1.0
   */
  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563")
  public final S withMaxOutboundMessageSize(int maxSize) {
    return build(channel, callOptions.withMaxOutboundMessageSize(maxSize));
  }

  /**
   * Returns a new stub that limits the maximum number of bytes per stream in the queue.
   *
   * @since 1.1.0
   */
  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/11021")
  public final S withOnReadyThreshold(int numBytes) {
    return build(channel, callOptions.withOnReadyThreshold(numBytes));
  }

  /**
   * A factory class for stub.
   *
   * @since 1.26.0
   */
  public interface StubFactory<T extends AbstractStub<T>> {
    T newStub(Channel channel, CallOptions callOptions);
  }
}

1	/*
2	* Copyright 2014 The gRPC Authors
3	*
4	* Licensed under the Apache License, Version 2.0 (the "License");
5	* you may not use this file except in compliance with the License.
6	* You may obtain a copy of the License at
7	*
8	* http://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,
12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13	* See the License for the specific language governing permissions and
14	* limitations under the License.
15	*/
16
17	package io.grpc.stub;
18
19	import static com.google.common.base.Preconditions.checkNotNull;
20	import static io.grpc.InternalTimeUtils.convert;
21
22	import io.grpc.CallCredentials;
23	import io.grpc.CallOptions;
24	import io.grpc.Channel;
25	import io.grpc.ClientInterceptor;
26	import io.grpc.ClientInterceptors;
27	import io.grpc.Deadline;
28	import io.grpc.ExperimentalApi;
29	import io.grpc.ManagedChannelBuilder;
30	import java.time.Duration;
31	import java.util.concurrent.Executor;
32	import java.util.concurrent.TimeUnit;
33	import javax.annotation.CheckReturnValue;
34	import javax.annotation.Nullable;
35	import javax.annotation.concurrent.ThreadSafe;
36
37	/**
38	* Common base type for stub implementations. Stub configuration is immutable; changing the
39	* configuration returns a new stub with updated configuration. Changing the configuration is cheap
40	* and may be done before every RPC, such as would be common when using {@link #withDeadlineAfter}.
41	*
42	* <p>Configuration is stored in {@link CallOptions} and is passed to the {@link Channel} when
43	* performing an RPC.
44	*
45	* <p>DO NOT MOCK: Customizing options doesn't work properly in mocks. Use InProcessChannelBuilder
46	* to create a real channel suitable for testing. It is also possible to mock Channel instead.
47	*
48	* @since 1.0.0
49	* @param <S> the concrete type of this stub.
50	*/
51	@ThreadSafe
52	@CheckReturnValue
53	public abstract class AbstractStub<S extends AbstractStub<S>> {
54	private final Channel channel;
55	private final CallOptions callOptions;
56
57	/**
58	* Constructor for use by subclasses, with the default {@code CallOptions}.
59	*
60	* @since 1.0.0
61	* @param channel the channel that this stub will use to do communications
62	*/
63	protected AbstractStub(Channel channel) {
64	this(channel, CallOptions.DEFAULT);	×
65	}	×
66
67	/**
68	* Constructor for use by subclasses.
69	*
70	* @since 1.0.0
71	* @param channel the channel that this stub will use to do communications
72	* @param callOptions the runtime call options to be applied to every call on this stub
73	*/
74	protected AbstractStub(Channel channel, CallOptions callOptions) {	1✔
75	this.channel = checkNotNull(channel, "channel");	1✔
76	this.callOptions = checkNotNull(callOptions, "callOptions");	1✔
77	}	1✔
78
79	/**
80	* The underlying channel of the stub.
81	*
82	* @since 1.0.0
83	*/
84	public final Channel getChannel() {
85	return channel;	1✔
86	}
87
88	/**
89	* The {@code CallOptions} of the stub.
90	*
91	* @since 1.0.0
92	*/
93	public final CallOptions getCallOptions() {
94	return callOptions;	1✔
95	}
96
97	/**
98	* Returns a new stub with the given channel for the provided method configurations.
99	*
100	* @since 1.0.0
101	* @param channel the channel that this stub will use to do communications
102	* @param callOptions the runtime call options to be applied to every call on this stub
103	*/
104	protected abstract S build(Channel channel, CallOptions callOptions);
105
106	/**
107	* Returns a new stub with the given channel for the provided method configurations.
108	*
109	* @since 1.26.0
110	* @param factory the factory to create a stub
111	* @param channel the channel that this stub will use to do communications
112	*/
113	public static <T extends AbstractStub<T>> T newStub(
114	StubFactory<T> factory, Channel channel) {
115	return newStub(factory, channel, CallOptions.DEFAULT);	×
116	}
117
118	/**
119	* Returns a new stub with the given channel for the provided method configurations.
120	*
121	* @since 1.26.0
122	* @param factory the factory to create a stub
123	* @param channel the channel that this stub will use to do communications
124	* @param callOptions the runtime call options to be applied to every call on this stub
125	*/
126	public static <T extends AbstractStub<T>> T newStub(
127	StubFactory<T> factory, Channel channel, CallOptions callOptions) {
128	return factory.newStub(channel, callOptions);	1✔
129	}
130
131	/**
132	* Returns a new stub with an absolute deadline.
133	*
134	* <p>This is mostly used for propagating an existing deadline. {@link #withDeadlineAfter} is the
135	* recommended way of setting a new deadline,
136	*
137	* @since 1.0.0
138	* @param deadline the deadline or {@code null} for unsetting the deadline.
139	*/
140	public final S withDeadline(@Nullable Deadline deadline) {
141	return build(channel, callOptions.withDeadline(deadline));	1✔
142	}
143
144	/**
145	* Returns a new stub with a deadline that is after the given {@code duration} from now.
146	*
147	* @since 1.0.0
148	* @see CallOptions#withDeadlineAfter
149	*/
150	public final S withDeadlineAfter(long duration, TimeUnit unit) {
151	return build(channel, callOptions.withDeadlineAfter(duration, unit));	1✔
152	}
153
154	@ExperimentalApi("https://github.com/grpc/grpc-java/issues/11657")
155	public final S withDeadlineAfter(Duration duration) {
156	return withDeadlineAfter(convert(duration), TimeUnit.NANOSECONDS);	1✔
157	}
158
159	/**
160	* Returns a new stub with the given executor that is to be used instead of the default one
161	* specified with {@link ManagedChannelBuilder#executor}. Note that setting this option may not
162	* take effect for blocking calls.
163	*
164	* @since 1.8.0
165	*/
166	public final S withExecutor(Executor executor) {
167	return build(channel, callOptions.withExecutor(executor));	1✔
168	}
169
170	/**
171	* Set's the compressor name to use for the call. It is the responsibility of the application
172	* to make sure the server supports decoding the compressor picked by the client. To be clear,
173	* this is the compressor used by the stub to compress messages to the server.
174	*
175	* @since 1.0.0
176	* @param compressorName the name (e.g. "gzip") of the compressor to use.
177	*/
178	public final S withCompression(String compressorName) {
179	return build(channel, callOptions.withCompression(compressorName));	×
180	}
181
182	/**
183	* Returns a new stub that uses the given channel.
184	*
185	* <p>This method is vestigial and is unlikely to be useful. Instead, users should prefer to
186	* use {@link #withInterceptors}.
187	*
188	* @since 1.0.0
189	*/
190	@Deprecated // use withInterceptors() instead
191	public final S withChannel(Channel newChannel) {
192	return build(newChannel, callOptions);	×
193	}
194
195	/**
196	* Sets a custom option to be passed to client interceptors on the channel
197	* {@link io.grpc.ClientInterceptor} via the CallOptions parameter.
198	*
199	* @since 1.0.0
200	* @param key the option being set
201	* @param value the value for the key
202	*/
203	@ExperimentalApi("https://github.com/grpc/grpc-java/issues/1869")
204	public final <T> S withOption(CallOptions.Key<T> key, T value) {
205	return build(channel, callOptions.withOption(key, value));	×
206	}
207
208	/**
209	* Returns a new stub that has the given interceptors attached to the underlying channel.
210	*
211	* @since 1.0.0
212	*/
213	public final S withInterceptors(ClientInterceptor... interceptors) {
214	return build(ClientInterceptors.intercept(channel, interceptors), callOptions);	1✔
215	}
216
217	/**
218	* Returns a new stub that uses the given call credentials.
219	*
220	* @since 1.0.0
221	*/
222	public final S withCallCredentials(CallCredentials credentials) {
223	return build(channel, callOptions.withCallCredentials(credentials));	×
224	}
225
226	/**
227	* Returns a new stub that uses
228	* <a href="https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md">'wait for ready'</a>
229	* for the call. Wait-for-ready queues the RPC until a connection is available. This may
230	* dramatically increase the latency of the RPC, but avoids failing "unnecessarily." The default
231	* queues the RPC until an attempt to connect has completed, but fails RPCs without sending them
232	* if unable to connect.
233	*
234	* @since 1.1.0
235	*/
236	public final S withWaitForReady() {
237	return build(channel, callOptions.withWaitForReady());	1✔
238	}
239
240	/**
241	* Returns a new stub that limits the maximum acceptable message size from a remote peer.
242	*
243	* <p>If unset, the {@link ManagedChannelBuilder#maxInboundMessageSize(int)} limit is used.
244	*
245	* @since 1.1.0
246	*/
247	@ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563")
248	public final S withMaxInboundMessageSize(int maxSize) {
249	return build(channel, callOptions.withMaxInboundMessageSize(maxSize));	1✔
250	}
251
252	/**
253	* Returns a new stub that limits the maximum acceptable message size to send a remote peer.
254	*
255	* @since 1.1.0
256	*/
257	@ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563")
258	public final S withMaxOutboundMessageSize(int maxSize) {
259	return build(channel, callOptions.withMaxOutboundMessageSize(maxSize));	1✔
260	}
261
262	/**
263	* Returns a new stub that limits the maximum number of bytes per stream in the queue.
264	*
265	* @since 1.1.0
266	*/
267	@ExperimentalApi("https://github.com/grpc/grpc-java/issues/11021")
268	public final S withOnReadyThreshold(int numBytes) {
269	return build(channel, callOptions.withOnReadyThreshold(numBytes));	1✔
270	}
271
272	/**
273	* A factory class for stub.
274	*
275	* @since 1.26.0
276	*/
277	public interface StubFactory<T extends AbstractStub<T>> {
278	T newStub(Channel channel, CallOptions callOptions);
279	}
280	}

grpc / grpc-java / #19533

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous