| package javax.websocket; |
| |
| /** |
| * Developers implement MessageHandlers in order to receive incoming messages during a web socket conversation. Each web |
| * socket session uses no more than one thread at a time to call its MessageHandlers. This means that, provided each |
| * message handler instance is used to handle messages for one web socket session, at most one thread at a time can be |
| * calling any of its methods. Developers who wish to handle messages from multiple clients within the same message |
| * handlers may do so by adding the same instance as a handler on each of the Session objects for the clients. In that |
| * case, they will need to code with the possibility of their MessageHandler being called concurrently by multiple |
| * threads, each one arising from a different client session. |
| * <p/> |
| * See Endpoint for a usage example. |
| */ |
| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| public interface MessageHandler { |
| |
| /** |
| * This kind of handler is notified by the implementation as it becomes ready to deliver parts of a whole message. |
| * <p/> |
| * For handling parts of text messages, the type T is String |
| * <p/> |
| * For handling parts of binary messages, the allowable types for T are |
| * <ul> |
| * <li>ByteBuffer</li> |
| * <li>byte[]</li> |
| * </ul> |
| * <p/> |
| * Developers should not continue to reference message objects of type ByteBuffer after the completion of the |
| * onMessage() call, since they may be recycled by the implementation. |
| * <p/> |
| * Note: Implementations may choose their own schemes for delivering large messages in smaller parts through this |
| * API. These schemes may or may not bear a relationship to the underlying websocket dataframes in which the message |
| * is received off the wire. |
| * |
| * @param <T> |
| * The type of the object that represent pieces of the incoming message that this MessageHandler will |
| * consume. |
| */ |
| public static interface Partial<T> extends MessageHandler { |
| /** |
| * Called when the next part of a message has been fully received. |
| * |
| * @param partialMessage |
| * the partial message data. |
| * @param last |
| * flag to indicate if this partialMessage is the last of the whole message being delivered. |
| */ |
| void onMessage(T partialMessage, boolean last); |
| } |
| |
| /** |
| * This kind of handler is notified by the container on arrival of a complete message. If the message is received in |
| * parts, the container buffers it until it is has been fully received before this method is called. |
| * <p/> |
| * For handling incoming text messages, the allowed types for T are |
| * <ul> |
| * <li>String</li> |
| * <li>Reader</li> |
| * <li>any developer object for which there is a corresponding Decoder.Text or Decoder.TextStream configured</li> |
| * </ul> |
| * <p/> |
| * For handling incoming binary messages, the allowed types for T are |
| * <ul> |
| * <li>ByteBuffer</li> |
| * <li>byte[]</li> |
| * <li>InputStream</li> |
| * <li>any developer object for which there is a corresponding Decoder.Binary or Decoder.BinaryStream configured</li> |
| * </ul> |
| * <p/> |
| * For handling incoming pong messages, the type of T is PongMessage |
| * <p/> |
| * Developers should not continue to reference message objects of type Reader, ByteBuffer or InputStream after the |
| * completion of the onMessage() call, since they may be recycled by the implementation. |
| * |
| * @param <T> |
| * The type of the message object that this MessageHandler will consume. |
| */ |
| public static interface Whole<T> extends MessageHandler { |
| /** |
| * Called when the message has been fully received. |
| * |
| * @param message |
| * the message data. |
| */ |
| void onMessage(T message); |
| } |
| } |