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.util.List;
020import java.util.concurrent.ExecutorService;
021import java.util.concurrent.RejectedExecutionHandler;
022import java.util.concurrent.ScheduledExecutorService;
023import java.util.concurrent.TimeUnit;
024
025import 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
044public 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}