nats-io/nats.java | Build 2213 | src/main/java/io/nats/client/JetStreamSubscription.java | Coveralls

1

// Copyright 2020 The NATS Authors

2

// Licensed under the Apache License, Version 2.0 (the "License");

3

// you may not use this file except in compliance with the License.

4

// You may obtain a copy of the License at:

5

//

6

// http://www.apache.org/licenses/LICENSE-2.0

7

//

8

// Unless required by applicable law or agreed to in writing, software

9

// distributed under the License is distributed on an "AS IS" BASIS,

10

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

11

// See the License for the specific language governing permissions and

12

// limitations under the License.

13

14

package io.nats.client;

15

16

import io.nats.client.api.ConsumerInfo;

17

18

import java.io.IOException;

19

import java.time.Duration;

20

import java.util.Iterator;

21

import java.util.List;

22

23

/**

24

 * Subscription on a JetStream context.

25

*/

26

public interface JetStreamSubscription extends Subscription {

27

28

/**

29

     * Gets the consumer name associated with the subscription.

30

     * @return the consumer name

31

*/

32

    String getConsumerName();

33

34

/**

35

     * Gets the stream name associated with the subscription.

36

     * @return the stream name

37

*/

39

40

/**

41

     * Initiate pull with the specified batch size.

42

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

43

     * ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.

44

45

     * @param batchSize the size of the batch

46

     * @throws IllegalStateException if not a pull subscription.

47

*/

48

    void pull(int batchSize);

49

50

/**

51

     * Initiate pull with the specified request options

52

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

53

     * ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.

54

55

     * @param pullRequestOptions the options object

56

     * @throws IllegalStateException if not a pull subscription.

57

*/

58

    void pull(PullRequestOptions pullRequestOptions);

59

60

/**

61

     * Initiate pull in noWait mode with the specified batch size.

62

     * The fetch will return immediately with as many messages as are available. Between zero and the maximum configured.

63

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

64

     * ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.

65

66

     * @param batchSize the size of the batch

67

     * @throws IllegalStateException if not a pull subscription.

68

*/

69

    void pullNoWait(int batchSize);

70

71

/**

72

     * Initiate pull in noWait mode with the specified batch size.

73

     * The fetch will return immediately with as many messages as are available, but at least one message. Between one and the maximum configured.

74

     * When no message is available it will wait for new messages to arrive till it expires.

75

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

76

     * ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.

77

78

     * @param batchSize the size of the batch

79

     * @param expiresIn how long from now this request should be expired from the server wait list

80

     * @throws IllegalStateException if not a pull subscription.

81

*/

82

    void pullNoWait(int batchSize, Duration expiresIn);

83

84

/**

85

     * Initiate pull in noWait mode with the specified batch size.

86

     * The fetch will return immediately with as many messages as are available, but at least one message. Between one and the maximum configured.

87

     * When no message is available it will wait for new messages to arrive till it expires.

88

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

89

     * ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.

90

91

     * @param batchSize the size of the batch

92

     * @param expiresInMillis how long from now this request should be expired from the server wait list, in milliseconds

93

     * @throws IllegalStateException if not a pull subscription.

94

*/

95

    void pullNoWait(int batchSize, long expiresInMillis);

96

97

/**

98

     * Initiate pull for all messages available before expiration.

99

     * <p>

100

     * <code>sub.nextMessage(timeout)</code> can return a:

101

     * <ul>

102

     * <li>regular JetStream message

103

     * <li>null

104

     * </ul>

105

     * <p>

106

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

107

     * ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.

108

109

     * @param batchSize the size of the batch

110

     * @param expiresIn how long from now this request should be expired from the server wait list

111

     * @throws IllegalStateException if not a pull subscription.

112

*/

113

