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