org.apache.camel.spi.StreamCachingStrategy Maven / Gradle / Ivy

Go to download
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.camel.spi;

import java.io.File;

import org.apache.camel.Exchange;
import org.apache.camel.StaticService;
import org.apache.camel.StreamCache;

/**
 * Strategy for using stream caching.
 */
public interface StreamCachingStrategy extends StaticService {

    /**
     * Utilization statistics of stream caching.
     */
    interface Statistics {

        /**
         * Gets the counter for number of in-memory {@link StreamCache} created.
         */
        long getCacheMemoryCounter();

        /**
         * Gets the total accumulated number of bytes which has been stream cached for in-memory stream caches.
         */
        long getCacheMemorySize();

        /**
         * Gets the average number of bytes per cached stream for in-memory stream caches.
         */
        long getCacheMemoryAverageSize();

        /**
         * Gets the counter for number of spooled (not in-memory) {@link StreamCache} created.
         */
        long getCacheSpoolCounter();

        /**
         * Gets the total accumulated number of bytes which has been stream cached for spooled stream caches.
         */
        long getCacheSpoolSize();

        /**
         * Gets the average number of bytes per cached stream for spooled (not in-memory) stream caches.
         */
        long getCacheSpoolAverageSize();

        /**
         * Reset the counters
         */
        void reset();

        /**
         * Whether statistics is enabled.
         */
        boolean isStatisticsEnabled();

        /**
         * Sets whether statistics is enabled.
         *
         * @param statisticsEnabled true to enable
         */
        void setStatisticsEnabled(boolean statisticsEnabled);
    }

    /**
     * Used for selecting if the memory limit is committed or maximum heap memory setting.
     */
    enum SpoolUsedHeapMemoryLimit {
        Committed,
        Max
    }

    /**
     * Rule for determine if stream caching should be spooled to disk or kept in-memory.
     */
    interface SpoolRule {

        /**
         * Determines if the stream should be spooled or not. For example if the stream length is over a threshold.
         * 
         * This allows implementations to use custom strategies to determine if spooling is needed or not.
         *
         * @param  length the length of the stream
         * @return        true to spool the cache, or false to keep the cache in-memory
         */
        boolean shouldSpoolCache(long length);

    }

    /**
     * Sets whether the stream caching is enabled.
     * 

     * Notice: This cannot be changed at runtime.
     */
    void setEnabled(boolean enabled);

    boolean isEnabled();

    /**
     * Sets the spool (temporary) directory to use for overflow and spooling to disk.
     * 

     * If no spool directory has been explicit configured, then a temporary directory is created in the
     * java.io.tmpdir directory.
     */
    void setSpoolDirectory(File path);

    File getSpoolDirectory();

    void setSpoolDirectory(String path);

    /**
     * Threshold in bytes when overflow to disk is activated.
     * 

     * The default threshold is {@link org.apache.camel.StreamCache#DEFAULT_SPOOL_THRESHOLD} bytes (eg 128kb). Use
     * -1 to disable overflow to disk.
     */
    void setSpoolThreshold(long threshold);

    long getSpoolThreshold();

    /**
     * Sets a percentage (1-99) of used heap memory threshold to activate spooling to disk.
     *
     * @param percentage percentage of used heap memory.
     */
    void setSpoolUsedHeapMemoryThreshold(int percentage);

    int getSpoolUsedHeapMemoryThreshold();

    /**
     * Sets what the upper bounds should be when {@link #setSpoolUsedHeapMemoryThreshold(int)} is in use.
     *
     * @param bounds the bounds
     */
    void setSpoolUsedHeapMemoryLimit(SpoolUsedHeapMemoryLimit bounds);

    SpoolUsedHeapMemoryLimit getSpoolUsedHeapMemoryLimit();

    /**
     * Sets the buffer size to use when allocating in-memory buffers used for in-memory stream caches.
     * 

     * The default size is {@link org.apache.camel.util.IOHelper#DEFAULT_BUFFER_SIZE}
     */
    void setBufferSize(int bufferSize);

    int getBufferSize();

    /**
     * Sets a cipher name to use when spooling to disk to write with encryption.
     * 

     * By default the data is not encrypted.
     */
    void setSpoolCipher(String cipher);

    String getSpoolCipher();

    /**
     * Whether to remove the temporary directory when stopping.
     * 

     * This option is default true
     */
    void setRemoveSpoolDirectoryWhenStopping(boolean remove);

    boolean isRemoveSpoolDirectoryWhenStopping();

    /**
     * Sets whether if just any of the {@link org.apache.camel.spi.StreamCachingStrategy.SpoolRule} rules returns
     * true then {@link #shouldSpoolCache(long)} returns true. If this option is false, then
     * all the {@link org.apache.camel.spi.StreamCachingStrategy.SpoolRule} must return true.
     * 

     * The default value is false which means that all the rules must return true.
     */
    void setAnySpoolRules(boolean any);

    boolean isAnySpoolRules();

    /**
     * Gets the utilization statistics.
     */
    Statistics getStatistics();

    /**
     * Adds the {@link org.apache.camel.spi.StreamCachingStrategy.SpoolRule} rule to be used.
     */
    void addSpoolRule(SpoolRule rule);

    /**
     * Determines if the stream should be spooled or not. For example if the stream length is over a threshold.
     * 
     * This allows implementations to use custom strategies to determine if spooling is needed or not.
     *
     * @param  length the length of the stream
     * @return        true to spool the cache, or false to keep the cache in-memory
     */
    boolean shouldSpoolCache(long length);

    /**
     * Caches the body aas a {@link StreamCache}.
     *
     * @param  exchange the exchange
     * @return          the body cached as a {@link StreamCache}, or null if not possible or no need to cache
     *                  the body
     */
    StreamCache cache(Exchange exchange);

}