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}