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.util.List; 020 import java.util.concurrent.ExecutorService; 021 import java.util.concurrent.ScheduledExecutorService; 022 023 import org.apache.camel.ShutdownableService; 024 025 /** 026 * Strategy to create thread pools. 027 * <p/> 028 * This manager is pluggable so you can plugin a custom provider, for example if you want to leverage 029 * the WorkManager for a JEE server. 030 * <p/> 031 * You may want to just implement a custom {@link ThreadPoolFactory} and rely on the 032 * {@link org.apache.camel.impl.DefaultExecutorServiceManager}, if that is sufficient. The {@link ThreadPoolFactory} 033 * is always used for creating the actual thread pools. You can implement a custom {@link ThreadPoolFactory} 034 * to leverage the WorkManager for a JEE server. 035 * <p/> 036 * The {@link ThreadPoolFactory} has pure JDK API, where as this {@link ExecutorServiceManager} has Camel API 037 * concepts such as {@link ThreadPoolProfile}. Therefore it may be easier to only implement a custom 038 * {@link ThreadPoolFactory}. 039 * <p/> 040 * This manager has fine grained methods for creating various thread pools, however custom strategies 041 * do not have to exactly create those kind of pools. Feel free to return a shared or different kind of pool. 042 * <p/> 043 * If you use the <tt>newXXX</tt> methods to create thread pools, then Camel will by default take care of 044 * shutting down those created pools when {@link org.apache.camel.CamelContext} is shutting down. 045 * <p/> 046 * @see ThreadPoolFactory 047 */ 048 public interface ExecutorServiceManager extends ShutdownableService { 049 050 /** 051 * Gets the {@link ThreadPoolFactory} to use for creating the thread pools. 052 * 053 * @return the thread pool factory 054 */ 055 ThreadPoolFactory getThreadPoolFactory(); 056 057 /** 058 * Sets a custom {@link ThreadPoolFactory} to use 059 * 060 * @param threadPoolFactory the thread pool factory 061 */ 062 void setThreadPoolFactory(ThreadPoolFactory threadPoolFactory); 063 064 /** 065 * Creates a full thread name 066 * 067 * @param name name which is appended to the full thread name 068 * @return the full thread name 069 */ 070 String resolveThreadName(String name); 071 072 /** 073 * Gets the thread pool profile by the given id 074 * 075 * @param id id of the thread pool profile to get 076 * @return the found profile, or <tt>null</tt> if not found 077 */ 078 ThreadPoolProfile getThreadPoolProfile(String id); 079 080 /** 081 * Registers the given thread pool profile 082 * 083 * @param profile the profile 084 */ 085 void registerThreadPoolProfile(ThreadPoolProfile profile); 086 087 /** 088 * Sets the default thread pool profile 089 * 090 * @param defaultThreadPoolProfile the new default thread pool profile 091 */ 092 void setDefaultThreadPoolProfile(ThreadPoolProfile defaultThreadPoolProfile); 093 094 /** 095 * Gets the default thread pool profile 096 * 097 * @return the default profile which are newer <tt>null</tt> 098 */ 099 ThreadPoolProfile getDefaultThreadPoolProfile(); 100 101 /** 102 * Sets the thread name pattern used for creating the full thread name. 103 * <p/> 104 * The default pattern is: <tt>Camel (#camelId#) thread ##counter# - #name#</tt> 105 * <p/> 106 * Where <tt>#camelId#</tt> is the name of the {@link org.apache.camel.CamelContext} 107 * <br/>and <tt>#counter#</tt> is a unique incrementing counter. 108 * <br/>and <tt>#name#</tt> is the regular thread name. 109 * <br/>You can also use <tt>#longName#</tt> is the long thread name which can includes endpoint parameters etc. 110 * 111 * @param pattern the pattern 112 * @throws IllegalArgumentException if the pattern is invalid. 113 */ 114 void setThreadNamePattern(String pattern) throws IllegalArgumentException; 115 116 /** 117 * Gets the thread name patter to use 118 * 119 * @return the pattern 120 */ 121 String getThreadNamePattern(); 122 123 /** 124 * Creates a new thread pool using the default thread pool profile. 125 * 126 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 127 * @param name name which is appended to the thread name 128 * @return the created thread pool 129 */ 130 ExecutorService newDefaultThreadPool(Object source, String name); 131 132 /** 133 * Creates a new scheduled thread pool using the default thread pool profile. 134 * 135 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 136 * @param name name which is appended to the thread name 137 * @return the created thread pool 138 */ 139 ScheduledExecutorService newDefaultScheduledThreadPool(Object source, String name); 140 141 /** 142 * Creates a new thread pool using the given profile 143 * 144 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 145 * @param name name which is appended to the thread name 146 * @param profile the profile with the thread pool settings to use 147 * @return the created thread pool 148 */ 149 ExecutorService newThreadPool(Object source, String name, ThreadPoolProfile profile); 150 151 /** 152 * Creates a new thread pool using using the given profile id 153 * 154 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 155 * @param name name which is appended to the thread name 156 * @param profileId the id of the profile with the thread pool settings to use 157 * @return the created thread pool, or <tt>null</tt> if the thread pool profile could not be found 158 */ 159 ExecutorService newThreadPool(Object source, String name, String profileId); 160 161 /** 162 * Creates a new thread pool. 163 * <p/> 164 * Will fallback and use values from the default thread pool profile for keep alive time, rejection policy 165 * and other parameters which cannot be specified. 166 * 167 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 168 * @param name name which is appended to the thread name 169 * @param poolSize the core pool size 170 * @param maxPoolSize the maximum pool size 171 * @return the created thread pool 172 */ 173 ExecutorService newThreadPool(Object source, String name, int poolSize, int maxPoolSize); 174 175 /** 176 * Creates a new single-threaded thread pool. This is often used for background threads. 177 * <p/> 178 * Notice that there will always be a single thread in the pool. If you want the pool to be 179 * able to shrink to no threads, then use the <tt>newThreadPool</tt> method, and use 180 * 0 in core pool size, and 1 in max pool size. 181 * 182 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 183 * @param name name which is appended to the thread name 184 * @return the created thread pool 185 */ 186 ExecutorService newSingleThreadExecutor(Object source, String name); 187 188 /** 189 * Creates a new cached thread pool. 190 * <p/> 191 * <b>Important:</b> Using cached thread pool is discouraged as they have no upper bound and can overload the JVM. 192 * 193 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 194 * @param name name which is appended to the thread name 195 * @return the created thread pool 196 */ 197 ExecutorService newCachedThreadPool(Object source, String name); 198 199 /** 200 * Creates a new fixed thread pool. 201 * 202 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 203 * @param name name which is appended to the thread name 204 * @param poolSize the core pool size 205 * @return the created thread pool 206 */ 207 ExecutorService newFixedThreadPool(Object source, String name, int poolSize); 208 209 /** 210 * Creates a new scheduled thread pool. 211 * 212 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 213 * @param name name which is appended to the thread name 214 * @param poolSize the core pool size 215 * @return the created thread pool 216 */ 217 ScheduledExecutorService newScheduledThreadPool(Object source, String name, int poolSize); 218 219 /** 220 * Creates a new single-threaded thread pool. This is often used for background threads. 221 * 222 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 223 * @param name name which is appended to the thread name 224 * @return the created thread pool 225 */ 226 ScheduledExecutorService newSingleThreadScheduledExecutor(Object source, String name); 227 228 /** 229 * Creates a new scheduled thread pool using a profile 230 * 231 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 232 * @param name name which is appended to the thread name 233 * @param profile the profile with the thread pool settings to use 234 * @return created thread pool 235 */ 236 ScheduledExecutorService newScheduledThreadPool(Object source, String name, ThreadPoolProfile profile); 237 238 /** 239 * Creates a new scheduled thread pool using a profile id 240 * 241 * @param source the source object, usually it should be <tt>this</tt> passed in as parameter 242 * @param name name which is appended to the thread name 243 * @param profileId the id of the profile with the thread pool settings to use 244 * @return created thread pool 245 */ 246 ScheduledExecutorService newScheduledThreadPool(Object source, String name, String profileId); 247 248 /** 249 * Shutdown the given executor service. 250 * 251 * @param executorService the executor service to shutdown 252 * @see java.util.concurrent.ExecutorService#shutdown() 253 */ 254 void shutdown(ExecutorService executorService); 255 256 /** 257 * Shutdown now the given executor service. 258 * 259 * @param executorService the executor service to shutdown now 260 * @return list of tasks that never commenced execution 261 * @see java.util.concurrent.ExecutorService#shutdownNow() 262 */ 263 List<Runnable> shutdownNow(ExecutorService executorService); 264 265 }