    void pullExpiresIn(int batchSize, Duration expiresIn);

114

115

/**

116

     * Initiate pull for all messages available before expiration.

117

     * This can only be used when the subscription is pull based.

118

     * <p>

119

     * <code>sub.nextMessage(timeout)</code> can return a:

120

     * <ul>

121

     * <li>regular JetStream message

122

     * <li>null

123

     * </ul>

124

     * <p>

125

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

126

     * ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.

127

128

     * @param batchSize the size of the batch

129

     * @param expiresInMillis how long from now this request should be expired from the server wait list, in milliseconds

130

     * @throws IllegalStateException if not a pull subscription.

131

*/

132

    void pullExpiresIn(int batchSize, long expiresInMillis);

133

134

/**

135

     * Fetch a list of messages up to the batch size, waiting no longer than maxWait.

136

     * This uses <code>pullExpiresIn</code> under the covers, and manages all responses

137

     * from <code>sub.nextMessage(...)</code> to only return regular JetStream messages.

138

     * This can only be used when the subscription is pull based.

139

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

140

141

     * @param batchSize the size of the batch

142

     * @param maxWait the maximum time to wait to collect messages for the batch.

143

144

     * @return the list of messages

145

     * @throws IllegalStateException if not a pull subscription.

146

*/

147

    List<Message> fetch(int batchSize, Duration maxWait);

148

149

/**

150

     * Fetch a list of messages up to the batch size, waiting no longer than maxWait.

151

     * This uses <code>pullExpiresIn</code> under the covers, and manages all responses

152

     * from <code>sub.nextMessage(...)</code> to only return regular JetStream messages.

153

     * This can only be used when the subscription is pull based.

154

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

155

156

     * @param batchSize the size of the batch

157

     * @param maxWaitMillis the maximum time to wait to collect messages for the batch, in milliseconds.

158

159

     * @return the list of messages

160

     * @throws IllegalStateException if not a pull subscription.

161

*/

162

    List<Message> fetch(int batchSize, long maxWaitMillis);

163

164

/**

165

     * Prepares an iterator. This uses <code>pullExpiresIn</code> under the covers,

166

     * and manages all responses. The iterator will have no messages if it does not

167

     * receive the first message within the max wait period. It will stop if the batch is

168

     * fulfilled or if there are fewer than batch size messages. 408 Status messages

169

     * are ignored and will not count toward the fulfilled batch size.

170

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

171

172

     * @param batchSize the size of the batch

173

     * @param maxWait the maximum time to wait for the first message.

174

175

     * @return the message iterator

176

     * @throws IllegalStateException if not a pull subscription.

177

*/

178

    Iterator<Message> iterate(int batchSize, Duration maxWait);

179

180

/**

181

     * Prepares an iterator. This uses <code>pullExpiresIn</code> under the covers,

182

     * and manages all responses. The iterator will have no messages if it does not

183

     * receive the first message within the max wait period. It will stop if the batch is

184

     * fulfilled or if there are fewer than batch size messages. 408 Status messages

185

     * are ignored and will not count toward the fulfilled batch size.

186

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

187

188

     * @param batchSize the size of the batch

189

     * @param maxWaitMillis the maximum time to wait for the first message, in milliseconds.

190

191

     * @return the message iterator

192

     * @throws IllegalStateException if not a pull subscription.

193

*/

194

    Iterator<Message> iterate(int batchSize, long maxWaitMillis);

195

196

/**

197

     * Prepares a reader. A reader looks like a push sync subscription,

198

     * meaning it is just an endless stream of messages to ask for by nextMessage,

199

     * but uses pull under the covers.

200

     * ! Pull subscriptions only. Push subscription will throw IllegalStateException

201

202

     * @param batchSize the size of the batch

203

     * @param repullAt the point in the current batch to tell the server to start the next batch

204

205

     * @return the message iterator

206

     * @throws IllegalStateException if not a pull subscription.

207

*/

208

    JetStreamReader reader(int batchSize, int repullAt);

209

210

/**

211

     * Gets information about the consumer behind this subscription.

212

     * @return consumer information

213

     * @throws IOException covers various communication issues with the NATS

214

     *         server such as timeout or interruption

215

     * @throws JetStreamApiException the request had an error related to the data

216

*/

217

