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;
020import org.apache.camel.Service;
021
022/**
023 * Access to a repository of Message IDs to implement the
024 * <a href="http://camel.apache.org/idempotent-consumer.html">Idempotent Consumer</a> pattern.
025 * <p/>
026 * The <tt>add</tt> and <tt>contains</tt> methods is operating according to the {@link java.util.Set} contract.
027 * <p/>
028 * The repository supports eager (default) and non-eager mode.
029 * <ul>
030 *     <li>eager: calls <tt>add</tt> and <tt>confirm</tt> if complete, or <tt>remove</tt> if failed</li>
031 *     <li>non-eager: calls <tt>contains</tt> and <tt>add</tt> if complete, or <tt>remove</tt> if failed</li>
032 * </ul>
033 * Notice the remove callback, can be configured to be disabled.
034 */
035public interface IdempotentRepository extends Service {
036
037    /**
038     * Adds the key to the repository.
039     * <p/>
040     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
041     *
042     * @param key the key of the message for duplicate test
043     * @return <tt>true</tt> if this repository did <b>not</b> already contain the specified element
044     */
045    boolean add(String key);
046
047    /**
048     * Returns <tt>true</tt> if this repository contains the specified element.
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
053     * @return <tt>true</tt> if this repository contains the specified element
054     */
055    boolean contains(String key);
056
057    /**
058     * Removes the key from the repository.
059     * <p/>
060     * Is usually invoked if the exchange failed.
061     * <p/>
062     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
063     *
064     * @param key the key of the message for duplicate test
065     * @return <tt>true</tt> if the key was removed
066     */
067    boolean remove(String key);
068
069    /**
070     * Confirms the key, after the exchange has been processed successfully.
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 confirmed
076     */
077    boolean confirm(String key);
078    
079    /**
080     * Clear the repository.
081     * <p/>
082     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
083     */
084    void clear();
085
086    /**
087     * Adds the key to the repository.
088     * <p/>
089     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
090     *
091     * @param key the key of the message for duplicate test
092     * @return <tt>true</tt> if this repository did <b>not</b> already contain the specified element
093     */
094    default boolean add(Exchange exchange, String key) {
095        return add(key);
096    }
097
098    /**
099     * Returns <tt>true</tt> if this repository contains the specified element.
100     * <p/>
101     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
102     *
103     * @param key the key of the message
104     * @return <tt>true</tt> if this repository contains the specified element
105     */
106    default boolean contains(Exchange exchange, String key) {
107        return contains(key);
108    }
109
110    /**
111     * Removes the key from the repository.
112     * <p/>
113     * Is usually invoked if the exchange failed.
114     * <p/>
115     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
116     *
117     * @param key the key of the message for duplicate test
118     * @return <tt>true</tt> if the key was removed
119     */
120    default boolean remove(Exchange exchange, String key) {
121        return remove(key);
122    }
123
124    /**
125     * Confirms the key, after the exchange has been processed successfully.
126     * <p/>
127     * <b>Important:</b> Read the class javadoc about eager vs non-eager mode.
128     *
129     * @param key the key of the message for duplicate test
130     * @return <tt>true</tt> if the key was confirmed
131     */
132    default boolean confirm(Exchange exchange, String key) {
133        return confirm(key);
134    }
135
136}