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 org.apache.wicket.core.request.handler.IPartialPageRequestHandler;
020import org.apache.wicket.request.ILoggableRequestHandler;
021
022import java.util.concurrent.Future;
023
024/**
025 * An interface for outbound communication with web socket clients
026 *
027 * @since 6.0
028 */
029public interface IWebSocketRequestHandler extends IPartialPageRequestHandler, ILoggableRequestHandler
030{
031        /**
032         * Pushes a text message to the client.
033         *
034         * @param message
035         *      the text message to push to the client if the web socket connection is open
036         */
037        void push(CharSequence message);
038
039        /**
040         * Pushes a text message to the client in an asynchronous way.
041         *
042         * @param message
043         *      the text message to push to the client if the web socket connection is open
044         * @return
045         *      a {@link java.util.concurrent.Future} representing the send operation. Or null if connection is closed.
046         */
047        Future<Void> pushAsync(CharSequence message);
048
049        /**
050         * Pushes a text message to the client in an asynchronous way.
051         *
052         * @param message
053         *      the text message to push to the client if the web socket connection is open
054         * @param timeout
055         *      the timeout for operation
056         * @return
057         *              a {@link java.util.concurrent.Future} representing the send operation. Or null if connection is closed.
058         */
059        Future<Void> pushAsync(CharSequence message, long timeout);
060
061        /**
062         * Pushes a binary message to the client.
063         *
064         * @param message
065         *      the binary message to push to the client if the web socket connection is open
066         * @param offset
067         *      the offset to start to read from the message
068         * @param length
069         *      how many bytes to read from the message
070         */
071        void push(byte[] message, int offset, int length);
072
073        /**
074         * Pushes a binary message to the client.
075         *
076         * @param message
077         *      the binary message to push to the client if the web socket connection is open
078         * @param offset
079         *      the offset to start to read from the message
080         * @param length
081         *      how many bytes to read from the message
082         * @return
083         *              a {@link java.util.concurrent.Future} representing the send operation. Or null if connection is closed.
084         */
085        Future<Void> pushAsync(byte[] message, int offset, int length);
086
087        /**
088         * Pushes a binary message to the client.
089         *
090         * @param message
091         *      the binary message to push to the client if the web socket connection is open
092         * @param offset
093         *      the offset to start to read from the message
094         * @param length
095         *      how many bytes to read from the message
096         * @param timeout
097         *      the timeout for operation
098         * @return
099         *              a {@link java.util.concurrent.Future} representing the send operation. Or null if connection is closed.
100         */
101        Future<Void> pushAsync(byte[] message, int offset, int length, long timeout);
102}