    ConsumerInfo getConsumerInfo() throws IOException, JetStreamApiException;

218

nats-io / nats.java / #2213

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

1	// Copyright 2020 The NATS Authors
2	// Licensed under the Apache License, Version 2.0 (the "License");
3	// you may not use this file except in compliance with the License.
4	// You may obtain a copy of the License at:
5	//
6	// http://www.apache.org/licenses/LICENSE-2.0
7	//
8	// Unless required by applicable law or agreed to in writing, software
9	// distributed under the License is distributed on an "AS IS" BASIS,
10	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11	// See the License for the specific language governing permissions and
12	// limitations under the License.
13
14	package io.nats.client;
15
16	import io.nats.client.api.ConsumerInfo;
17
18	import java.io.IOException;
19	import java.time.Duration;
20	import java.util.Iterator;
21	import java.util.List;
22
23	/**
24	* Subscription on a JetStream context.
25	*/
26	public interface JetStreamSubscription extends Subscription {
27
28	/**
29	* Gets the consumer name associated with the subscription.
30	* @return the consumer name
31	*/
32	String getConsumerName();
33
34	/**
35	* Gets the stream name associated with the subscription.
36	* @return the stream name
37	*/
NEW 38	default String getStreamName() { return null; }	×
39
40	/**
41	* Initiate pull with the specified batch size.
42	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
43	* ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.
44	*
45	* @param batchSize the size of the batch
46	* @throws IllegalStateException if not a pull subscription.
47	*/
48	void pull(int batchSize);
49
50	/**
51	* Initiate pull with the specified request options
52	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
53	* ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.
54	*
55	* @param pullRequestOptions the options object
56	* @throws IllegalStateException if not a pull subscription.
57	*/
58	void pull(PullRequestOptions pullRequestOptions);
59
60	/**
61	* Initiate pull in noWait mode with the specified batch size.
62	* The fetch will return immediately with as many messages as are available. Between zero and the maximum configured.
63	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
64	* ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.
65	*
66	* @param batchSize the size of the batch
67	* @throws IllegalStateException if not a pull subscription.
68	*/
69	void pullNoWait(int batchSize);
70
71	/**
72	* Initiate pull in noWait mode with the specified batch size.
73	* The fetch will return immediately with as many messages as are available, but at least one message. Between one and the maximum configured.
74	* When no message is available it will wait for new messages to arrive till it expires.
75	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
76	* ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.
77	*
78	* @param batchSize the size of the batch
79	* @param expiresIn how long from now this request should be expired from the server wait list
80	* @throws IllegalStateException if not a pull subscription.
81	*/
82	void pullNoWait(int batchSize, Duration expiresIn);
83
84	/**
85	* Initiate pull in noWait mode with the specified batch size.
86	* The fetch will return immediately with as many messages as are available, but at least one message. Between one and the maximum configured.
87	* When no message is available it will wait for new messages to arrive till it expires.
88	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
89	* ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.
90	*
91	* @param batchSize the size of the batch
92	* @param expiresInMillis how long from now this request should be expired from the server wait list, in milliseconds
93	* @throws IllegalStateException if not a pull subscription.
94	*/
95	void pullNoWait(int batchSize, long expiresInMillis);
96
97	/**
98	* Initiate pull for all messages available before expiration.
99	* <p>
100	* <code>sub.nextMessage(timeout)</code> can return a:
101	* <ul>
102	* <li>regular JetStream message
103	* <li>null
104	* </ul>
105	* <p>
106	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
107	* ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.
108	*
109	* @param batchSize the size of the batch
110	* @param expiresIn how long from now this request should be expired from the server wait list
111	* @throws IllegalStateException if not a pull subscription.
112	*/
113	void pullExpiresIn(int batchSize, Duration expiresIn);
114
115	/**
116	* Initiate pull for all messages available before expiration.
117	* This can only be used when the subscription is pull based.
118	* <p>
119	* <code>sub.nextMessage(timeout)</code> can return a:
120	* <ul>
121	* <li>regular JetStream message
122	* <li>null
123	* </ul>
124	* <p>
125	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
126	* ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.
127	*
128	* @param batchSize the size of the batch
129	* @param expiresInMillis how long from now this request should be expired from the server wait list, in milliseconds
130	* @throws IllegalStateException if not a pull subscription.
131	*/
132	void pullExpiresIn(int batchSize, long expiresInMillis);
133
134	/**
135	* Fetch a list of messages up to the batch size, waiting no longer than maxWait.
136	* This uses <code>pullExpiresIn</code> under the covers, and manages all responses
137	* from <code>sub.nextMessage(...)</code> to only return regular JetStream messages.
138	* This can only be used when the subscription is pull based.
139	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
140	*
141	* @param batchSize the size of the batch
142	* @param maxWait the maximum time to wait to collect messages for the batch.
143	*
144	* @return the list of messages
145	* @throws IllegalStateException if not a pull subscription.
146	*/
147	List<Message> fetch(int batchSize, Duration maxWait);
148
149	/**
150	* Fetch a list of messages up to the batch size, waiting no longer than maxWait.
151	* This uses <code>pullExpiresIn</code> under the covers, and manages all responses
152	* from <code>sub.nextMessage(...)</code> to only return regular JetStream messages.
153	* This can only be used when the subscription is pull based.
154	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
155	*
156	* @param batchSize the size of the batch
157	* @param maxWaitMillis the maximum time to wait to collect messages for the batch, in milliseconds.
158	*
159	* @return the list of messages
160	* @throws IllegalStateException if not a pull subscription.
161	*/
162	List<Message> fetch(int batchSize, long maxWaitMillis);
163
164	/**
165	* Prepares an iterator. This uses <code>pullExpiresIn</code> under the covers,
166	* and manages all responses. The iterator will have no messages if it does not
167	* receive the first message within the max wait period. It will stop if the batch is
168	* fulfilled or if there are fewer than batch size messages. 408 Status messages
169	* are ignored and will not count toward the fulfilled batch size.
170	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
171	*
172	* @param batchSize the size of the batch
173	* @param maxWait the maximum time to wait for the first message.
174	*
175	* @return the message iterator
176	* @throws IllegalStateException if not a pull subscription.
177	*/
178	Iterator<Message> iterate(int batchSize, Duration maxWait);
179
180	/**
181	* Prepares an iterator. This uses <code>pullExpiresIn</code> under the covers,
182	* and manages all responses. The iterator will have no messages if it does not
183	* receive the first message within the max wait period. It will stop if the batch is
184	* fulfilled or if there are fewer than batch size messages. 408 Status messages
185	* are ignored and will not count toward the fulfilled batch size.
186	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
187	*
188	* @param batchSize the size of the batch
189	* @param maxWaitMillis the maximum time to wait for the first message, in milliseconds.
190	*
191	* @return the message iterator
192	* @throws IllegalStateException if not a pull subscription.
193	*/
194	Iterator<Message> iterate(int batchSize, long maxWaitMillis);
195
196	/**
197	* Prepares a reader. A reader looks like a push sync subscription,
198	* meaning it is just an endless stream of messages to ask for by nextMessage,
199	* but uses pull under the covers.
200	* ! Pull subscriptions only. Push subscription will throw IllegalStateException
201	*
202	* @param batchSize the size of the batch
203	* @param repullAt the point in the current batch to tell the server to start the next batch
204	*
205	* @return the message iterator
206	* @throws IllegalStateException if not a pull subscription.
207	*/
208	JetStreamReader reader(int batchSize, int repullAt);
209
210	/**
211	* Gets information about the consumer behind this subscription.
212	* @return consumer information
213	* @throws IOException covers various communication issues with the NATS
214	* server such as timeout or interruption
215	* @throws JetStreamApiException the request had an error related to the data
216	*/
217	ConsumerInfo getConsumerInfo() throws IOException, JetStreamApiException;
218	}

nats-io / nats.java / #2213

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