001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.protocol.ws.api;
018
019import java.io.IOException;
020import java.util.concurrent.Future;
021
022import org.apache.wicket.Application;
023import org.apache.wicket.protocol.ws.api.message.IWebSocketPushMessage;
024import org.apache.wicket.protocol.ws.api.registry.IKey;
025
026/**
027 * Common interface for native WebSocket connections
028 *
029 * @since 6.0
030 */
031public interface IWebSocketConnection
032{
033        /**
034         * @return {@code true} when the underlying native web socket
035         *      connection is still open.
036         */
037        boolean isOpen();
038
039        /**
040         * Closes the underlying web socket connection
041         *
042         * @param code
043         *      the status code
044         * @param reason
045         *      the reason to close the connection
046         */
047        void close(int code, String reason);
048
049        /**
050         * Sends a text message to the client.
051         *
052         * @param message
053         *      the text message
054         * @return {@code this} object, for chaining methods
055         * @throws IOException when an IO error occurs during the write to the client
056         */
057        IWebSocketConnection sendMessage(String message) throws IOException;
058
059    /**
060     * Sends a text message to the client in an asynchronous way.
061     *
062     * @param message
063     *      the text message
064     * @return a {@link java.util.concurrent.Future} representing the send operation
065     *
066     */
067    Future<Void> sendMessageAsync(String message);
068
069    /**
070     * Sends a text message to the client in an asynchronous way.
071     *
072     * @param message
073     *      the text message
074     * @param timeout
075     *      the timeout for operation
076     * @return a {@link java.util.concurrent.Future} representing the send operation
077     */
078    Future<Void> sendMessageAsync(String message, long timeout);
079
080        /**
081         * Sends a binary message to the client.
082         *
083         * @param message
084         *      the binary message
085         * @param offset
086         *      the offset to read from
087         * @param length
088         *      how much data to read
089         * @return {@code this} object, for chaining methods
090         * @throws IOException when an IO error occurs during the write to the client
091         */
092        IWebSocketConnection sendMessage(byte[] message, int offset, int length) throws IOException;
093
094    /**
095     * Sends a binary message to the client in an asynchronous way.
096     *
097     * @param message
098     *      the binary message
099     * @param offset
100     *      the offset to read from
101     * @param length
102     *      how much data to read
103     * @return a {@link java.util.concurrent.Future} representing the send operation
104     */
105    Future<Void> sendMessageAsync(byte[] message, int offset, int length);
106
107    /**
108     * Sends a binary message to the client in an asynchronous way.
109     *
110     * @param message
111     *      the binary message
112     * @param offset
113     *      the offset to read from
114     * @param length
115     *      how much data to read
116     * @param timeout
117     *      the timeout for operation
118     * @return a {@link java.util.concurrent.Future} representing the send operation
119     */
120    Future<Void> sendMessageAsync(byte[] message, int offset, int length, long timeout);
121
122        /**
123         * Broadcasts a push message to the wicket page (and it's components) associated with this
124         * connection. The components can then send messages or component updates to client by adding
125         * them to the target.
126         *
127         * @param message
128         *     the push message to send
129         * @since 6.4
130         */
131        void sendMessage(IWebSocketPushMessage message);
132
133        /**
134         * Broadcasts a push message to the wicket page (and it's components) associated with this
135         * connection. The components can then send messages or component updates to client by adding
136         * them to the target. Pushing to client is done asynchronously.
137         *
138         * @param message
139         *     the push message to send
140         *
141         */
142        void sendMessageAsync(IWebSocketPushMessage message);
143
144
145        /**
146         * Broadcasts a push message to the wicket page (and it's components) associated with this
147         * connection. The components can then send messages or component updates to client by adding
148         * them to the target. Pushing to client is done asynchronously.
149         *
150         * @param message
151         *     the push message to send
152         * @param timeout
153         *     the timeout in milliseconds
154         *
155         */
156        void sendMessageAsync(IWebSocketPushMessage message, long timeout);
157
158        /**
159         * @return The application for which this WebSocket connection is registered
160         */
161        Application getApplication();
162
163        /**
164         * @return The id of the session for which this WebSocket connection is registered
165         */
166        String getSessionId();
167
168        /**
169         * @return The registry key for which this WebSocket connection is registered
170         */
171        IKey getKey();
172}