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