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.camel.spi;
018
019 import java.util.EventObject;
020 import java.util.List;
021
022 import org.apache.camel.CamelContextAware;
023 import org.apache.camel.Exchange;
024 import org.apache.camel.Processor;
025 import org.apache.camel.Service;
026 import org.apache.camel.model.ProcessorDefinition;
027
028 /**
029 * A debugger which allows tooling to attach breakpoints which is is being invoked
030 * when {@link Exchange}s is being routed.
031 *
032 * @version
033 */
034 public interface Debugger extends Service, CamelContextAware {
035
036 /**
037 * Add the given breakpoint
038 *
039 * @param breakpoint the breakpoint
040 */
041 void addBreakpoint(Breakpoint breakpoint);
042
043 /**
044 * Add the given breakpoint
045 *
046 * @param breakpoint the breakpoint
047 * @param conditions a number of {@link org.apache.camel.spi.Condition}s
048 */
049 void addBreakpoint(Breakpoint breakpoint, Condition... conditions);
050
051 /**
052 * Add the given breakpoint which will be used in single step mode
053 * <p/>
054 * The debugger will single step the first message arriving.
055 *
056 * @param breakpoint the breakpoint
057 */
058 void addSingleStepBreakpoint(Breakpoint breakpoint);
059
060 /**
061 * Add the given breakpoint which will be used in single step mode
062 * <p/>
063 * The debugger will single step the first message arriving.
064 *
065 * @param breakpoint the breakpoint
066 * @param conditions a number of {@link org.apache.camel.spi.Condition}s
067 */
068 void addSingleStepBreakpoint(Breakpoint breakpoint, Condition... conditions);
069
070 /**
071 * Removes the given breakpoint
072 *
073 * @param breakpoint the breakpoint
074 */
075 void removeBreakpoint(Breakpoint breakpoint);
076
077 /**
078 * Suspends all breakpoints.
079 */
080 void suspendAllBreakpoints();
081
082 /**
083 * Activate all breakpoints.
084 */
085 void activateAllBreakpoints();
086
087 /**
088 * Gets a list of all the breakpoints
089 *
090 * @return the breakpoints wrapped in an unmodifiable list, is never <tt>null</tt>.
091 */
092 List<Breakpoint> getBreakpoints();
093
094 /**
095 * Starts the single step debug mode for the given exchange
096 *
097 * @param exchangeId the exchange id
098 * @param breakpoint the breakpoint
099 * @return <tt>true</tt> if the debugger will single step the given exchange, <tt>false</tt> if the debugger is already
100 * single stepping another, and thus cannot simultaneously single step another exchange
101 */
102 boolean startSingleStepExchange(String exchangeId, Breakpoint breakpoint);
103
104 /**
105 * Stops the single step debug mode for the given exchange.
106 * <p/>
107 * <b>Notice:</b> The default implementation of the debugger is capable of auto stopping when the exchange is complete.
108 *
109 * @param exchangeId the exchange id
110 */
111 void stopSingleStepExchange(String exchangeId);
112
113 /**
114 * Callback invoked when an {@link Exchange} is about to be processed which allows implementators
115 * to notify breakpoints.
116 *
117 * @param exchange the exchange
118 * @param processor the {@link Processor} about to be processed
119 * @param definition the definition of the processor
120 * @return <tt>true</tt> if any breakpoint was hit, <tt>false</tt> if not breakpoint was hit
121 */
122 boolean beforeProcess(Exchange exchange, Processor processor, ProcessorDefinition<?> definition);
123
124 /**
125 * Callback invoked when an {@link Exchange} has been processed which allows implementators
126 * to notify breakpoints.
127 *
128 * @param exchange the exchange
129 * @param processor the {@link Processor} which was processed
130 * @param definition the definition of the processor
131 * @param timeTaken time in millis it took to process the {@link Exchange} - time spend in breakpoint callbacks may affect this time
132 * @return <tt>true</tt> if any breakpoint was hit, <tt>false</tt> if not breakpoint was hit
133 */
134 boolean afterProcess(Exchange exchange, Processor processor, ProcessorDefinition<?> definition, long timeTaken);
135
136 /**
137 * Callback invoked when an {@link Exchange} is being processed which allows implementators
138 * to notify breakpoints.
139 *
140 * @param exchange the exchange
141 * @param event the event (instance of {@link org.apache.camel.management.event.AbstractExchangeEvent}
142 * @return <tt>true</tt> if any breakpoint was hit, <tt>false</tt> if not breakpoint was hit
143 */
144 boolean onEvent(Exchange exchange, EventObject event);
145
146 }