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    /**
020     * A <a href="http://camel.apache.org/component.html">component</a> is
021     * a factory of {@link Endpoint} objects.
022     * 
023     * @version 
024     */
025    public interface Component extends CamelContextAware {
026    
027        /**
028         * Attempt to resolve an endpoint for the given URI if the component is
029         * capable of handling the URI.
030         * <p/>
031         * See {@link #useRawUri()} for controlling whether the passed in uri
032         * should be as-is (raw), or encoded (default).
033         * 
034         * @param uri the URI to create; either raw or encoded (default)
035         * @return a newly created {@link Endpoint} or null if this component cannot create
036         *         {@link Endpoint} instances using the given uri
037         * @throws Exception is thrown if error creating the endpoint
038         * @see #useRawUri()
039         */
040        Endpoint createEndpoint(String uri) throws Exception;
041    
042        /**
043         * Whether to use raw or encoded uri, when creating endpoints.
044         * <p/>
045         * <b>Notice:</b> When using raw uris, then the parameter values is raw as well.
046         *
047         * @return <tt>true</tt> to use raw uris, <tt>false</tt> to use encoded uris (default).
048         *
049         * @since Camel 2.11.0
050         */
051        boolean useRawUri();
052    
053        /**
054         * Attempt to create a configuration object from the given uri
055         *
056         * @param uri the configuration URI
057         * @return a newly created {@link EndpointConfiguration}
058         * @throws Exception is thrown if the configuration URI is invalid
059         *
060         * @since Camel 2.9.0
061         */
062        EndpointConfiguration createConfiguration(String uri) throws Exception;
063    
064        /**
065         * Creates a configuration helper object for a component that lets you configure the various
066         * URI and parameter values; then create the full URI for it, create a new Endpoint from it
067         * or configure an existing Endpoint from the values.
068         *
069         * This method is intended to be used in cases where there is not yet a full URI to
070         * configure an endpoint yet; but rather there are a number of parameters to configure
071         * to then build up a new URI or directly create an Endpoint from the parameter values.
072         */
073        ComponentConfiguration createComponentConfiguration();
074    }