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.Service;
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 * Implementations for the <a href="http://camel.apache.org/idempotent-consumer.html">idempotent consumer EIP</a>
035 * should favor using {@link org.apache.camel.spi.ExchangeIdempotentRepository} instead.
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 * @see org.apache.camel.spi.ExchangeIdempotentRepository
044 */
045public interface IdempotentRepository<E> extends Service {
046
047    /**
048     * Adds the key to the repository.
049     * <p/>
050     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
051     *
052     * @param key the key of the message for duplicate test
053     * @return <tt>true</tt> if this repository did <b>not</b> already contain the specified element
054     */
055    boolean add(E key);
056
057    /**
058     * Returns <tt>true</tt> if this repository contains the specified element.
059     * <p/>
060     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
061     *
062     * @param key the key of the message
063     * @return <tt>true</tt> if this repository contains the specified element
064     */
065    boolean contains(E key);
066
067    /**
068     * Removes the key from the repository.
069     * <p/>
070     * Is usually invoked if the exchange failed.
071     * <p/>
072     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
073     *
074     * @param key the key of the message for duplicate test
075     * @return <tt>true</tt> if the key was removed
076     */
077    boolean remove(E key);
078
079    /**
080     * Confirms the key, after the exchange has been processed successfully.
081     * <p/>
082     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
083     *
084     * @param key the key of the message for duplicate test
085     * @return <tt>true</tt> if the key was confirmed
086     */
087    boolean confirm(E key);
088    
089    /**
090     * Clear the repository.
091     * <p/>
092     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
093     */
094    void clear();
095
096}