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 */
017package 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 */
025public 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}