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.TimeUnit;
021    
022    import org.apache.camel.CamelContext;
023    import org.apache.camel.Service;
024    
025    /**
026     * Pluggable shutdown strategy executed during shutdown of routes.
027     * <p/>
028     * Shutting down routes in a reliable and graceful manner is not a trivial task. Therefore Camel provides a pluggable
029     * strategy allowing 3rd party to use their own strategy if needed.
030     * <p/>
031     * The key problem is to stop the input consumers for the routes such that no new messages is coming into Camel.
032     * But at the same time still keep the routes running so the existing in flight exchanges can still be run to
033     * completion. On top of that there are some in memory components (such as SEDA) which may have pending messages
034     * on its in memory queue which we want to run to completion as well, otherwise they will get lost.
035     * <p/>
036     * Camel provides a default strategy which supports all that that can be used as inspiration for your own strategy.
037     *
038     * @version 
039     * @see org.apache.camel.spi.ShutdownAware
040     */
041    public interface ShutdownStrategy extends Service {
042    
043        /**
044         * Shutdown the routes, forcing shutdown being more aggressive, if timeout occurred.
045         * <p/>
046         * This operation is used when {@link CamelContext} is shutting down, to ensure Camel will shutdown
047         * if messages seems to be <i>stuck</i>.
048         *
049         * @param context   the camel context
050         * @param routes    the routes, ordered by the order they was started
051         * @throws Exception is thrown if error shutting down the consumers, however its preferred to avoid this
052         */
053        void shutdownForced(CamelContext context, List<RouteStartupOrder> routes) throws Exception;
054    
055        /**
056         * Shutdown the routes
057         *
058         * @param context   the camel context
059         * @param routes    the routes, ordered by the order they was started
060         * @throws Exception is thrown if error shutting down the consumers, however its preferred to avoid this
061         */
062        void shutdown(CamelContext context, List<RouteStartupOrder> routes) throws Exception;
063    
064        /**
065         * Suspends the routes
066         *
067         * @param context   the camel context
068         * @param routes    the routes, ordered by the order they was started
069         * @throws Exception is thrown if error suspending the consumers, however its preferred to avoid this
070         */
071        void suspend(CamelContext context, List<RouteStartupOrder> routes) throws Exception;
072    
073        /**
074         * Shutdown the routes using a specified timeout instead of the default timeout values
075         *
076         * @param context   the camel context
077         * @param routes    the routes, ordered by the order they was started
078         * @param timeout   timeout
079         * @param timeUnit  the unit to use
080         * @throws Exception is thrown if error shutting down the consumers, however its preferred to avoid this
081         */
082        void shutdown(CamelContext context, List<RouteStartupOrder> routes, long timeout, TimeUnit timeUnit) throws Exception;
083    
084        /**
085         * Shutdown the route using a specified timeout instead of the default timeout values and supports abortAfterTimeout mode
086         *
087         * @param context   the camel context
088         * @param route     the route
089         * @param timeout   timeout
090         * @param timeUnit  the unit to use
091         * @param abortAfterTimeout   should abort shutdown after timeout
092         * @return <tt>true</tt> if the route is stopped before the timeout
093         * @throws Exception is thrown if error shutting down the consumer, however its preferred to avoid this
094         */
095        boolean shutdown(CamelContext context, RouteStartupOrder route, long timeout, TimeUnit timeUnit, boolean abortAfterTimeout) throws Exception;
096    
097        /**
098         * Suspends the routes using a specified timeout instead of the default timeout values
099         *
100         * @param context   the camel context
101         * @param routes    the routes, ordered by the order they was started
102         * @param timeout   timeout
103         * @param timeUnit  the unit to use
104         * @throws Exception is thrown if error suspending the consumers, however its preferred to avoid this
105         */
106        void suspend(CamelContext context, List<RouteStartupOrder> routes, long timeout, TimeUnit timeUnit) throws Exception;
107    
108        /**
109         * Set an timeout to wait for the shutdown to complete.
110         * <p/>
111         * Setting a value of 0 or negative will disable timeout and wait until complete
112         * (potential blocking forever)
113         * <p/>
114         * The default timeout unit is <tt>SECONDS</tt>
115         *
116         * @param timeout timeout
117         */
118        void setTimeout(long timeout);
119    
120        /**
121         * Gets the timeout.
122         * <p/>
123         * Use 0 or a negative value to disable timeout
124         * <p/>
125         * The default timeout unit is <tt>SECONDS</tt>
126         *
127         * @return the timeout
128         */
129        long getTimeout();
130    
131        /**
132         * Set the time unit to use
133         *
134         * @param timeUnit the unit to use
135         */
136        void setTimeUnit(TimeUnit timeUnit);
137    
138        /**
139         * Gets the time unit used
140         *
141         * @return the time unit
142         */
143        TimeUnit getTimeUnit();
144    
145        /**
146         * Sets whether to force shutdown of all consumers when a timeout occurred and thus
147         * not all consumers was shutdown within that period.
148         * <p/>
149         * You should have good reasons to set this option to <tt>false</tt> as it means that the routes
150         * keep running and is halted abruptly when {@link CamelContext} has been shutdown.
151         *
152         * @param shutdownNowOnTimeout <tt>true</tt> to force shutdown, <tt>false</tt> to leave them running
153         */
154        void setShutdownNowOnTimeout(boolean shutdownNowOnTimeout);
155    
156        /**
157         * Whether to force shutdown of all consumers when a timeout occurred.
158         *
159         * @return force shutdown or not
160         */
161        boolean isShutdownNowOnTimeout();
162    
163        /**
164         * Sets whether routes should be shutdown in reverse or the same order as they where started.
165         *
166         * @param shutdownRoutesInReverseOrder <tt>true</tt> to shutdown in reverse order
167         */
168        void setShutdownRoutesInReverseOrder(boolean shutdownRoutesInReverseOrder);
169    
170        /**
171         * Whether to shutdown routes in reverse order than they where started.
172         * <p/>
173         * This option is by default set to <tt>true</tt>.
174         *
175         * @return <tt>true</tt> if routes should be shutdown in reverse order.
176         */
177        boolean isShutdownRoutesInReverseOrder();
178    
179        /**
180         * Whether a service is forced to shutdown.
181         * <p/>
182         * Can be used to signal to services that they are no longer allowed to run, such as if a forced
183         * shutdown is currently in progress.
184         * <p/>
185         * For example the Camel {@link org.apache.camel.processor.RedeliveryErrorHandler} uses this information
186         * to know if a forced shutdown is in progress, and then break out of redelivery attempts.
187         * 
188         * @param service the service
189         * @return <tt>true</tt> indicates the service is to be forced to shutdown, <tt>false</tt> the service can keep running.
190         */
191        boolean forceShutdown(Service service);
192    
193    }