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 }