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 }