org.cometd.bayeux.client.ClientSession Maven / Gradle / Ivy
/*
* Copyright (c) 2010 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.Map;
import org.cometd.bayeux.Message;
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);
/**
* Equivalent to {@link #handshake(Map) handshake(null)}.
*/
void handshake();
/**
* 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.
*/
void handshake(Map template);
/**
* 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);
/**
* 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 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
*/
boolean rcv(ClientSession session, Message.Mutable message);
/**
* 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
*/
boolean rcvMeta(ClientSession session, Message.Mutable 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
*/
boolean send(ClientSession session, Message.Mutable message);
/**
* 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
*/
boolean sendMeta(ClientSession session, Message.Mutable message);
}
}