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 * <p/>
037 * <b>Important:</b> Implementations of this should use <tt>String</tt> as the generic type as that is
038 * what is required by Camel to allow using the idempotent repository with the Idempotent Consumer EIP
039 * and also as file consumer read-lock. It was a mistake to make {@link IdempotentRepository} parameterized,
040 * as it should have been a pre-configured to use a <tt>String</tt> type.
041 *
042 * @version 
043 */
044public interface ExchangeIdempotentRepository<E> extends IdempotentRepository<E> {
045
046    /**
047     * Adds the key to the repository.
048     * <p/>
049     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
050     *
051     * @param key the key of the message for duplicate test
052     * @return <tt>true</tt> if this repository did <b>not</b> already contain the specified element
053     */
054    boolean add(Exchange exchange, E key);
055
056    /**
057     * Returns <tt>true</tt> if this repository contains the specified element.
058     * <p/>
059     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
060     *
061     * @param key the key of the message
062     * @return <tt>true</tt> if this repository contains the specified element
063     */
064    boolean contains(Exchange exchange, E key);
065
066    /**
067     * Removes the key from the repository.
068     * <p/>
069     * Is usually invoked if the exchange failed.
070     * <p/>
071     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
072     *
073     * @param key the key of the message for duplicate test
074     * @return <tt>true</tt> if the key was removed
075     */
076    boolean remove(Exchange exchange, E key);
077
078    /**
079     * Confirms the key, after the exchange has been processed successfully.
080     * <p/>
081     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
082     *
083     * @param key the key of the message for duplicate test
084     * @return <tt>true</tt> if the key was confirmed
085     */
086    boolean confirm(Exchange exchange, E key);
087
088}