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
019import java.util.Collection;
020import java.util.Collections;
021import java.util.Map;
022import java.util.Optional;
023
024import org.apache.camel.component.extension.ComponentExtension;
025import org.apache.camel.spi.PropertyConfigurer;
026
027/**
028 * A <a href="http://camel.apache.org/component.html">component</a> is
029 * a factory of {@link Endpoint} objects.
030 */
031public interface Component extends CamelContextAware, Service {
032
033    /**
034     * Attempt to resolve an endpoint for the given URI if the component is
035     * capable of handling the URI.
036     * <p/>
037     * See {@link #useRawUri()} for controlling whether the passed in uri
038     * should be as-is (raw), or encoded (default).
039     * 
040     * @param uri the URI to create; either raw or encoded (default)
041     * @return a newly created {@link Endpoint} or null if this component cannot create
042     *         {@link Endpoint} instances using the given uri
043     * @throws Exception is thrown if error creating the endpoint
044     * @see #useRawUri()
045     */
046    Endpoint createEndpoint(String uri) throws Exception;
047
048    /**
049     * Attempt to resolve an endpoint for the given URI if the component is
050     * capable of handling the URI.
051     * <p/>
052     * See {@link #useRawUri()} for controlling whether the passed in uri
053     * should be as-is (raw), or encoded (default).
054     *
055     * @param uri the URI to create; either raw or encoded (default)
056     * @param parameters the parameters for the endpoint
057     * @return a newly created {@link Endpoint} or null if this component cannot create
058     *         {@link Endpoint} instances using the given uri
059     * @throws Exception is thrown if error creating the endpoint
060     * @see #useRawUri()
061     */
062    Endpoint createEndpoint(String uri, Map<String, Object> parameters) throws Exception;
063
064    /**
065     * Whether to use raw or encoded uri, when creating endpoints.
066     * <p/>
067     * <b>Notice:</b> When using raw uris, then the parameter values is raw as well.
068     *
069     * @return <tt>true</tt> to use raw uris, <tt>false</tt> to use encoded uris (default).
070     *
071     * @since Camel 2.11.0
072     */
073    boolean useRawUri();
074
075    /**
076     * Gets the component {@link PropertyConfigurer}.
077     *
078     * @return the configurer, or <tt>null</tt> if the component does not support using property configurer.
079     */
080    default PropertyConfigurer getComponentPropertyConfigurer() {
081        return null;
082    }
083
084    /**
085     * Gets the endpoint {@link PropertyConfigurer}.
086     *
087     * @return the configurer, or <tt>null</tt> if the endpoint does not support using property configurer.
088     */
089    default PropertyConfigurer getEndpointPropertyConfigurer() {
090        return null;
091    }
092
093    /**
094     * Gets a list of supported extensions.
095     *
096     * @return the list of extensions.
097     */
098    default Collection<Class<? extends ComponentExtension>> getSupportedExtensions() {
099        return Collections.emptyList();
100    }
101
102    /**
103     * Gets the extension of the given type.
104     *
105     * @param extensionType tye type of the extensions
106     * @return an optional extension
107     */
108    default <T extends ComponentExtension> Optional<T> getExtension(Class<T> extensionType) {
109        return Optional.empty();
110    }
111
112    /**
113     * Set the {@link Component} context if the component is an instance of {@link ComponentAware}.
114     */
115    static <T> T trySetComponent(T object, Component component) {
116        if (object instanceof ComponentAware) {
117            ((ComponentAware) object).setComponent(component);
118        }
119
120        return object;
121    }
122
123}