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