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 org.apache.camel.Exchange;
020
021/**
022 * Access to a repository of Message IDs to implement the
023 * <a href="http://camel.apache.org/idempotent-consumer.html">Idempotent Consumer</a> pattern.
024 * <p/>
025 * The <tt>add</tt> and <tt>contains</tt> methods is operating according to the {@link java.util.Set} contract.
026 * <p/>
027 * The repository supports eager (default) and non-eager mode.
028 * <ul>
029 *     <li>eager: calls <tt>add</tt> and <tt>confirm</tt> if complete, or <tt>remove</tt> if failed</li>
030 *     <li>non-eager: calls <tt>contains</tt> and <tt>add</tt> if complete, or <tt>remove</tt> if failed</li>
031 * </ul>
032 * Notice the remove callback, can be configured to be disabled.
033 * <p/>
034 * This repository supports the operations to pass in the current exchange, which can be needed by some implementations
035 * such as the JPA idempotent consumer.
036 *
037 * @version 
038 */
039public interface ExchangeIdempotentRepository<E> extends IdempotentRepository<E> {
040
041    /**
042     * Adds the key to the repository.
043     * <p/>
044     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
045     *
046     * @param key the key of the message for duplicate test
047     * @return <tt>true</tt> if this repository did <b>not</b> already contain the specified element
048     */
049    boolean add(Exchange exchange, E key);
050
051    /**
052     * Returns <tt>true</tt> if this repository contains the specified element.
053     * <p/>
054     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
055     *
056     * @param key the key of the message
057     * @return <tt>true</tt> if this repository contains the specified element
058     */
059    boolean contains(Exchange exchange, E key);
060
061    /**
062     * Removes the key from the repository.
063     * <p/>
064     * Is usually invoked if the exchange failed.
065     * <p/>
066     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
067     *
068     * @param key the key of the message for duplicate test
069     * @return <tt>true</tt> if the key was removed
070     */
071    boolean remove(Exchange exchange, E key);
072
073    /**
074     * Confirms the key, after the exchange has been processed successfully.
075     * <p/>
076     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
077     *
078     * @param key the key of the message for duplicate test
079     * @return <tt>true</tt> if the key was confirmed
080     */
081    boolean confirm(Exchange exchange, E key);
082
083}