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;
018    
019    import java.util.Collection;
020    import java.util.List;
021    import java.util.Map;
022    import java.util.concurrent.Callable;
023    
024    import org.apache.camel.builder.ErrorHandlerBuilder;
025    import org.apache.camel.model.RouteType;
026    import org.apache.camel.model.dataformat.DataFormatType;
027    import org.apache.camel.spi.ExchangeConverter;
028    import org.apache.camel.spi.Injector;
029    import org.apache.camel.spi.InterceptStrategy;
030    import org.apache.camel.spi.Language;
031    import org.apache.camel.spi.LifecycleStrategy;
032    import org.apache.camel.spi.Registry;
033    
034    /**
035     * Interface used to represent the context used to configure routes and the
036     * policies to use during message exchanges between endpoints.
037     *
038     * @version $Revision: 53295 $
039     */
040    public interface CamelContext extends Service {
041    
042        /**
043         * Gets the name of the this context.
044         *
045         * @return the name
046         */
047        String getName();
048    
049        // Component Management Methods
050        //-----------------------------------------------------------------------
051    
052        /**
053         * Adds a component to the context.
054         *
055         * @param componentName  the name the component is registered as
056         * @param component      the component
057         */
058        void addComponent(String componentName, Component component);
059    
060        /**
061         * Gets a component from the context by name.
062         *
063         * @param componentName the name of the component
064         * @return the component
065         */
066        Component getComponent(String componentName);
067    
068        /**
069         * Gets a component from the context by name and specifying the expected type of component.
070         *
071         * @param name  the name to lookup
072         * @param componentType  the expected type
073         * @return the component
074         */
075        <T extends Component> T getComponent(String name, Class<T> componentType);
076    
077        /**
078         * Removes a previously added component.
079         *
080         * @param componentName the component name to remove
081         * @return the previously added component or null if it had not been previously added.
082         */
083        Component removeComponent(String componentName);
084    
085        /**
086         * Gets the a previously added component by name or lazily creates the component
087         * using the factory Callback.
088         *
089         * @param componentName the name of the component
090         * @param factory       used to create a new component instance if the component was not previously added.
091         * @return the component
092         */
093        Component getOrCreateComponent(String componentName, Callable<Component> factory);
094    
095        // Endpoint Management Methods
096        //-----------------------------------------------------------------------
097    
098        /**
099         * Resolves the given URI to an {@link Endpoint}.  If the URI has a singleton endpoint
100         * registered, then the singleton is returned.  Otherwise, a new {@link Endpoint} is created
101         * and if the endpoint is a singleton it is registered as a singleton endpoint.
102         *
103         * @param uri  the URI of the endpoint
104         * @return  the endpoint
105         */
106        Endpoint getEndpoint(String uri);
107    
108        /**
109         * Resolves the given name to an {@link Endpoint} of the specified type.
110         * If the name has a singleton endpoint registered, then the singleton is returned.
111         * Otherwise, a new {@link Endpoint} is created and if the endpoint is a
112         * singleton it is registered as a singleton endpoint.
113         *
114         * @param name  the name of the endpoint
115         * @param endpointType  the expected type
116         * @return the endpoint
117         */
118        <T extends Endpoint> T getEndpoint(String name, Class<T> endpointType);
119    
120        /**
121         * Returns the collection of all registered endpoints.
122         *
123         * @return  all endpoints
124         */
125        Collection<Endpoint> getEndpoints();
126    
127        /**
128         * Returns the collection of all registered endpoints for a uri or an empty collection.
129         * For a singleton endpoint the collection will contain exactly one element.
130         *
131         * @param uri  the URI of the endpoints
132         * @return  collection of endpoints
133         */
134        Collection<Endpoint> getEndpoints(String uri);
135    
136        /**
137         * Returns the collection of all registered singleton endpoints.
138         *
139         * @return  all the singleton endpoints
140         */
141        Collection<Endpoint> getSingletonEndpoints();
142    
143        /**
144         * Adds the endpoint to the context using the given URI.
145         *
146         * @param uri the URI to be used to resolve this endpoint
147         * @param endpoint the endpoint to be added to the context
148         * @return the old endpoint that was previously registered to the context if 
149         * there was already an singleton endpoint for that URI or null
150         * @throws Exception if the new endpoint could not be started or the old 
151         * singleton endpoint could not be stopped
152         */
153        Endpoint addEndpoint(String uri, Endpoint endpoint) throws Exception;
154    
155        /**
156         * Removes all endpoints with the given URI
157         *
158         * @param uri the URI to be used to remove
159         * @return a collection of endpoints removed or null if there are no endpoints for this URI
160         * @throws Exception if at least one endpoint could not be stopped
161         */
162        Collection<Endpoint> removeEndpoints(String uri) throws Exception;
163    
164        /**
165         * Adds the endpoint to the context using the given URI.  The endpoint will be registered as a singleton.
166         *
167         * @param uri the URI to be used to resolve this endpoint
168         * @param endpoint the endpoint to be added to the context
169         * @return the old endpoint that was previously registered to the context if there was
170         * already an endpoint for that URI
171         * @throws Exception if the new endpoint could not be started or the old endpoint could not be stopped
172         */
173        @Deprecated
174        Endpoint addSingletonEndpoint(String uri, Endpoint endpoint) throws Exception;
175    
176        /**
177         * Removes the singleton endpoint with the given URI
178         *
179         * @param uri the URI to be used to remove
180         * @return the endpoint that was removed or null if there is no endpoint for this URI
181         * @throws Exception if endpoint could not be stopped
182         */
183        @Deprecated
184        Endpoint removeSingletonEndpoint(String uri) throws Exception;
185    
186    
187        // Route Management Methods
188        //-----------------------------------------------------------------------
189    
190        /**
191         * Returns a list of the current route definitions
192         *
193         * @return list of the current route definitions
194         */
195        List<RouteType> getRouteDefinitions();
196    
197        /**
198         * Returns the current routes in this context
199         *
200         * @return the current routes
201         */
202        List<Route> getRoutes();
203    
204        /**
205         * Sets the routes for this context, replacing any current routes
206         *
207         * @param routes the new routes to use
208         * @deprecated is considered for deprecation, use addRoutes instead, could be removed in Camel 2.0
209         */
210        @Deprecated
211        void setRoutes(List<Route> routes);
212    
213        /**
214         * Adds a collection of routes to this context
215         *
216         * @param routes the routes to add
217         * @throws Exception if the routes could not be created for whatever reason
218         */
219        void addRoutes(Collection<Route> routes) throws Exception;
220    
221        /**
222         * Adds a collection of routes to this context using the given builder
223         * to build them
224         *
225         * @param builder the builder which will create the routes and add them to this context
226         * @throws Exception if the routes could not be created for whatever reason
227         */
228        void addRoutes(Routes builder) throws Exception;
229    
230        /**
231         * Adds a collection of route definitions to the context
232         *
233         * @param routeDefinitions the route definitions to add
234         * @throws Exception if the route definition could not be created for whatever reason
235         */
236        void addRouteDefinitions(Collection<RouteType> routeDefinitions) throws Exception;
237    
238    
239        // Properties
240        //-----------------------------------------------------------------------
241    
242        /**
243         * Returns the converter of exchanges from one type to another
244         *
245         * @return the converter
246         */
247        ExchangeConverter getExchangeConverter();
248    
249        /**
250         * Returns the type converter used to coerce types from one type to another
251         *
252         * @return the converter
253         */
254        TypeConverter getTypeConverter();
255    
256        /**
257         * Returns the registry used to lookup components by name and type such as the Spring ApplicationContext,
258         * JNDI or the OSGi Service Registry
259         *
260         * @return the registry
261         */
262        Registry getRegistry();
263    
264        /**
265         * Returns the injector used to instantiate objects by type
266         *
267         * @return the injector
268         */
269        Injector getInjector();
270    
271        /**
272         * Returns the lifecycle strategy used to handle lifecycle notification
273         *
274         * @return the lifecycle strategy
275         */
276        LifecycleStrategy getLifecycleStrategy();
277    
278        /**
279         * Resolves a language for creating expressions
280         *
281         * @param language  name of the language
282         * @return the resolved language
283         */
284        Language resolveLanguage(String language);
285    
286        /**
287         * Creates a new ProducerTemplate.
288         * <p/>
289         * See this FAQ before use: <a href="http://activemq.apache.org/camel/why-does-camel-use-too-many-threads-with-producertemplate.html">
290         * Why does Camel use too many threads with ProducerTemplate?</a>
291         *
292         * @return the template
293         */
294        <E extends Exchange> ProducerTemplate<E> createProducerTemplate();
295    
296        /**
297         * Adds the given interceptor strategy
298         *
299         * @param interceptStrategy the strategy
300         */
301        void addInterceptStrategy(InterceptStrategy interceptStrategy);
302    
303        /**
304         * Gets the default error handler builder which is inherited by the routes
305         *
306         * @return the builder
307         */
308        ErrorHandlerBuilder getErrorHandlerBuilder();
309    
310        /**
311         * Sets the default error handler builder which is inherited by the routes
312         *
313         * @param errorHandlerBuilder  the builder
314         */
315        void setErrorHandlerBuilder(ErrorHandlerBuilder errorHandlerBuilder);
316    
317        /**
318         * Sets the data formats that can be referenced in the routes.
319         * @param dataFormats the data formats
320         */
321        void setDataFormats(Map<String, DataFormatType> dataFormats);
322    
323        /**
324         * Gets the data formats that can be referenced in the routes.
325         *
326         * @return the data formats available
327         */
328        Map<String, DataFormatType> getDataFormats();
329    }