/*
 *  Copyright (c) 2011-2015 The original author or authors
 *  ------------------------------------------------------
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  and Apache License v2.0 which accompanies this distribution.
 *
 *       The Eclipse Public License is available at
 *       http://www.eclipse.org/legal/epl-v10.html
 *
 *       The Apache License v2.0 is available at
 *       http://www.opensource.org/licenses/apache2.0.php
 *
 *  You may elect to redistribute this code under either of these licenses.
 */

package io.vertx.ext.stomp;

import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.AsyncResult;
import io.vertx.core.Future;
import io.vertx.core.Handler;
import io.vertx.core.Vertx;
import io.vertx.ext.auth.User;
import io.vertx.ext.auth.authentication.AuthenticationProvider;
import io.vertx.ext.stomp.impl.DefaultStompHandler;

import java.util.List;

STOMP server handler implements the behavior of the STOMP server when a specific event occurs. For instance, if let customize the behavior when specific STOMP frames arrives or when a connection is closed. This class has been designed to let you customize the server behavior. The default implementation is compliant with the STOMP specification. In this default implementation, not acknowledge frames are dropped.
Author:Clement Escoffier
/** * STOMP server handler implements the behavior of the STOMP server when a specific event occurs. For instance, if * let customize the behavior when specific STOMP frames arrives or when a connection is closed. This class has been * designed to let you customize the server behavior. The default implementation is compliant with the STOMP * specification. In this default implementation, not acknowledge frames are dropped. * * @author <a href="http://escoffier.me">Clement Escoffier</a> */
@VertxGen public interface StompServerHandler extends Handler<ServerFrame> {
Creates an instance of StompServerHandler using the default (compliant) implementation.
Params:
  • vertx – the vert.x instance to use
Returns:the created StompServerHandler
/** * Creates an instance of {@link StompServerHandler} using the default (compliant) implementation. * * @param vertx the vert.x instance to use * @return the created {@link StompServerHandler} */
static StompServerHandler create(Vertx vertx) { return new DefaultStompHandler(vertx); }
Configures a handler that get notified when a STOMP frame is received by the server. This handler can be used for logging, debugging or ad-hoc behavior.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures a handler that get notified when a STOMP frame is received by the server. * This handler can be used for logging, debugging or ad-hoc behavior. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler receivedFrameHandler(Handler<ServerFrame> handler);
Configures the action to execute when a CONNECT frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code CONNECT} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler connectHandler(Handler<ServerFrame> handler);
Configures the action to execute when a STOMP frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code STOMP} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler stompHandler(Handler<ServerFrame> handler);
Configures the action to execute when a SUBSCRIBE frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code SUBSCRIBE} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler subscribeHandler(Handler<ServerFrame> handler);
Configures the action to execute when a UNSUBSCRIBE frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code UNSUBSCRIBE} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler unsubscribeHandler(Handler<ServerFrame> handler);
Configures the action to execute when a SEND frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code SEND} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler sendHandler(Handler<ServerFrame> handler);
Configures the action to execute when a connection with the client is closed.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a connection with the client is closed. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler closeHandler(Handler<StompServerConnection> handler);
Called when the connection is closed. This method executes a default behavior and must calls the configured closeHandler(Handler<StompServerConnection>) if any.
Params:
  • connection – the connection
/** * Called when the connection is closed. This method executes a default behavior and must calls the configured * {@link #closeHandler(Handler)} if any. * * @param connection the connection */
void onClose(StompServerConnection connection);
Configures the action to execute when a COMMIT frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code COMMIT} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler commitHandler(Handler<ServerFrame> handler);
Configures the action to execute when a ABORT frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code ABORT} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler abortHandler(Handler<ServerFrame> handler);
Configures the action to execute when a BEGIN frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code BEGIN} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler beginHandler(Handler<ServerFrame> handler);
Configures the action to execute when a DISCONNECT frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code DISCONNECT} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler disconnectHandler(Handler<ServerFrame> handler);
Configures the action to execute when a ACK frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code ACK} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler ackHandler(Handler<ServerFrame> handler);
Configures the action to execute when a NACK frame is received.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the action to execute when a {@code NACK} frame is received. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler nackHandler(Handler<ServerFrame> handler);
Called when the client connects to a server requiring authentication. It invokes the AuthenticationProvider configured using authProvider(AuthenticationProvider).
Params:
  • connection – server connection that contains session ID
  • login – the login
  • passcode – the password
  • handler – handler receiving the authentication result
Returns:the current StompServerHandler
/** * Called when the client connects to a server requiring authentication. It invokes the {@link AuthenticationProvider} configured * using {@link #authProvider(AuthenticationProvider)}. * * @param connection server connection that contains session ID * @param login the login * @param passcode the password * @param handler handler receiving the authentication result * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler onAuthenticationRequest(StompServerConnection connection, String login, String passcode, Handler<AsyncResult<Boolean>> handler); /** * Like {@link StompServerHandler#onAuthenticationRequest(StompServerConnection, String, String, Handler)} but with a future of the result */ Future<Boolean> onAuthenticationRequest(StompServerConnection connection, String login, String passcode);
Provides for authorization matches on a destination level, this will return the User created by the AuthenticationProvider.
Params:
  • session – session ID for the server connection.
