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 */
017 package org.apache.camel.spi;
018
019 import java.io.File;
020
021 import org.apache.camel.Exchange;
022 import org.apache.camel.StaticService;
023 import org.apache.camel.StreamCache;
024
025 /**
026 * Strategy for using <a href="http://camel.apache.org/stream-caching.html">stream caching</a>.
027 */
028 public 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 }