Package: MessageHandler$Partial

MessageHandler$Partial

Coverage

1: /*
2: * Copyright (c) 2018, 2019 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: /**
21: * Developers implement MessageHandlers in order to receive incoming messages during a web socket conversation. Each web
22: * socket session uses no more than one thread at a time to call its MessageHandlers. This means that, provided each
23: * message handler instance is used to handle messages for one web socket session, at most one thread at a time can be
24: * calling any of its methods. Developers who wish to handle messages from multiple clients within the same message
25: * handlers may do so by adding the same instance as a handler on each of the Session objects for the clients. In that
26: * case, they will need to code with the possibility of their MessageHandler being called concurrently by multiple
27: * threads, each one arising from a different client session.
28: *
29: * <p>
30: * See {@link Endpoint} for a usage example.
31: *
32: * @author dannycoward
33: */
34: public interface MessageHandler {
35:
36: /**
37: * This kind of handler is notified by the container on arrival of a complete message. If the message is received in
38: * parts, the container buffers it until it is has been fully received before this method is called.
39: *
40: * <p>
41: * For handling incoming text messages, the allowed types for T are
42: * <ul>
43: * <li>{@link java.lang.String}</li>
44: * <li>{@link java.io.Reader}</li>
45: * <li>any developer object for which there is a corresponding {@link Decoder.Text} or {@link Decoder.TextStream}
46: * configured</li>
47: * </ul>
48: *
49: * <p>
50: * For handling incoming binary messages, the allowed types for T are
51: * <ul>
52: * <li>{@link java.nio.ByteBuffer}</li>
53: * <li>byte[]</li>
54: * <li>{@link java.io.InputStream}</li>
55: * <li>any developer object for which there is a corresponding {@link Decoder.Binary} or
56: * {@link Decoder.BinaryStream} configured
57: * </ul>
58: *
59: * <p>
60: * For handling incoming pong messages, the type of T is {@link PongMessage}
61: *
62: * <p>
63: * Developers should not continue to reference message objects of type {@link java.io.Reader},
64: * {@link java.nio.ByteBuffer} or {@link java.io.InputStream} after the completion of the onMessage() call, since
65: * they may be recycled by the implementation.
66: *
67: * @param <T> The type of the message object that this MessageHandler will consume.
68: */
69: interface Whole<T> extends MessageHandler {
70:
71: /**
72: * Called when the message has been fully received.
73: *
74: * @param message the message data.
75: */
76: void onMessage(T message);
77: }
78:
79: /**
80: * This kind of handler is notified by the implementation as it becomes ready to deliver parts of a whole message.
81: *
82: * <p>
83: * For handling parts of text messages, the type T is {@link java.lang.String}
84: *
85: * <p>
86: * For handling parts of binary messages, the allowable types for T are
87: * <ul>
88: * <li>{@link java.nio.ByteBuffer}</li>
89: * <li>byte[]</li>
90: * </ul>
91: *
92: * <p>
93: * Developers should not continue to reference message objects of type {@link java.nio.ByteBuffer} after the
94: * completion of the onMessage() call, since they may be recycled by the implementation.
95: *
96: * <p>
97: * Note: Implementations may choose their own schemes for delivering large messages in smaller parts through this
98: * API. These schemes may or may not bear a relationship to the underlying websocket dataframes in which the message
99: * is received off the wire.
100: *
101: * @param <T> The type of the object that represent pieces of the incoming message that this MessageHandler will
102: * consume.
103: */
104: interface Partial<T> extends MessageHandler {
105:
106: /**
107: * Called when the next part of a message has been fully received.
108: *
109: * @param partialMessage the partial message data.
110: * @param last flag to indicate if this partialMessage is the last of the whole message being
111: * delivered.
112: */
113: void onMessage(T partialMessage, boolean last);
114: }
115: }