Returns:null if not authenticated.
/** * Provides for authorization matches on a destination level, this will return the User created by the {@link AuthenticationProvider}. * * @param session session ID for the server connection. * @return null if not authenticated. */
User getUserBySession(String session);
Configures the AuthenticationProvider to be used to authenticate the user.
Params:
  • handler – the handler
Returns:the current StompServerHandler
/** * Configures the {@link AuthenticationProvider} to be used to authenticate the user. * * @param handler the handler * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler authProvider(AuthenticationProvider handler);
Returns:the list of destination managed by the STOMP server. Don't forget the STOMP interprets destination as opaque Strings.
/** * @return the list of destination managed by the STOMP server. Don't forget the STOMP interprets destination as * opaque Strings. */
List<Destination> getDestinations();
Gets the destination with the given name.
Params:
  • destination – the destination
Returns:the Destination, null if not existing.
/** * Gets the destination with the given name. * * @param destination the destination * @return the {@link Destination}, {@code null} if not existing. */
Destination getDestination(String destination);
Method called by single message (client-individual policy) or a set of message (client policy) are acknowledged. Implementations must call the handler configured using onAckHandler(Handler<Acknowledgement>).
Params:
  • connection – the connection
  • subscribe – the SUBSCRIBE frame
  • messages – the acknowledge messages
Returns:the current StompServerHandler
/** * Method called by single message (client-individual policy) or a set of message (client policy) are acknowledged. * Implementations must call the handler configured using {@link #onAckHandler(Handler)}. * * @param connection the connection * @param subscribe the {@code SUBSCRIBE} frame * @param messages the acknowledge messages * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler onAck(StompServerConnection connection, Frame subscribe, List<Frame> messages);
Method called by single message (client-individual policy) or a set of message (client policy) are not acknowledged. Not acknowledgment can result from a NACK frame or from a timeout (no ACK frame received in a given time. Implementations must call the handler configured using onNackHandler(Handler<Acknowledgement>).
Params:
  • connection – the connection
  • subscribe – the SUBSCRIBE frame
  • messages – the acknowledge messages
Returns:the current StompServerHandler
/** * Method called by single message (client-individual policy) or a set of message (client policy) are * <strong>not</strong> acknowledged. Not acknowledgment can result from a {@code NACK} frame or from a timeout (no * {@code ACK} frame received in a given time. Implementations must call the handler configured using * {@link #onNackHandler(Handler)}. * * @param connection the connection * @param subscribe the {@code SUBSCRIBE} frame * @param messages the acknowledge messages * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler onNack(StompServerConnection connection, Frame subscribe, List<Frame> messages);
Configures the action to execute when messages are acknowledged.
Params:
  • handler – the handler
See Also:
Returns:the current StompServerHandler
/** * Configures the action to execute when messages are acknowledged. * * @param handler the handler * @return the current {@link StompServerHandler} * @see #onAck(StompServerConnection, Frame, List) */
@Fluent StompServerHandler onAckHandler(Handler<Acknowledgement> handler);
Configures the action to execute when messages are not acknowledged.
Params:
  • handler – the handler
See Also:
Returns:the current StompServerHandler
/** * Configures the action to execute when messages are <strong>not</strong> acknowledged. * * @param handler the handler * @return the current {@link StompServerHandler} * @see #onNack(StompServerConnection, Frame, List) */
@Fluent StompServerHandler onNackHandler(Handler<Acknowledgement> handler);
Allows customizing the action to do when the server needs to send a `PING` to the client. By default it send a frame containing EOL (specification). However, you can customize this and send another frame. However, be aware that this may requires a custom client.

The handler will only be called if the connection supports heartbeats.
Params:
  • handler – the action to execute when a `PING` needs to be sent.
Returns:the current StompServerHandler
/** * Allows customizing the action to do when the server needs to send a `PING` to the client. By default it send a * frame containing {@code EOL} (specification). However, you can customize this and send another frame. However, * be aware that this may requires a custom client. * <p/> * The handler will only be called if the connection supports heartbeats. * * @param handler the action to execute when a `PING` needs to be sent. * @return the current {@link StompServerHandler} */
@Fluent StompServerHandler pingHandler(Handler<StompServerConnection> handler);
Gets a Destination object if existing, or create a new one. The creation is delegated to the DestinationFactory.
Params:
  • destination – the destination
Returns:the Destination instance, may have been created.
/** * Gets a {@link Destination} object if existing, or create a new one. The creation is delegated to the * {@link DestinationFactory}. * * @param destination the destination * @return the {@link Destination} instance, may have been created. */
Destination getOrCreateDestination(String destination);
Configures the DestinationFactory used to create Destination objects.
Params:
  • factory – the factory
Returns:the current StompServerHandler.
/** * Configures the {@link DestinationFactory} used to create {@link Destination} objects. * * @param factory the factory * @return the current {@link StompServerHandler}. */
@Fluent StompServerHandler destinationFactory(DestinationFactory factory);
Configures the STOMP server to act as a bridge with the Vert.x event bus.
Params:
  • options – the configuration options
See Also:
Returns:the current StompServerHandler.
/** * Configures the STOMP server to act as a bridge with the Vert.x event bus. * * @param options the configuration options * @return the current {@link StompServerHandler}. * @see Vertx#eventBus() */
@Fluent StompServerHandler bridge(BridgeOptions options); }