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.EventObject; 020import java.util.List; 021 022import org.apache.camel.CamelContextAware; 023import org.apache.camel.Exchange; 024import org.apache.camel.Processor; 025import org.apache.camel.Service; 026import 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 */ 034public 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}