001/* 002 * Copyright 2002-2019 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 */ 016 017package org.springframework.messaging.simp.stomp; 018 019/** 020 * Represents a STOMP session with operations to send messages, 021 * create subscriptions and receive messages on those subscriptions. 022 * 023 * @author Rossen Stoyanchev 024 * @since 4.2 025 */ 026public interface StompSession { 027 028 /** 029 * Return the id for the session. 030 */ 031 String getSessionId(); 032 033 /** 034 * Whether the session is connected. 035 */ 036 boolean isConnected(); 037 038 /** 039 * When enabled, a receipt header is automatically added to future 040 * {@code send} and {@code subscribe} operations on this session, which 041 * causes the server to return a RECEIPT. An application can then use 042 * the {@link StompSession.Receiptable Receiptable} returned from the 043 * operation to track the receipt. 044 * <p>A receipt header can also be added manually through the overloaded 045 * methods that accept {@code StompHeaders}. 046 */ 047 void setAutoReceipt(boolean enabled); 048 049 /** 050 * Send a message to the specified destination, converting the payload to a 051 * {@code byte[]} with the help of a 052 * {@link org.springframework.messaging.converter.MessageConverter MessageConverter}. 053 * @param destination the destination to send a message to 054 * @param payload the message payload 055 * @return a Receiptable for tracking receipts 056 */ 057 Receiptable send(String destination, Object payload); 058 059 /** 060 * An overloaded version of {@link #send(String, Object)} with full 061 * {@link StompHeaders} instead of just a destination. The headers must 062 * contain a destination and may also have other headers such as 063 * "content-type" or custom headers for the broker to propagate to 064 * subscribers, or broker-specific, non-standard headers. 065 * @param headers the message headers 066 * @param payload the message payload 067 * @return a Receiptable for tracking receipts 068 */ 069 Receiptable send(StompHeaders headers, Object payload); 070 071 /** 072 * Subscribe to the given destination by sending a SUBSCRIBE frame and handle 073 * received messages with the specified {@link StompFrameHandler}. 074 * @param destination the destination to subscribe to 075 * @param handler the handler for received messages 076 * @return a handle to use to unsubscribe and/or track receipts 077 */ 078 Subscription subscribe(String destination, StompFrameHandler handler); 079 080 /** 081 * An overloaded version of {@link #subscribe(String, StompFrameHandler)} 082 * with full {@link StompHeaders} instead of just a destination. 083 * @param headers the headers for the subscribe message frame 084 * @param handler the handler for received messages 085 * @return a handle to use to unsubscribe and/or track receipts 086 */ 087 Subscription subscribe(StompHeaders headers, StompFrameHandler handler); 088 089 /** 090 * Send an acknowledgement whether a message was consumed or not resulting 091 * in an ACK or NACK frame respectively. 092 * <p><strong>Note:</strong> to use this when subscribing you must set the 093 * {@link StompHeaders#setAck(String) ack} header to "client" or 094 * "client-individual" in order ot use this. 095 * @param messageId the id of the message 096 * @param consumed whether the message was consumed or not 097 * @return a Receiptable for tracking receipts 098 * @since 4.3 099 */ 100 Receiptable acknowledge(String messageId, boolean consumed); 101 102 /** 103 * Disconnect the session by sending a DISCONNECT frame. 104 */ 105 void disconnect(); 106 107 108 /** 109 * A handle to use to track receipts. 110 * @see #setAutoReceipt(boolean) 111 */ 112 interface Receiptable { 113 114 /** 115 * Return the receipt id, or {@code null} if the STOMP frame for which 116 * the handle was returned did not have a "receipt" header. 117 */ 118 String getReceiptId(); 119 120 /** 121 * Task to invoke when a receipt is received. 122 * @throws java.lang.IllegalArgumentException if the receiptId is {@code null} 123 */ 124 void addReceiptTask(Runnable runnable); 125 126 /** 127 * Task to invoke when a receipt is not received in the configured time. 128 * @throws java.lang.IllegalArgumentException if the receiptId is {@code null} 129 * @see org.springframework.messaging.simp.stomp.StompClientSupport#setReceiptTimeLimit(long) 130 */ 131 void addReceiptLostTask(Runnable runnable); 132 } 133 134 135 /** 136 * A handle to use to unsubscribe or to track a receipt. 137 */ 138 interface Subscription extends Receiptable { 139 140 /** 141 * Return the id for the subscription. 142 */ 143 String getSubscriptionId(); 144 145 /** 146 * Remove the subscription by sending an UNSUBSCRIBE frame. 147 */ 148 void unsubscribe(); 149 } 150 151}