| /* |
| * 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; |
| |
| /** |
| * The Web Socket Endpoint represents an object that can handle websocket conversations. Developers may extend this |
| * class in order to implement a programmatic websocket endpoint. The Endpoint class holds lifecycle methods that may be |
| * overridden to intercept websocket open, error and close events. By implementing the onOpen method, the programmatic |
| * endpoint gains access to the Session object, to which the developer may add MessageHandler implementations in order |
| * to intercept incoming websocket messages. Each instance of a websocket endpoint is guaranteed not to be called by |
| * more than one thread at a time per active connection. |
| * <p/> |
| * If deployed as a client endpoint, it will be instantiated once for the single connection to the server. |
| * <p/> |
| * When deployed as a server endpoint, the implementation uses the |
| * ServerEndpointConfig.Configurator.getEndpointInstance(java.lang.Class<T>) method to obtain the endpoint instance it |
| * will use for each new client connection. If the developer uses the default ServerEndpointConfig.Configurator, there |
| * will be precisely one endpoint instance per active client connection. Consequently, in this typical case, when |
| * implementing/overriding the methods of Endpoint, the developer is guaranteed that there will be at most one thread |
| * calling each endpoint instance at a time. |
| * <p/> |
| * If the developer provides a custom ServerEndpointConfig.Configurator which overrides the default policy for endpoint |
| * instance creation, for example, using a single Endpoint instance for multiple client connections, the developer may |
| * need to write code that can execute concurrently. |
| * <p/> |
| * Here is an example of a simple endpoint that echoes any incoming text message back to the sender. |
| * <p/> |
| * <code> |
| * public class EchoServer extends Endpoint { |
| * |
| * public void onOpen(Session session, EndpointConfig config) { |
| * final RemoteEndpoint remote = session.getBasicRemote(); |
| * session.addMessageHandler(new MessageHandler.Whole<String>() { |
| * public void onMessage(String text) { |
| * try { |
| * remote.sendString("Got your message (" + text + "). Thanks !"); |
| * } catch (IOException ioe) { |
| * // handle send failure here |
| * } |
| * } |
| * }); |
| * } |
| * |
| * } |
| * </code> |
| */ |
| public abstract class Endpoint { |
| |
| public Endpoint() { |
| super(); |
| } |
| |
| /** |
| * Developers must implement this method to be notified when a new conversation has just begun. |
| * |
| * @param session |
| * the session that has just been activated. |
| * @param config |
| * the configuration used to configure this endpoint. |
| */ |
| public abstract void onOpen(Session session, EndpointConfig config); |
| |
| /** |
| * This method is called immediately prior to the session with the remote peer being closed. It is called whether |
| * the session is being closed because the remote peer initiated a close and sent a close frame, or whether the |
| * local websocket container or this endpoint requests to close the session. The developer may take this last |
| * opportunity to retrieve session attributes such as the ID, or any application data it holds before it becomes |
| * unavailable after the completion of the method. Developers should not attempt to modify the session from within |
| * this method, or send new messages from this call as the underlying connection will not be able to send them at |
| * this stage. |
| * |
| * @param session |
| * the session about to be closed. |
| * @param closeReason |
| * the reason the session was closed. |
| */ |
| public void onClose(Session session, CloseReason closeReason) { |
| |
| } |
| |
| /** |
| * Developers may implement this method when the web socket session creates some kind of error that is not modeled |
| * in the web socket protocol. This may for example be a notification that an incoming message is too big to handle, |
| * or that the incoming message could not be encoded. |
| * <p/> |
| * There are a number of categories of exception that this method is (currently) defined to handle: |
| * <ul> |
| * <li>connection problems, for example, a socket failure that occurs before the web socket connection can be |
| * formally closed. These are modeled as SessionExceptions</li> |
| * <li>runtime errors thrown by developer created message handlers calls.</li> |
| * <li>conversion errors encoding incoming messages before any message handler has been called. These are modeled as |
| * DecodeExceptions</li> |
| * |
| * @param session |
| * the session in use when the error occurs. |
| * @param thr |
| * the throwable representing the problem. |
| */ |
| public void onError(Session session, Throwable thr) { |
| |
| } |
| } |