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