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 }