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 java.io.File;
020
021import org.apache.camel.Exchange;
022import org.apache.camel.StaticService;
023import org.apache.camel.StreamCache;
024
025/**
026 * Strategy for using <a href="http://camel.apache.org/stream-caching.html">stream caching</a>.
027 */
028public interface StreamCachingStrategy extends StaticService {
029
030    /**
031     * Utilization statistics of stream caching.
032     */
033    interface Statistics {
034
035        /**
036         * Gets the counter for number of in-memory {@link StreamCache} created.
037         */
038        long getCacheMemoryCounter();
039
040        /**
041         * Gets the total accumulated number of bytes which has been stream cached for in-memory stream caches.
042         */
043        long getCacheMemorySize();
044
045        /**
046         * Gets the average number of bytes per cached stream for in-memory stream caches.
047         */
048        long getCacheMemoryAverageSize();
049
050        /**
051         * Gets the counter for number of spooled (not in-memory) {@link StreamCache} created.
052         */
053        long getCacheSpoolCounter();
054
055        /**
056         * Gets the total accumulated number of bytes which has been stream cached for spooled stream caches.
057         */
058        long getCacheSpoolSize();
059
060        /**
061         * Gets the average number of bytes per cached stream for spooled (not in-memory) stream caches.
062         */
063        long getCacheSpoolAverageSize();
064
065        /**
066         * Reset the counters
067         */
068        void reset();
069
070        /**
071         * Whether statistics is enabled.
072         */
073        boolean isStatisticsEnabled();
074
075        /**
076         * Sets whether statistics is enabled.
077         *
078         * @param statisticsEnabled <tt>true</tt> to enable
079         */
080        void setStatisticsEnabled(boolean statisticsEnabled);
081    }
082
083    /**
084     * Used for selecting if the memory limit is <tt>committed</tt> or <tt>maximum</tt> heap memory setting.
085     */
086    enum SpoolUsedHeapMemoryLimit {
087        Committed, Max
088    }
089
090    /**
091     * Rule for determine if stream caching should be spooled to disk or kept in-memory.
092     */
093    interface SpoolRule {
094
095        /**
096         * Determines if the stream should be spooled or not. For example if the stream length is
097         * over a threshold.
098         * <p/>
099         * This allows implementations to use custom strategies to determine if spooling is needed or not.
100         *
101         * @param length the length of the stream
102         * @return <tt>true</tt> to spool the cache, or <tt>false</tt> to keep the cache in-memory
103         */
104        boolean shouldSpoolCache(long length);
105
106    }
107
108    /**
109     * Sets whether the stream caching is enabled.
110     * <p/>
111     * <b>Notice:</b> This cannot be changed at runtime.
112     */
113    void setEnabled(boolean enabled);
114
115    boolean isEnabled();
116
117    /**
118     * Sets the spool (temporary) directory to use for overflow and spooling to disk.
119     * <p/>
120     * If no spool directory has been explicit configured, then a temporary directory
121     * is created in the <tt>java.io.tmpdir</tt> directory.
122     */
123    void setSpoolDirectory(File path);
124
125    File getSpoolDirectory();
126
127    void setSpoolDirectory(String path);
128
129    /**
130     * Threshold in bytes when overflow to disk is activated.
131     * <p/>
132     * The default threshold is {@link org.apache.camel.StreamCache#DEFAULT_SPOOL_THRESHOLD} bytes (eg 128kb).
133     * Use <tt>-1</tt> to disable overflow to disk.
134     */
135    void setSpoolThreshold(long threshold);
136
137    long getSpoolThreshold();
138
139    /**
140     * Sets a percentage (1-99) of used heap memory threshold to activate spooling to disk.
141     *
142     * @param percentage percentage of used heap memory.
143     */
144    void setSpoolUsedHeapMemoryThreshold(int percentage);
145
146    int getSpoolUsedHeapMemoryThreshold();
147
148    /**
149     * Sets what the upper bounds should be when {@link #setSpoolUsedHeapMemoryThreshold(int)}
150     * is in use.
151     *
152     * @param bounds the bounds
153     */
154    void setSpoolUsedHeapMemoryLimit(SpoolUsedHeapMemoryLimit bounds);
155
156    SpoolUsedHeapMemoryLimit getSpoolUsedHeapMemoryLimit();
157
158    /**
159     * Sets the buffer size to use when allocating in-memory buffers used for in-memory stream caches.
160     * <p/>
161     * The default size is {@link org.apache.camel.util.IOHelper#DEFAULT_BUFFER_SIZE}
162     */
163    void setBufferSize(int bufferSize);
164
165    int getBufferSize();
166
167    /**
168     * Sets a chiper name to use when spooling to disk to write with encryption.
169     * <p/>
170     * By default the data is not encrypted.
171     */
172    void setSpoolChiper(String chiper);
173
174    String getSpoolChiper();
175
176    /**
177     * Whether to remove the temporary directory when stopping.
178     * <p/>
179     * This option is default <tt>true</tt>
180     */
181    void setRemoveSpoolDirectoryWhenStopping(boolean remove);
182
183    boolean isRemoveSpoolDirectoryWhenStopping();
184
185    /**
186     * Sets whether if just any of the {@link org.apache.camel.spi.StreamCachingStrategy.SpoolRule} rules
187     * returns <tt>true</tt> then {@link #shouldSpoolCache(long)} returns <tt>true</tt>.
188     * If this option is <tt>false</tt>, then <b>all</b> the {@link org.apache.camel.spi.StreamCachingStrategy.SpoolRule} must
189     * return <tt>true</tt>.
190     * <p/>
191     * The default value is <tt>false</tt> which means that all the rules must return <tt>true</tt>.
192     */
193    void setAnySpoolRules(boolean any);
194
195    boolean isAnySpoolRules();
196
197    /**
198     * Gets the utilization statistics.
199     */
200    Statistics getStatistics();
201
202    /**
203     * Adds the {@link org.apache.camel.spi.StreamCachingStrategy.SpoolRule} rule to be used.
204     */
205    void addSpoolRule(SpoolRule rule);
206
207    /**
208     * Determines if the stream should be spooled or not. For example if the stream length is
209     * over a threshold.
210     * <p/>
211     * This allows implementations to use custom strategies to determine if spooling is needed or not.
212     *
213     * @param length the length of the stream
214     * @return <tt>true</tt> to spool the cache, or <tt>false</tt> to keep the cache in-memory
215     */
216    boolean shouldSpoolCache(long length);
217
218    /**
219     * Caches the body aas a {@link StreamCache}.
220     *
221     * @param exchange the exchange
222     * @return the body cached as a {@link StreamCache}, or <tt>null</tt> if not possible or no need to cache the body
223     */
224    StreamCache cache(Exchange exchange);
225
226}