Java tutorial
/* * Copyright 2002-2019 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.springframework.messaging.simp.stomp; import org.springframework.lang.Nullable; /** * Represents a STOMP session with operations to send messages, * create subscriptions and receive messages on those subscriptions. * * @author Rossen Stoyanchev * @since 4.2 */ public interface StompSession { /** * Return the id for the session. */ String getSessionId(); /** * Whether the session is connected. */ boolean isConnected(); /** * When enabled, a receipt header is automatically added to future * {@code send} and {@code subscribe} operations on this session, which * causes the server to return a RECEIPT. An application can then use * the {@link StompSession.Receiptable Receiptable} returned from the * operation to track the receipt. * <p>A receipt header can also be added manually through the overloaded * methods that accept {@code StompHeaders}. */ void setAutoReceipt(boolean enabled); /** * Send a message to the specified destination, converting the payload to a * {@code byte[]} with the help of a * {@link org.springframework.messaging.converter.MessageConverter MessageConverter}. * @param destination the destination to send a message to * @param payload the message payload * @return a Receiptable for tracking receipts */ Receiptable send(String destination, Object payload); /** * An overloaded version of {@link #send(String, Object)} with full * {@link StompHeaders} instead of just a destination. The headers must * contain a destination and may also have other headers such as * "content-type" or custom headers for the broker to propagate to * subscribers, or broker-specific, non-standard headers. * @param headers the message headers * @param payload the message payload * @return a Receiptable for tracking receipts */ Receiptable send(StompHeaders headers, Object payload); /** * Subscribe to the given destination by sending a SUBSCRIBE frame and handle * received messages with the specified {@link StompFrameHandler}. * @param destination the destination to subscribe to * @param handler the handler for received messages * @return a handle to use to unsubscribe and/or track receipts */ Subscription subscribe(String destination, StompFrameHandler handler); /** * An overloaded version of {@link #subscribe(String, StompFrameHandler)} * with full {@link StompHeaders} instead of just a destination. * @param headers the headers for the subscribe message frame * @param handler the handler for received messages * @return a handle to use to unsubscribe and/or track receipts */ Subscription subscribe(StompHeaders headers, StompFrameHandler handler); /** * Send an acknowledgement whether a message was consumed or not resulting * in an ACK or NACK frame respectively. * <p><strong>Note:</strong> to use this when subscribing you must set the * {@link StompHeaders#setAck(String) ack} header to "client" or * "client-individual" in order ot use this. * @param messageId the id of the message * @param consumed whether the message was consumed or not * @return a Receiptable for tracking receipts * @since 4.3 */ Receiptable acknowledge(String messageId, boolean consumed); /** * An overloaded version of {@link #acknowledge(String, boolean)} with * full {@link StompHeaders} instead of just a {@code messageId}. * @param headers the headers for the ACK or NACK message frame * @param consumed whether the message was consumed or not * @return a Receiptable for tracking receipts * @since 5.0.5 */ Receiptable acknowledge(StompHeaders headers, boolean consumed); /** * Disconnect the session by sending a DISCONNECT frame. */ void disconnect(); /** * A handle to use to track receipts. * @see #setAutoReceipt(boolean) */ interface Receiptable { /** * Return the receipt id, or {@code null} if the STOMP frame for which * the handle was returned did not have a "receipt" header. */ @Nullable String getReceiptId(); /** * Task to invoke when a receipt is received. * @throws java.lang.IllegalArgumentException if the receiptId is {@code null} */ void addReceiptTask(Runnable runnable); /** * Task to invoke when a receipt is not received in the configured time. * @throws java.lang.IllegalArgumentException if the receiptId is {@code null} * @see org.springframework.messaging.simp.stomp.StompClientSupport#setReceiptTimeLimit(long) */ void addReceiptLostTask(Runnable runnable); } /** * A handle to use to unsubscribe or to track a receipt. */ interface Subscription extends Receiptable { /** * Return the id for the subscription. */ @Nullable String getSubscriptionId(); /** * Return the headers used on the SUBSCRIBE frame. * @since 5.0 */ StompHeaders getSubscriptionHeaders(); /** * Remove the subscription by sending an UNSUBSCRIBE frame. */ void unsubscribe(); /** * Alternative to {@link #unsubscribe()} with additional custom headers * to send to the server. * <p><strong>Note:</strong> There is no need to set the subscription id. * @param headers the custom headers, if any * @since 5.0 */ void unsubscribe(@Nullable StompHeaders headers); } }