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;
020
021import org.apache.camel.Exchange;
022import org.apache.camel.Processor;
023import 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 */
039public interface Breakpoint {
040
041    /**
042     * State of the breakpoint as either active or suspended.
043     */
044    enum State {
045        Active, Suspended
046    }
047
048    /**
049     * Gets the state of this break
050     *
051     * @return the state
052     */
053    State getState();
054
055    /**
056     * Suspend this breakpoint
057     */
058    void suspend();
059
060    /**
061     * Activates this breakpoint
062     */
063    void activate();
064
065    /**
066     * Callback invoked when the breakpoint was hit and the {@link Exchange} is about to be processed (before).
067     *
068     * @param exchange   the {@link Exchange}
069     * @param processor  the {@link Processor} about to be processed
070     * @param definition the {@link org.apache.camel.model.ProcessorDefinition} definition of the processor
071     */
072    void beforeProcess(Exchange exchange, Processor processor, ProcessorDefinition<?> definition);
073
074    /**
075     * Callback invoked when the breakpoint was hit and the {@link Exchange} has been processed (after).
076     *
077     * @param exchange   the {@link Exchange}
078     * @param processor  the {@link Processor} which was processed
079     * @param definition the {@link org.apache.camel.model.ProcessorDefinition} definition of the processor
080     * @param timeTaken  time in millis it took to process the {@link Exchange} - time spend in breakpoint callbacks may affect this time
081     */
082    void afterProcess(Exchange exchange, Processor processor, ProcessorDefinition<?> definition, long timeTaken);
083
084    /**
085     * Callback invoked when the breakpoint was hit and any of the {@link Exchange} {@link EventObject event}s occurred.
086     *
087     * @param exchange   the {@link Exchange}
088     * @param event      the event (instance of {@link org.apache.camel.management.event.AbstractExchangeEvent}
089     * @param definition the {@link org.apache.camel.model.ProcessorDefinition} definition of the last processor executed,
090     *                   may be <tt>null</tt> if not possible to resolve from tracing
091     * @see org.apache.camel.management.event.AbstractExchangeEvent
092     */
093    void onEvent(Exchange exchange, EventObject event, ProcessorDefinition<?> definition);
094
095}