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