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.component.file;
018
019import org.apache.camel.Exchange;
020import org.apache.camel.LoggingLevel;
021
022/**
023 * Strategy for acquiring exclusive read locks for files to be consumed. After
024 * granting the read lock it is released, we just want to make sure that when
025 * we start consuming the file its not currently in progress of being written by
026 * third party.
027 * <p/>
028 * Camel supports out of the box the following strategies:
029 * <ul>
030 * <li>FileRenameExclusiveReadLockStrategy waiting until its possible to rename the file.</li>
031 * <li>FileLockExclusiveReadLockStrategy acquiring a RW file lock for the duration of the processing.</li>
032 * <li>MarkerFileExclusiveReadLockStrategy using a marker file for acquiring read lock.</li>
033 * <li>FileChangedExclusiveReadLockStrategy using a file changed detection for acquiring read lock.</li>
034 * <li>FileIdempotentRepositoryReadLockStrategy using a {@link org.apache.camel.spi.IdempotentRepository} to hold the read locks which allows to support clustering.</li>
035 * </ul>
036 */
037public interface GenericFileExclusiveReadLockStrategy<T> {
038
039    /**
040     * Allows custom logic to be run on startup preparing the strategy, such as removing old lock files etc.
041     *
042     * @param operations generic file operations
043     * @param endpoint   the endpoint
044     * @throws Exception can be thrown in case of errors
045     */
046    void prepareOnStartup(GenericFileOperations<T> operations, GenericFileEndpoint<T> endpoint) throws Exception;
047
048    /**
049     * Acquires exclusive read lock to the file.
050     *
051     * @param operations generic file operations
052     * @param file       the file
053     * @param exchange   the exchange
054     * @return <tt>true</tt> if read lock was acquired. If <tt>false</tt> Camel
055     *         will skip the file and try it on the next poll
056     * @throws Exception can be thrown in case of errors
057     */
058    boolean acquireExclusiveReadLock(GenericFileOperations<T> operations, GenericFile<T> file, Exchange exchange) throws Exception;
059
060    /**
061     * Releases the exclusive read lock granted by the <tt>acquireExclusiveReadLock</tt> method due an abort operation (acquireExclusiveReadLock returned false).
062     *
063     * @param operations generic file operations
064     * @param file       the file
065     * @param exchange   the exchange
066     * @throws Exception can be thrown in case of errors
067     */
068    void releaseExclusiveReadLockOnAbort(GenericFileOperations<T> operations, GenericFile<T> file, Exchange exchange) throws Exception;
069
070    /**
071     * Releases the exclusive read lock granted by the <tt>acquireExclusiveReadLock</tt> method due a rollback operation (Exchange processing failed)
072     *
073     * @param operations generic file operations
074     * @param file       the file
075     * @param exchange   the exchange
076     * @throws Exception can be thrown in case of errors
077     */
078    void releaseExclusiveReadLockOnRollback(GenericFileOperations<T> operations, GenericFile<T> file, Exchange exchange) throws Exception;
079
080    /**
081     * Releases the exclusive read lock granted by the <tt>acquireExclusiveReadLock</tt> method due a commit operation (Exchange processing succeeded)
082     *
083     * @param operations generic file operations
084     * @param file       the file
085     * @param exchange   the exchange
086     * @throws Exception can be thrown in case of errors
087     */
088    void releaseExclusiveReadLockOnCommit(GenericFileOperations<T> operations, GenericFile<T> file, Exchange exchange) throws Exception;
089
090    /**
091     * Sets an optional timeout period.
092     * <p/>
093     * If the readlock could not be granted within the time period then the wait is stopped and the
094     * <tt>acquireExclusiveReadLock</tt> method returns <tt>false</tt>.
095     *
096     * @param timeout period in millis
097     */
098    void setTimeout(long timeout);
099
100    /**
101     * Sets the check interval period.
102     * <p/>
103     * The check interval is used for sleeping between attempts to acquire read lock.
104     * Setting a high value allows to cater for <i>slow writes</i> in case the producer
105     * of the file is slow.
106     * <p/>
107     * The default period is 1000 millis.
108     *
109     * @param checkInterval interval in millis
110     */
111    void setCheckInterval(long checkInterval);
112
113    /**
114     * Sets logging level used when a read lock could not be acquired.
115     * <p/>
116     * Logging level used when a read lock could not be acquired.
117     * <p/>
118     * The default logging level is WARN
119     * @param readLockLoggingLevel LoggingLevel
120     */
121    void setReadLockLoggingLevel(LoggingLevel readLockLoggingLevel);
122
123    /**
124     * Sets whether marker file should be used or not.
125     *
126     * @param markerFile <tt>true</tt> to use marker files.
127     */
128    void setMarkerFiler(boolean markerFile);
129
130    /**
131     * Sets whether orphan marker files should be deleted upon startup
132     *
133     * @param deleteOrphanLockFiles <tt>true</tt> to delete files, <tt>false</tt> to skip this check
134     */
135    void setDeleteOrphanLockFiles(boolean deleteOrphanLockFiles);
136
137}