blob: a48f4b6581f6209ff777d92273d258779cb2da1f [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<title>OnMessage</title>
<link rel="stylesheet" type="text/css" href="../../stylesheet.css" title="Style">
<script type="text/javascript" src="../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="OnMessage";
}
}
catch(err) {
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</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">
<li><a href="../../jakarta/websocket/OnError.html" title="annotation in jakarta.websocket"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../jakarta/websocket/OnOpen.html" title="annotation in jakarta.websocket"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../index.html?jakarta/websocket/OnMessage.html" target="_top">Frames</a></li>
<li><a href="OnMessage.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../allclasses-noframe.html">All&nbsp;Classes</a></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>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Required&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">jakarta.websocket</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>
<br>
<pre>@Retention(value=RUNTIME)
@Target(value=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="../../jakarta/websocket/Decoder.Text.html" title="interface in jakarta.websocket"><code>Decoder.Text</code></a> or
<a href="../../jakarta/websocket/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="../../jakarta/websocket/Decoder.Binary.html" title="interface in jakarta.websocket"><code>Decoder.Binary</code></a> or
<a href="../../jakarta/websocket/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="../../jakarta/websocket/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="../../jakarta/websocket/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>
&#64;OnMessage
public void processGreeting(String message, Session session) {
System.out.println("Greeting received:" + message);
}
</code>
</pre>
For example:
<pre>
<code>
&#64;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>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- =========== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.optional.element.summary">
<!-- -->
</a>
<h3>Optional Element Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Optional Element Summary table, listing optional elements, and an explanation">
<caption><span>Optional Elements</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Optional Element and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>long</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/websocket/OnMessage.html#maxMessageSize--">maxMessageSize</a></span></code>
<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>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.element.detail">
<!-- -->
</a>
<h3>Element Detail</h3>
<a name="maxMessageSize--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>maxMessageSize</h4>
<pre>public abstract&nbsp;long&nbsp;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>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</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">
<li><a href="../../jakarta/websocket/OnError.html" title="annotation in jakarta.websocket"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../jakarta/websocket/OnOpen.html" title="annotation in jakarta.websocket"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../index.html?jakarta/websocket/OnMessage.html" target="_top">Frames</a></li>
<li><a href="OnMessage.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../allclasses-noframe.html">All&nbsp;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>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Required&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</body>
</html>