All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.websocket.RemoteEndpoint Maven / Gradle / Ivy

There is a newer version: 8.0.1
Show newest version
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * http://glassfish.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at packager/legal/LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */
package javax.websocket;

import java.io.IOException;
import java.io.OutputStream;
import java.io.Writer;
import java.nio.ByteBuffer;
import java.util.concurrent.Future;

/**
 * The RemoteEndpoint object is supplied by the container and represents the 
 * 'other end' or peer of the Web Socket conversation. Instances of the RemoteEndpoint
 * are obtained from the Session using {@link Session#getBasicRemote()} or
 * {@link Session#getAsyncRemote()}.
 * Objects of this kind include numerous ways to send web socket messages. There 
 * are two kinds of RemoteEndpoint objects: RemoteEndpoint.Basic for synchronous
 * sending of websocket messages, and RemoteEndpoint.Async for sending messages
 * asynchronously.
 *
 * 

There is no guarantee of the successful delivery of a web socket message to * the peer, but if the action of sending a message causes an error known to * the container, the API throws it. * RemoteEndpoints include a variety of ways to send messages: by whole message, * in parts, and in various data formats including websocket pings and pongs. * *

Implementations * may or may not support batching of messages. More detail of the expected semantics * of implementations that do support batching are laid out in {@link RemoteEndpoint#setBatchingAllowed(boolean)}. * *

Note: Implementations may choose their own schemes for sending large messages in smaller parts. These * schemes may or may not bear a relationship to the underlying websocket dataframes in which the message * is ultimately sent on the wire. * *

If the underlying connection is closed and methods on the RemoteEndpoint are attempted to be called, they will * result in an error being generated. For the methods that send messages, this will be an IOException, for the methods * that alter configuration of the endpoint, this will be runtime IllegalArgumentExceptions. * @author dannycoward */ public interface RemoteEndpoint { /** * Indicate to the implementation that it is allowed to batch outgoing messages * before sending. Not all implementations support batching of outgoing messages. * The default mode for RemoteEndpoints is false. If the developer * has indicated that batching of outgoing * messages is permitted, then the developer must call flushBatch() in order to be * sure that all the messages passed into the send methods of this RemoteEndpoint * are sent. * When batching is allowed, the implementations send operations are considered * to have completed if the message has been written to the local batch, in * the case when there is still room in the batch for the message, and are considered * to have completed if the batch has been send to the peer and the remainder * written to the new batch, in the case when * writing the message causes the batch to need to be sent. The blocking * and asynchronous send methods use this notion of completion in order * to complete blocking calls, notify SendHandlers and complete Futures respectively. * When batching is allowed, if the developer has called send methods * on this RemoteEndpoint without calling flushBatch(), then the implementation * may not have sent all the messages the developer has asked to be sent. If * the parameter value is false and the implementation has a batch of unsent messages, * then the implementation must immediately send the batch of unsent messages. * * @param allowed whether the implementation is allowed to batch messages. * @throws IOException if batching is being disabled and there are unsent messages * this error may be thrown as the implementation sends the batch of unsent messages if * there is a problem. */ void setBatchingAllowed(boolean allowed) throws IOException; /** * Return whether the implementation is allowed to batch outgoing messages * before sending. The default mode for RemoteEndpoints is false. The value * may be changed by calling {@link #setBatchingAllowed(boolean) setBatchingAllowed}. */ boolean getBatchingAllowed(); /** * This method is only used when batching is allowed for this RemoteEndpint. Calling * this method forces the implementation to send any unsent messages it has been batching. */ void flushBatch() throws IOException; /** * Send a Ping message containing the given application data to the remote endpoint. The corresponding Pong message may be picked * up using the MessageHandler.Pong handler. * * @param applicationData the data to be carried in the ping request. * @throws IOException if the ping failed to be sent * @throws IllegalArgumentException if the applicationData exceeds the maximum allowed payload of 125 bytes */ void sendPing(ByteBuffer applicationData) throws IOException, IllegalArgumentException; /** * Allows the developer to send an unsolicited Pong message containing the given application * data in order to serve as a unidirectional * heartbeat for the session. * * @param applicationData the application data to be carried in the pong response. * @throws IOException if the pong failed to be sent * @throws IllegalArgumentException if the applicationData exceeds the maximum allowed payload of 125 bytes */ void sendPong(ByteBuffer applicationData) throws IOException, IllegalArgumentException; /** * This representation of the peer of a web socket conversation has the ability * to send messages asynchronously. The point of completion of the send is * defined when all the supplied data has been written to the underlying connection. * The completion handlers for the asynchronous methods are always called with * a different thread from that which initiated the send. */ interface Async extends RemoteEndpoint { /** * Return the number of milliseconds the implementation will timeout * attempting to send a websocket message. A non-positive number indicates * the implementation will not timeout attempting to send a websocket message * asynchronously. This value overrides the default value assigned in the * WebSocketContainer. * * @return the timeout time in milliseconds. */ long getSendTimeout(); /** * Sets the number of milliseconds the implementation will timeout * attempting to send a websocket message. A non-positive number indicates * the implementation will not timeout attempting to send a websocket message * asynchronously. This value overrides the default value assigned in the * WebSocketContainer. * * @param timeoutmillis The number of milliseconds this RemoteEndpoint will wait before timing out * an incomplete asynchronous message send. */ void setSendTimeout(long timeoutmillis); /** * Initiates the asynchronous transmission of a text message. This method returns before the message * is transmitted. Developers provide a callback to be notified when the message has been * transmitted. Errors * in transmission are given to the developer in the SendResult object. * * @param text the text being sent. * @param handler the handler which will be notified of progress. * @throws IllegalArgumentException if the text or the handler is {@code null}. */ void sendText(String text, SendHandler handler); /** * Initiates the asynchronous transmission of a text message. This method * returns before the message is transmitted. Developers use the * returned Future object to track progress of the transmission. The * Future's get() method returns {@code null} upon successful completion. Errors * in transmission are wrapped in the {@link java.util.concurrent.ExecutionException} * thrown when querying the Future object. * * @param text the text being sent. * @return the Future object representing the send operation. * @throws IllegalArgumentException if the text is {@code null}. */ Future sendText(String text); /** * Initiates the asynchronous transmission of a binary message. This method returns before the message * is transmitted. Developers use the returned Future object to track progress of the transmission. The * Future's get() method returns {@code null} upon successful completion. Errors * in transmission are wrapped in the {@link java.util.concurrent.ExecutionException} * thrown when querying the Future object. * * @param data the data being sent. * @return the Future object representing the send operation. * @throws IllegalArgumentException if the data is {@code null}. */ Future sendBinary(ByteBuffer data); /** * Initiates the asynchronous transmission of a binary message. This method returns before the message * is transmitted. Developers provide a callback to be notified when the message has been * transmitted. Errors in transmission are given to the developer in the SendResult object. * * @param data the data being sent, must not be {@code null}. * @param handler the handler that will be notified of progress, must not be {@code null}. * @throws IllegalArgumentException if either the data or the handler are {@code null}. */ void sendBinary(ByteBuffer data, SendHandler handler); /** * Initiates the asynchronous transmission of a custom developer object. * The developer will have provided an encoder for this object * type in the endpoint configuration. Containers will by default be able * to encode java primitive types and their object equivalents, otherwise * the developer must have provided an encoder for the object type in the * endpoint configuration. Progress may be tracked using the Future object. * The Future's get() methods return {@code null} upon successful completion. Errors * in transmission are wrapped in the {@link java.util.concurrent.ExecutionException} * thrown when querying the Future object. * * @param data the object being sent. * @return the Future object representing the send operation. * @throws IllegalArgumentException if the data is {@code null}. */ Future sendObject(Object data); /** * Initiates the asynchronous transmission of a custom developer object. * Containers will by default be able to encode java primitive types and * their object equivalents, otherwise the developer must have provided an encoder * for the object type in the endpoint configuration. Developers * are notified when transmission is complete through the supplied callback object. * * @param data the object being sent. * @param handler the handler that will be notified of progress, must not be {@code null}. * @throws IllegalArgumentException if either the data or the handler are {@code null}. */ void sendObject(Object data, SendHandler handler); } /** * This representation of the peer of a web socket conversation has the ability * to send messages synchronously. The point of completion of the send is * defined when all the supplied data has been written to the underlying connection. * The methods for sending messages on the RemoteEndpoint.Basic block until this * point of completion is reached, except for {@link RemoteEndpoint.Basic#getSendStream() getSendStream} * and {@link RemoteEndpoint.Basic#getSendWriter() getSendWriter} which present * traditional blocking I/O streams to write messages. * *

If the websocket connection underlying this RemoteEndpoint is busy sending a message when a call is made * to send another one, for example if two threads attempt to call a send method * concurrently, or if a developer attempts to send a new message while in the * middle of sending an existing one, the send method called while * the connection is already busy may throw an {@link java.lang.IllegalStateException}. */ interface Basic extends RemoteEndpoint { /** * Send a text message, blocking until all of the message has been transmitted. * * @param text the message to be sent. * @throws IOException if there is a problem delivering the message. * @throws IllegalArgumentException if the text is {@code null}. */ void sendText(String text) throws IOException; /** * Send a binary message, returning when all of the message has been transmitted. * * @param data the message to be sent. * @throws IOException if there is a problem delivering the message. * @throws IllegalArgumentException if the data is {@code null}. */ void sendBinary(ByteBuffer data) throws IOException; /** * Send a text message in parts, blocking until all of the message has been transmitted. The runtime * reads the message in order. Non-final parts of the message are sent with isLast set to false. The final part * must be sent with isLast set to true. * * @param partialMessage the parts of the message being sent. * @param isLast Whether the partial message being sent is the last part of the message. * @throws IOException if there is a problem delivering the message fragment. * @throws IllegalArgumentException if the partialMessage is {@code null}. */ void sendText(String partialMessage, boolean isLast) throws IOException; /** * Send a binary message in parts, blocking until all of the message has been transmitted. The runtime * reads the message in order. Non-final parts are sent with isLast set to false. The final piece * must be sent with isLast set to true. * * @param partialByte the part of the message being sent. * @param isLast Whether the partial message being sent is the last part of the message. * @throws IOException if there is a problem delivering the partial message. * @throws IllegalArgumentException if the partialByte is {@code null}. */ void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException; // or Iterable /** * Opens an output stream on which a binary message may be sent. The developer must close the output stream in order * to indicate that the complete message has been placed into the output stream. * * @return the output stream to which the message will be written. * @throws IOException if there is a problem obtaining the OutputStream to write the binary message. */ OutputStream getSendStream() throws IOException; /** * Opens an character stream on which a text message may be sent. The developer must close the writer in order * to indicate that the complete message has been placed into the character stream. * * @return the writer to which the message will be written. * @throws IOException if there is a problem obtaining the Writer to write the text message. */ Writer getSendWriter() throws IOException; /** * Sends a custom developer object, blocking until it has been transmitted. * Containers will by default be able to encode java primitive types and * their object equivalents, otherwise the developer must have provided an encoder * for the object type in the endpoint configuration. A developer-provided * encoder for a Java primitive type overrides the container default * encoder. * * @param data the object to be sent. * @throws IOException if there is a communication error sending the message object. * @throws EncodeException if there was a problem encoding the message object into the form of a native websocket message. * @throws IllegalArgumentException if the data parameter is {@code null} */ void sendObject(Object data) throws IOException, EncodeException; } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy