Package: OnMessage

OnMessage

Coverage

1: /*
2: * Copyright (c) 2018, 2023 Oracle and/or its affiliates and others.
3: * All rights reserved.
4: *
5: * This program and the accompanying materials are made available under the
6: * terms of the Eclipse Public License v. 2.0, which is available at
7: * http://www.eclipse.org/legal/epl-2.0.
8: *
9: * This Source Code may also be made available under the following Secondary
10: * Licenses when the conditions for such availability set forth in the
11: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
12: * version 2 with the GNU Classpath Exception, which is available at
13: * https://www.gnu.org/software/classpath/license.html.
14: *
15: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
16: */
17:
18: package jakarta.websocket;
19:
20: import java.lang.annotation.ElementType;
21: import java.lang.annotation.Retention;
22: import java.lang.annotation.RetentionPolicy;
23: import java.lang.annotation.Target;
24:
25: /**
26: * This method level annotation can be used to make a Java method receive incoming web socket messages. Each websocket
27: * endpoint may only have one message handling method for each of the native websocket message formats: text, binary and
28: * pong. Methods using this annotation are allowed to have parameters of types described below, otherwise the container
29: * will generate an error at deployment time.
30: * <p>
31: * The allowed parameters are:
32: * <ol>
33: * <li>Exactly one of any of the following choices
34: * <ul>
35: * <li>if the method is handling text messages:
36: * <ul>
37: * <li>{@link java.lang.String} to receive the whole message</li>
38: * <li>Java primitive or class equivalent to receive the whole message converted to that type</li>
39: * <li>String and boolean pair to receive the message in parts</li>
40: * <li>{@link java.io.Reader} to receive the whole message as a blocking stream</li>
41: * <li>any object parameter for which the endpoint has a text decoder ({@link Decoder.Text} or
42: * {@link Decoder.TextStream}).</li>
43: * </ul>
44: * </li>
45: * <li>if the method is handling binary messages:
46: * <ul>
47: * <li>byte[] or {@link java.nio.ByteBuffer} to receive the whole message</li>
48: * <li>byte[] and boolean pair, or {@link java.nio.ByteBuffer} and boolean pair to receive the message in parts</li>
49: * <li>{@link java.io.InputStream} to receive the whole message as a blocking stream</li>
50: * <li>any object parameter for which the endpoint has a binary decoder ({@link Decoder.Binary} or
51: * {@link Decoder.BinaryStream}).</li>
52: * </ul>
53: * </li>
54: * <li>if the method is handling pong messages:
55: * <ul>
56: * <li>{@link PongMessage} for handling pong messages</li>
57: * </ul>
58: * </li>
59: * </ul>
60: * </li>
61: * <li>and Zero to n String or Java primitive parameters annotated with the {@code jakarta.websocket.server.PathParam}
62: * annotation for server endpoints.</li>
63: * <li>and an optional {@link Session} parameter</li>
64: * </ol>
65: * <p>
66: * The parameters may be listed in any order.
67: *
68: * <p>
69: * The method may have a non-void return type, in which case the web socket runtime must interpret this as a web socket
70: * message to return to the peer. The allowed data types for this return type, other than void, are String, ByteBuffer,
71: * byte[], any Java primitive or class equivalent, and anything for which there is an encoder. If the method uses a Java
72: * primitive as a return value, the implementation must construct the text message to send using the standard Java
73: * string representation of the Java primitive unless there developer provided encoder for the type configured for this
74: * endpoint, in which case that encoder must be used. If the method uses a class equivalent of a Java primitive as a
75: * return value, the implementation must construct the text message from the Java primitive equivalent as described
76: * above.
77: *
78: * <p>
79: * Developers should note that if developer closes the session during the invocation of a method with a return type, the
80: * method will complete but the return value will not be delivered to the remote endpoint. The send failure will be
81: * passed back into the endpoint's error handling method.
82: *
83: * <p>
84: * For example:
85: *
86: * <pre>
87: * <code>
88: * @OnMessage
89: * public void processGreeting(String message, Session session) {
90: * System.out.println("Greeting received:" + message);
91: * }
92: * </code>
93: * </pre>
94: *
95: * For example:
96: *
97: * <pre>
98: * <code>
99: * @OnMessage
100: * public void processUpload(byte[] b, boolean last, Session session) {
101: * // process partial data here, which check on last to see if these is more on the way
102: * }
103: * </code>
104: * </pre>
105: *
106: * Developers should not continue to reference message objects of type {@link java.io.Reader},
107: * {@link java.nio.ByteBuffer} or {@link java.io.InputStream} after the annotated method has completed, since they may
108: * be recycled by the implementation.
109: *
110: * @author dannycoward
111: */
112: @Retention(RetentionPolicy.RUNTIME)
113: @Target(ElementType.METHOD)
114: public @interface OnMessage {
115:
116: /**
117: * Specifies the maximum size of message in bytes that the method this annotates will be able to process, or -1 to
118: * indicate that no maximum has been configured. The default is -1. This attribute only applies when the annotation
119: * is used to process whole messages, not to those methods that process messages in parts or use a stream or reader
120: * parameter to handle the incoming message. If the incoming whole message exceeds this limit, then the
121: * implementation generates an error and closes the connection using the reason that the message was too big.
122: * <p>
123: * Setting this attribute to a value larger than {@code Integer#MAX_VALUE} will trigger a
124: * {@code DeploymentException} unless the JVM supports Strings (for text messages) or ByteBuffers (for binary
125: * messages) larger than {@code Integer#MAX_VALUE}. Note that, as of Java 22, there are no plans for such support.
126: *
127: * @return the maximum size in bytes.
128: */
129: public long maxMessageSize() default -1;
130: }