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    }