geronimo-websockets_1.0_spec/src/main/java/javax/websocket/Endpoint.java

/*
 * 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) {

    }
}