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    
021    import org.apache.camel.Exchange;
022    import org.apache.camel.Processor;
023    import org.apache.camel.model.ProcessorDefinition;
024    
025    /**
026     * {@link org.apache.camel.spi.Breakpoint} are used by the {@link org.apache.camel.spi.Debugger} API.
027     * <p/>
028     * This allows you to register {@link org.apache.camel.spi.Breakpoint}s to the {@link org.apache.camel.spi.Debugger}
029     * and have those breakpoints activated when their {@link org.apache.camel.spi.Condition}s match.
030     * <p/>
031     * If any exceptions is thrown from the callback methods then the {@link org.apache.camel.spi.Debugger}
032     * will catch and log those at <tt>WARN</tt> level and continue. This ensures Camel can continue to route
033     * the message without having breakpoints causing issues.
034     *
035     * @version 
036     * @see org.apache.camel.spi.Debugger
037     * @see org.apache.camel.spi.Condition
038     */
039    public interface Breakpoint {
040    
041        enum State {
042            Active, Suspended
043        }
044    
045        /**
046         * Gets the state of this break
047         *
048         * @return the state
049         */
050        State getState();
051    
052        /**
053         * Suspend this breakpoint
054         */
055        void suspend();
056    
057        /**
058         * Activates this breakpoint
059         */
060        void activate();
061    
062        /**
063         * Callback invoked when the breakpoint was hit and the {@link Exchange} is about to be processed (before).
064         *
065         * @param exchange   the {@link Exchange}
066         * @param processor  the {@link Processor} about to be processed
067         * @param definition the {@link org.apache.camel.model.ProcessorDefinition} definition of the processor
068         */
069        void beforeProcess(Exchange exchange, Processor processor, ProcessorDefinition<?> definition);
070    
071        /**
072         * Callback invoked when the breakpoint was hit and the {@link Exchange} has been processed (after).
073         *
074         * @param exchange   the {@link Exchange}
075         * @param processor  the {@link Processor} which was processed
076         * @param definition the {@link org.apache.camel.model.ProcessorDefinition} definition of the processor
077         * @param timeTaken  time in millis it took to process the {@link Exchange} - time spend in breakpoint callbacks may affect this time
078         */
079        void afterProcess(Exchange exchange, Processor processor, ProcessorDefinition<?> definition, long timeTaken);
080    
081        /**
082         * Callback invoked when the breakpoint was hit and any of the {@link Exchange} {@link EventObject event}s occurred.
083         *
084         * @param exchange   the {@link Exchange}
085         * @param event      the event (instance of {@link org.apache.camel.management.event.AbstractExchangeEvent}
086         * @param definition the {@link org.apache.camel.model.ProcessorDefinition} definition of the last processor executed,
087         *                   may be <tt>null</tt> if not possible to resolve from tracing
088         * @see org.apache.camel.management.event.AbstractExchangeEvent
089         */
090        void onEvent(Exchange exchange, EventObject event, ProcessorDefinition<?> definition);
091    
092    }