001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.catalina.tribes;
018:
019: import org.apache.catalina.tribes.group.InterceptorPayload;
020:
021: /**
022: * A ChannelInterceptor is an interceptor that intercepts
023: * messages and membership messages in the channel stack.
024: * This allows interceptors to modify the message or perform
025: * other actions when a message is sent or received.<br>
026: * Interceptors are tied together in a linked list.
027: * @see org.apache.catalina.tribes.group.ChannelInterceptorBase
028: * @author Filip Hanik
029: * @version $Revision: 467222 $, $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
030: */
031:
032: public interface ChannelInterceptor extends MembershipListener,
033: Heartbeat {
034:
035: /**
036: * An interceptor can react to a message based on a set bit on the
037: * message options. <br>
038: * When a message is sent, the options can be retrieved from ChannelMessage.getOptions()
039: * and if the bit is set, this interceptor will react to it.<br>
040: * A simple evaluation if an interceptor should react to the message would be:<br>
041: * <code>boolean react = (getOptionFlag() == (getOptionFlag() & ChannelMessage.getOptions()));</code><br>
042: * The default option is 0, meaning there is no way for the application to trigger the
043: * interceptor. The interceptor itself will decide.<br>
044: * @return int
045: * @see ChannelMessage#getOptions()
046: */
047: public int getOptionFlag();
048:
049: /**
050: * Sets the option flag
051: * @param flag int
052: * @see #getOptionFlag()
053: */
054: public void setOptionFlag(int flag);
055:
056: /**
057: * Set the next interceptor in the list of interceptors
058: * @param next ChannelInterceptor
059: */
060: public void setNext(ChannelInterceptor next);
061:
062: /**
063: * Retrieve the next interceptor in the list
064: * @return ChannelInterceptor - returns the next interceptor in the list or null if no more interceptors exist
065: */
066: public ChannelInterceptor getNext();
067:
068: /**
069: * Set the previous interceptor in the list
070: * @param previous ChannelInterceptor
071: */
072: public void setPrevious(ChannelInterceptor previous);
073:
074: /**
075: * Retrieve the previous interceptor in the list
076: * @return ChannelInterceptor - returns the previous interceptor in the list or null if no more interceptors exist
077: */
078: public ChannelInterceptor getPrevious();
079:
080: /**
081: * The <code>sendMessage</code> method is called when a message is being sent to one more destinations.
082: * The interceptor can modify any of the parameters and then pass on the message down the stack by
083: * invoking <code>getNext().sendMessage(destination,msg,payload)</code><br>
084: * Alternatively the interceptor can stop the message from being sent by not invoking
085: * <code>getNext().sendMessage(destination,msg,payload)</code><br>
086: * If the message is to be sent asynchronous the application can be notified of completion and
087: * errors by passing in an error handler attached to a payload object.<br>
088: * The ChannelMessage.getAddress contains Channel.getLocalMember, and can be overwritten
089: * to simulate a message sent from another node.<br>
090: * @param destination Member[] - the destination for this message
091: * @param msg ChannelMessage - the message to be sent
092: * @param payload InterceptorPayload - the payload, carrying an error handler and future useful data, can be null
093: * @throws ChannelException
094: * @see ErrorHandler
095: * @see InterceptorPayload
096: */
097: public void sendMessage(Member[] destination, ChannelMessage msg,
098: InterceptorPayload payload) throws ChannelException;
099:
100: /**
101: * the <code>messageReceived</code> is invoked when a message is received.
102: * <code>ChannelMessage.getAddress()</code> is the sender, or the reply-to address
103: * if it has been overwritten.
104: * @param data ChannelMessage
105: */
106: public void messageReceived(ChannelMessage data);
107:
108: /**
109: * The <code>heartbeat()</code> method gets invoked periodically
110: * to allow interceptors to clean up resources, time out object and
111: * perform actions that are unrelated to sending/receiving data.
112: */
113: public void heartbeat();
114:
115: /**
116: * Intercepts the <code>Channel.hasMembers()</code> method
117: * @return boolean - if the channel has members in its membership group
118: * @see Channel#hasMembers()
119: */
120: public boolean hasMembers();
121:
122: /**
123: * Intercepts the code>Channel.getMembers()</code> method
124: * @return Member[]
125: * @see Channel#getMembers()
126: */
127: public Member[] getMembers();
128:
129: /**
130: * Intercepts the code>Channel.getLocalMember(boolean)</code> method
131: * @param incAliveTime boolean
132: * @return Member
133: * @see Channel#getLocalMember(boolean)
134: */
135: public Member getLocalMember(boolean incAliveTime);
136:
137: /**
138: * Intercepts the code>Channel.getMember(Member)</code> method
139: * @param mbr Member
140: * @return Member - the actual member information, including stay alive
141: * @see Channel#getMember(Member)
142: */
143: public Member getMember(Member mbr);
144:
145: /**
146: * Starts up the channel. This can be called multiple times for individual services to start
147: * The svc parameter can be the logical or value of any constants
148: * @param svc int value of <BR>
149: * Channel.DEFAULT - will start all services <BR>
150: * Channel.MBR_RX_SEQ - starts the membership receiver <BR>
151: * Channel.MBR_TX_SEQ - starts the membership broadcaster <BR>
152: * Channel.SND_TX_SEQ - starts the replication transmitter<BR>
153: * Channel.SND_RX_SEQ - starts the replication receiver<BR>
154: * @throws ChannelException if a startup error occurs or the service is already started.
155: * @see Channel
156: */
157: public void start(int svc) throws ChannelException;
158:
159: /**
160: * Shuts down the channel. This can be called multiple times for individual services to shutdown
161: * The svc parameter can be the logical or value of any constants
162: * @param svc int value of <BR>
163: * Channel.DEFAULT - will shutdown all services <BR>
164: * Channel.MBR_RX_SEQ - stops the membership receiver <BR>
165: * Channel.MBR_TX_SEQ - stops the membership broadcaster <BR>
166: * Channel.SND_TX_SEQ - stops the replication transmitter<BR>
167: * Channel.SND_RX_SEQ - stops the replication receiver<BR>
168: * @throws ChannelException if a startup error occurs or the service is already started.
169: * @see Channel
170: */
171: public void stop(int svc) throws ChannelException;
172:
173: public void fireInterceptorEvent(InterceptorEvent event);
174:
175: interface InterceptorEvent {
176: int getEventType();
177:
178: String getEventTypeDesc();
179:
180: ChannelInterceptor getInterceptor();
181: }
182:
183: }
|