| /* |
| * 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. |
| */ |
| |
| package javax.websocket; |
| |
| import java.lang.annotation.ElementType; |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.lang.annotation.Target; |
| |
| /** |
| * 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>String 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>Reader to receive the whole message as a blocking stream</li> |
| * <li>any object parameter for which the endpoint has a text decoder (Decoder.Text or Decoder.TextStream).</li> |
| * </ul> |
| * </li> |
| * <li>if the method is handling binary messages: |
| * <ul> |
| * <li>byte[] or ByteBuffer to receive the whole message</li> |
| * <li>byte[] and boolean pair, or ByteBuffer and boolean pair to receive the message in parts</li> |
| * <li>InputStream to receive the whole message as a blocking stream</li> |
| * <li>any object parameter for which the endpoint has a binary decoder (Decoder.Binary or Decoder.BinaryStream).</li> |
| * </ul> |
| * </li> |
| * <li>if the method is handling pong messages: |
| * <ul> |
| * <li>PongMessage for handling pong messages</li> |
| * </ul> |
| * </li> |
| * </ul> |
| * </li> |
| * <li>and Zero to n String or Java primitive parameters annotated with the PathParam annotation for server endpoints.</li> |
| * <li>and an optional Session 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: |
| * <p/> |
| * <code> |
| * |
| * @OnMessage public void processGreeting(String message, Session session) { System.out.println("Greeting received:" + |
| * message); } </code> |
| * <p/> |
| * For example: |
| * <p/> |
| * <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> |
| * <p/> |
| * Developers should not continue to reference message objects of type Reader, ByteBuffer or InputStream |
| * after the annotated method has completed, since they may be recycled by the implementation. |
| */ |
| @Retention(value = RetentionPolicy.RUNTIME) |
| @Target(value = ElementType.METHOD) |
| public @interface OnMessage { |
| long maxMessageSize() default -1L; |
| } |