-
Notifications
You must be signed in to change notification settings - Fork 1
/
OnMessage.html
347 lines (340 loc) · 12.2 KB
/
OnMessage.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
<!DOCTYPE HTML>
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (11.0.2) on Sat Oct 21 15:44:48 UTC 2023 -->
<title>OnMessage (Tyrus 2.0.5 API)</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="dc.created" content="2023-10-21">
<link rel="stylesheet" type="text/css" href="../../stylesheet.css" title="Style">
<link rel="stylesheet" type="text/css" href="../../jquery/jquery-ui.css" title="Style">
<script type="text/javascript" src="../../script.js"></script>
<script type="text/javascript" src="../../jquery/jszip/dist/jszip.min.js"></script>
<script type="text/javascript" src="../../jquery/jszip-utils/dist/jszip-utils.min.js"></script>
<!--[if IE]>
<script type="text/javascript" src="../../jquery/jszip-utils/dist/jszip-utils-ie.min.js"></script>
<![endif]-->
<script type="text/javascript" src="../../jquery/jquery-3.3.1.js"></script>
<script type="text/javascript" src="../../jquery/jquery-migrate-3.0.1.js"></script>
<script type="text/javascript" src="../../jquery/jquery-ui.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="OnMessage (Tyrus 2.0.5 API)";
}
}
catch(err) {
}
//-->
var pathtoroot = "../../";
var useModuleDirectories = true;
loadScripts(document, 'script');</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<header role="banner">
<nav role="navigation">
<div class="fixedNav">
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a id="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a id="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../index.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/OnMessage.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../index-all.html">Index</a></li>
<li><a href="../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../allclasses.html">All Classes</a></li>
</ul>
<ul class="navListSearch">
<li><label for="search">SEARCH:</label>
<input type="text" id="search" value="search" disabled="disabled">
<input type="reset" id="reset" value="reset" disabled="disabled">
</li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
</div>
<div>
<ul class="subNavList">
<li>Summary: </li>
<li>Field | </li>
<li>Required | </li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail: </li>
<li>Field | </li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a id="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
</div>
<div class="navPadding"> </div>
<script type="text/javascript"><!--
$('.navPadding').css('padding-top', $('.fixedNav').css("height"));
//-->
</script>
</nav>
</header>
<!-- ======== START OF CLASS DATA ======== -->
<main role="main">
<div class="header">
<div class="subTitle"><span class="packageLabelInType">Package</span> <a href="package-summary.html">jakarta.websocket</a></div>
<h2 title="Annotation Type OnMessage" class="title">Annotation Type OnMessage</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<pre>@Retention(RUNTIME)
@Target(METHOD)
public @interface <span class="memberNameLabel">OnMessage</span></pre>
<div class="block">This method level annotation can be used to make a Java method receive incoming web socket messages. Each websocket
endpoint may only have one message handling method for each of the native websocket message formats: text, binary and
pong. Methods using this annotation are allowed to have parameters of types described below, otherwise the container
will generate an error at deployment time.
<p>
The allowed parameters are:
<ol>
<li>Exactly one of any of the following choices
<ul>
<li>if the method is handling text messages:
<ul>
<li><code>String</code> to receive the whole message</li>
<li>Java primitive or class equivalent to receive the whole message converted to that type</li>
<li>String and boolean pair to receive the message in parts</li>
<li><code>Reader</code> to receive the whole message as a blocking stream</li>
<li>any object parameter for which the endpoint has a text decoder (<a href="Decoder.Text.html" title="interface in jakarta.websocket"><code>Decoder.Text</code></a> or
<a href="Decoder.TextStream.html" title="interface in jakarta.websocket"><code>Decoder.TextStream</code></a>).</li>
</ul>
</li>
<li>if the method is handling binary messages:
<ul>
<li>byte[] or <code>ByteBuffer</code> to receive the whole message</li>
<li>byte[] and boolean pair, or <code>ByteBuffer</code> and boolean pair to receive the message in parts</li>
<li><code>InputStream</code> to receive the whole message as a blocking stream</li>
<li>any object parameter for which the endpoint has a binary decoder (<a href="Decoder.Binary.html" title="interface in jakarta.websocket"><code>Decoder.Binary</code></a> or
<a href="Decoder.BinaryStream.html" title="interface in jakarta.websocket"><code>Decoder.BinaryStream</code></a>).</li>
</ul>
</li>
<li>if the method is handling pong messages:
<ul>
<li><a href="PongMessage.html" title="interface in jakarta.websocket"><code>PongMessage</code></a> for handling pong messages</li>
</ul>
</li>
</ul>
</li>
<li>and Zero to n String or Java primitive parameters annotated with the <code>jakarta.websocket.server.PathParam</code>
annotation for server endpoints.</li>
<li>and an optional <a href="Session.html" title="interface in jakarta.websocket"><code>Session</code></a> parameter</li>
</ol>
<p>
The parameters may be listed in any order.
<p>
The method may have a non-void return type, in which case the web socket runtime must interpret this as a web socket
message to return to the peer. The allowed data types for this return type, other than void, are String, ByteBuffer,
byte[], any Java primitive or class equivalent, and anything for which there is an encoder. If the method uses a Java
primitive as a return value, the implementation must construct the text message to send using the standard Java
string representation of the Java primitive unless there developer provided encoder for the type configured for this
endpoint, in which case that encoder must be used. If the method uses a class equivalent of a Java primitive as a
return value, the implementation must construct the text message from the Java primitive equivalent as described
above.
<p>
Developers should note that if developer closes the session during the invocation of a method with a return type, the
method will complete but the return value will not be delivered to the remote endpoint. The send failure will be
passed back into the endpoint's error handling method.
<p>
For example:
<pre>
<code>
@OnMessage
public void processGreeting(String message, Session session) {
System.out.println("Greeting received:" + message);
}
</code>
</pre>
For example:
<pre>
<code>
@OnMessage
public void processUpload(byte[] b, boolean last, Session session) {
// process partial data here, which check on last to see if these is more on the way
}
</code>
</pre>
Developers should not continue to reference message objects of type <code>Reader</code>,
<code>ByteBuffer</code> or <code>InputStream</code> after the annotated method has completed, since they may
be recycled by the implementation.</div>
<dl>
<dt><span class="simpleTagLabel">Author:</span></dt>
<dd>dannycoward</dd>
</dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- =========== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY =========== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="annotation.type.optional.element.summary">
<!-- -->
</a>
<h3>Optional Element Summary</h3>
<table class="memberSummary">
<caption><span>Optional Elements</span><span class="tabEnd"> </span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colSecond" scope="col">Optional Element</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>long</code></td>
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#maxMessageSize()">maxMessageSize</a></span></code></th>
<td class="colLast">
<div class="block">Specifies the maximum size of message in bytes that the method this annotates will be able to process, or -1 to
indicate that there is no maximum.</div>
</td>
</tr>
</table>
</li>
</ul>
</section>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="annotation.type.element.detail">
<!-- -->
</a>
<h3>Element Detail</h3>
<a id="maxMessageSize()">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>maxMessageSize</h4>
<pre>long maxMessageSize</pre>
<div class="block">Specifies the maximum size of message in bytes that the method this annotates will be able to process, or -1 to
indicate that there is no maximum. The default is -1. This attribute only applies when the annotation is used to
process whole messages, not to those methods that process messages in parts or use a stream or reader parameter
to handle the incoming message. If the incoming whole message exceeds this limit, then the implementation
generates an error and closes the connection using the reason that the message was too big.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the maximum size in bytes.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>-1L</dd>
</dl>
</li>
</ul>
</li>
</ul>
</section>
</li>
</ul>
</div>
</div>
</main>
<!-- ========= END OF CLASS DATA ========= -->
<footer role="contentinfo">
<nav role="navigation">
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a id="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a id="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../index.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/OnMessage.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../index-all.html">Index</a></li>
<li><a href="../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../allclasses.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
</div>
<div>
<ul class="subNavList">
<li>Summary: </li>
<li>Field | </li>
<li>Required | </li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail: </li>
<li>Field | </li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a id="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</nav>
<p class="legalCopy"><small>Copyright © 2012–2020 <a href="http://www.oracle.com/">Oracle Corporation</a>. All rights reserved.</small></p>
</footer>
</body>
</html>