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}