001/*
002 * Copyright 2002-2020 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.springframework.web.reactive.socket;
017
018import java.util.Map;
019import java.util.function.Function;
020
021import org.reactivestreams.Publisher;
022import reactor.core.publisher.Flux;
023import reactor.core.publisher.Mono;
024
025import org.springframework.core.io.buffer.DataBuffer;
026import org.springframework.core.io.buffer.DataBufferFactory;
027
028/**
029 * Represents a WebSocket session.
030 *
031 * <p>Use {@link WebSocketSession#receive() session.receive()} to compose on
032 * the inbound message stream, and {@link WebSocketSession#send(Publisher)
033 * session.send(publisher)} to provide the outbound message stream.
034 *
035 * @author Rossen Stoyanchev
036 * @since 5.0
037 */
038public interface WebSocketSession {
039
040        /**
041         * Return the id for the session.
042         */
043        String getId();
044
045        /**
046         * Return information from the handshake request.
047         */
048        HandshakeInfo getHandshakeInfo();
049
050        /**
051         * Return a {@code DataBuffer} Factory to create message payloads.
052         * @return the buffer factory for the session
053         */
054        DataBufferFactory bufferFactory();
055
056        /**
057         * Return the map with attributes associated with the WebSocket session.
058         * @return a Map with the session attributes (never {@code null})
059         * @since 5.1
060         */
061        Map<String, Object> getAttributes();
062
063        /**
064         * Provides access to the stream of inbound messages.
065         * <p>This stream receives a completion or error signal when the connection
066         * is closed. In a typical {@link WebSocketHandler} implementation this
067         * stream is composed into the overall processing flow, so that when the
068         * connection is closed, handling will end.
069         * <p>See the class-level doc of {@link WebSocketHandler} and the reference
070         * for more details and examples of how to handle the session.
071         */
072        Flux<WebSocketMessage> receive();
073
074        /**
075         * Give a source of outgoing messages, write the messages and return a
076         * {@code Mono<Void>} that completes when the source completes and writing
077         * is done.
078         * <p>See the class-level doc of {@link WebSocketHandler} and the reference
079         * for more details and examples of how to handle the session.
080         */
081        Mono<Void> send(Publisher<WebSocketMessage> messages);
082
083        /**
084         * Close the WebSocket session with {@link CloseStatus#NORMAL}.
085         */
086        default Mono<Void> close() {
087                return close(CloseStatus.NORMAL);
088        }
089
090        /**
091         * Close the WebSocket session with the given status.
092         * @param status the close status
093         */
094        Mono<Void> close(CloseStatus status);
095
096
097        // WebSocketMessage factory methods
098
099        /**
100         * Factory method to create a text {@link WebSocketMessage} using the
101         * {@link #bufferFactory()} for the session.
102         */
103        WebSocketMessage textMessage(String payload);
104
105        /**
106         * Factory method to create a binary WebSocketMessage using the
107         * {@link #bufferFactory()} for the session.
108         */
109        WebSocketMessage binaryMessage(Function<DataBufferFactory, DataBuffer> payloadFactory);
110
111        /**
112         * Factory method to create a ping WebSocketMessage using the
113         * {@link #bufferFactory()} for the session.
114         */
115        WebSocketMessage pingMessage(Function<DataBufferFactory, DataBuffer> payloadFactory);
116
117        /**
118         * Factory method to create a pong WebSocketMessage using the
119         * {@link #bufferFactory()} for the session.
120         */
121        WebSocketMessage pongMessage(Function<DataBufferFactory, DataBuffer> payloadFactory);
122
123}