org.cometd.bayeux.client.ClientSession Maven / Gradle / Ivy
/*
* Copyright (c) 2008-2022 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
*
* http://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.cometd.bayeux.client;
import java.util.List;
import java.util.Map;
import org.cometd.bayeux.Bayeux;
import org.cometd.bayeux.Message;
import org.cometd.bayeux.Promise;
import org.cometd.bayeux.Session;
/**
* This interface represents the client side Bayeux session.
* In addition to the {@link Session common Bayeux session}, this
* interface provides method to configure extension, access channels
* and to initiate the communication with a Bayeux server(s).
*/
public interface ClientSession extends Session {
/**
* Adds an extension to this session.
*
* @param extension the extension to add
* @see #removeExtension(Extension)
*/
void addExtension(Extension extension);
/**
* Removes an extension from this session.
*
* @param extension the extension to remove
* @see #addExtension(Extension)
*/
void removeExtension(Extension extension);
/**
* @return an immutable list of extensions present in this ClientSession instance
* @see #addExtension(Extension)
*/
List getExtensions();
/**
* Equivalent to {@link #handshake(Map) handshake(null)}.
*/
default void handshake() {
handshake(null);
}
/**
* Equivalent to {@link #handshake(Map, ClientSession.MessageListener) handshake(template, null)}.
*
* @param template additional fields to add to the handshake message.
*/
default void handshake(Map template) {
handshake(template, MessageListener.NOOP);
}
/**
* Initiates the bayeux protocol handshake with the server(s).
* The handshake initiated by this method is asynchronous and
* does not wait for the handshake response.
*
* @param template additional fields to add to the handshake message.
* @param callback the message listener to notify of the handshake result
*/
void handshake(Map template, MessageListener callback);
@Override
default void disconnect() {
disconnect(MessageListener.NOOP);
}
/**
* Disconnects this session, ending the link between the client and the server peers.
*
* @param callback the message listener to notify of the disconnect result
*/
void disconnect(MessageListener callback);
/**
* Returns a client side channel scoped by this session.
* The channel name may be for a specific channel (e.g. "/foo/bar")
* or for a wild channel (e.g. "/meta/**" or "/foo/*").
* This method will always return a channel, even if the
* the channel has not been created on the server side. The server
* side channel is only involved once a publish or subscribe method
* is called on the channel returned by this method.
* Typical usage examples are:
*
* clientSession.getChannel("/foo/bar").subscribe(mySubscriptionListener);
* clientSession.getChannel("/foo/bar").publish("Hello");
* clientSession.getChannel("/meta/*").addListener(myMetaChannelListener);
*
*
* @param channelName specific or wild channel name.
* @return a channel scoped by this session.
*/
ClientSessionChannel getChannel(String channelName);
/**
* Performs a remote call to the server, to the specified {@code target},
* and with the given {@code data} as payload.
* The remote call response will be delivered via the {@code callback}
* parameter.
* Typical usage:
*
* clientSession.remoteCall("getOnlineStatus", userId, new MessageListener()
* {
* @Override
* public void onMessage(Message message)
* {
* if (message.isSuccessful())
* {
* String status = (String)message.getData();
* // Update UI with online status.
* }
* else
* {
* // Remote call failed.
* }
* }
* });
*
*
* @param target the remote call target
* @param data the remote call parameters
* @param callback the listener that receives the remote call response
*/
void remoteCall(String target, Object data, MessageListener callback);
/**
* A listener for remote call messages.
*
* @see #remoteCall(String, Object, MessageListener)
*/
public interface MessageListener extends Bayeux.BayeuxListener {
public static final MessageListener NOOP = message -> {
};
/**
* Callback invoked when a remote call response is received.
*
* @param message the remote call response
*/
void onMessage(Message message);
}
/**
* Extension API for client session.
* An extension allows user code to interact with the Bayeux protocol as late
* as messages are sent or as soon as messages are received.
* Messages may be modified, or state held, so that the extension adds a
* specific behavior simply by observing the flow of Bayeux messages.
*
* @see ClientSession#addExtension(Extension)
*/
public interface Extension {
/**
* Callback method invoked every time a message is incoming.
*
* @param session the session that sent the message
* @param message the incoming message
* @param promise the promise to notify whether message processing should continue
*/
default void incoming(ClientSession session, Message.Mutable message, Promise promise) {
promise.succeed(message.isMeta() ? rcvMeta(session, message) : rcv(session, message));
}
/**
* Callback method invoked every time a normal message is received.
*
* @param session the session object that is receiving the message
* @param message the message received
* @return true if message processing should continue, false if it should stop
*/
default boolean rcv(ClientSession session, Message.Mutable message) {
return true;
}
/**
* Callback method invoked every time a meta message is received.
*
* @param session the session object that is receiving the meta message
* @param message the meta message received
* @return true if message processing should continue, false if it should stop
*/
default boolean rcvMeta(ClientSession session, Message.Mutable message) {
return true;
}
/**
* Callback method invoked every time a message is outgoing.
*
* @param session the session that sent the message
* @param message the outgoing message
* @param promise the promise to notify whether message processing should continue
*/
default void outgoing(ClientSession session, Message.Mutable message, Promise promise) {
promise.succeed(message.isMeta() ? sendMeta(session, message) : send(session, message));
}
/**
* Callback method invoked every time a normal message is being sent.
*
* @param session the session object that is sending the message
* @param message the message being sent
* @return true if message processing should continue, false if it should stop
*/
default boolean send(ClientSession session, Message.Mutable message) {
return true;
}
/**
* Callback method invoked every time a meta message is being sent.
*
* @param session the session object that is sending the message
* @param message the meta message being sent
* @return true if message processing should continue, false if it should stop
*/
default boolean sendMeta(ClientSession session, Message.Mutable message) {
return true;
}
}
}