/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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.apache.catalina.tribes;
import org.apache.catalina.tribes.group.InterceptorPayload;
/**
* A ChannelInterceptor is an interceptor that intercepts messages and membership messages in the channel stack. This
* allows interceptors to modify the message or perform other actions when a message is sent or received.
* <p>
* Interceptors are tied together in a linked list.
*
* @see org.apache.catalina.tribes.group.ChannelInterceptorBase
*/
public interface ChannelInterceptor extends MembershipListener, Heartbeat {
/**
* An interceptor can react to a message based on a set bit on the message options. When a message is sent, the
* options can be retrieved from ChannelMessage.getOptions() and if the bit is set, this interceptor will react to
* it.
* <p>
* A simple evaluation if an interceptor should react to the message would be: <br>
* <code>boolean react = (getOptionFlag() == (getOptionFlag() & ChannelMessage.getOptions()));</code> <br>
* The default option is 0, meaning there is no way for the application to trigger the interceptor. The interceptor
* itself will decide.
*
* @return int
*
* @see ChannelMessage#getOptions()
*/
int getOptionFlag();
/**
* Sets the option flag
*
* @param flag int
*
* @see #getOptionFlag()
*/
void setOptionFlag(int flag);
/**
* Set the next interceptor in the list of interceptors
*
* @param next ChannelInterceptor
*/
void setNext(ChannelInterceptor next);
/**
* Retrieve the next interceptor in the list
*
* @return ChannelInterceptor - returns the next interceptor in the list or null if no more interceptors exist
*/
ChannelInterceptor getNext();
/**
* Set the previous interceptor in the list
*
* @param previous ChannelInterceptor
*/
void setPrevious(ChannelInterceptor previous);
/**
* Retrieve the previous interceptor in the list
*
* @return ChannelInterceptor - returns the previous interceptor in the list or null if no more interceptors exist
*/
ChannelInterceptor getPrevious();
/**
* The <code>sendMessage</code> method is called when a message is being sent to one more destinations. The
* interceptor can modify any of the parameters and then pass on the message down the stack by invoking
* <code>getNext().sendMessage(destination,msg,payload)</code>.
* <p>
* Alternatively the interceptor can stop the message from being sent by not invoking
* <code>getNext().sendMessage(destination,msg,payload)</code>.
* <p>
* If the message is to be sent asynchronous the application can be notified of completion and errors by passing in
* an error handler attached to a payload object.
* <p>
* The ChannelMessage.getAddress contains Channel.getLocalMember, and can be overwritten to simulate a message sent
* from another node.
*
* @param destination Member[] - the destination for this message
* @param msg ChannelMessage - the message to be sent
* @param payload InterceptorPayload - the payload, carrying an error handler and future useful data, can be
* null
*
* @throws ChannelException if a serialization error happens.
*
* @see ErrorHandler
* @see InterceptorPayload
*/
void sendMessage(Member[] destination, ChannelMessage msg, InterceptorPayload payload) throws ChannelException;
/**
* The <code>messageReceived</code> is invoked when a message is received. <code>ChannelMessage.getAddress()</code>
* is the sender, or the reply-to address if it has been overwritten.
*
* @param data ChannelMessage
*/
void messageReceived(ChannelMessage data);
/**
* The <code>heartbeat()</code> method gets invoked periodically to allow interceptors to clean up resources, time
* out object and perform actions that are unrelated to sending/receiving data.
*/
@Override
void heartbeat();
/**
* Intercepts the <code>Channel.hasMembers()</code> method
*
* @return boolean - if the channel has members in its membership group
*
* @see Channel#hasMembers()
*/
boolean hasMembers();
/**
* Intercepts the <code>Channel.getMembers()</code> method
*
* @return the members
*
* @see Channel#getMembers()
*/
Member[] getMembers();
/**
* Intercepts the <code>Channel.getLocalMember(boolean)</code> method
*
* @param incAliveTime boolean
*
* @return the member that represents this node
*
* @see Channel#getLocalMember(boolean)
*/
Member getLocalMember(boolean incAliveTime);
/**
* Intercepts the <code>Channel.getMember(Member)</code> method
*
* @param mbr Member
*
* @return Member - the actual member information, including stay alive
*
* @see Channel#getMember(Member)
*/
Member getMember(Member mbr);
/**
* Starts up the channel. This can be called multiple times for individual services to start The svc parameter can
* be the logical or value of any constants
*
* @param svc one of:
* <ul>
* <li>Channel.DEFAULT - will start all services</li>
* <li>Channel.MBR_RX_SEQ - starts the membership receiver</li>
* <li>Channel.MBR_TX_SEQ - starts the membership broadcaster</li>
* <li>Channel.SND_TX_SEQ - starts the replication transmitter</li>
* <li>Channel.SND_RX_SEQ - starts the replication receiver</li>
* </ul>
*
* @throws ChannelException if a startup error occurs or the service is already started.
*
* @see Channel
*/
void start(int svc) throws ChannelException;
/**
* Shuts down the channel. This can be called multiple times for individual services to shut down. The svc parameter
* can be the logical or value of any constants
*
* @param svc one of:
* <ul>
* <li>Channel.DEFAULT - will shut down all services</li>
* <li>Channel.MBR_RX_SEQ - stops the membership receiver</li>
* <li>Channel.MBR_TX_SEQ - stops the membership broadcaster</li>
* <li>Channel.SND_TX_SEQ - stops the replication transmitter</li>
* <li>Channel.SND_RX_SEQ - stops the replication receiver</li>
* </ul>
*
* @throws ChannelException if a startup error occurs or the service is already started.
*
* @see Channel
*/
void stop(int svc) throws ChannelException;
/**
* Fire an event.
*
* @param event the event
*/
void fireInterceptorEvent(InterceptorEvent event);
/**
* Return the channel that is related to this interceptor
*
* @return Channel
*/
Channel getChannel();
/**
* Set the channel that is related to this interceptor
*
* @param channel The channel
*/
void setChannel(Channel channel);
interface InterceptorEvent {
int getEventType();
String getEventTypeDesc();
ChannelInterceptor getInterceptor();
}
}