## Connector Component

The connector component is an abstract component that is used as a building block to build a Camel connector.


### What is a Camel connector?

A Camel connector is a simplified setup of any existing Camel component. The idea is to be able to pre-configure
  a connector to a specific use-case, such as _add contact to salesforce_, or _add calendar entry_,
  or _new leads from twitter_.

The existing Camel components are generic and have many options. Therefore to use any of these components you
   need to understand how to use and setup all these options.

### How it works

The connector is based on one of the existing Camel components (or 3rd party component) by which you can specify
in a `camel-connector.json` file which options to pre-select and as well specify other default values etc.

Then the `camel-connector-maven-plugin` Maven plugin will build this as a Camel component,
so at runtime its just a regular Camel component.

Because connectors are just regular Camel component there is no problem running them in Camel applications.

In addition all existing JMX, tooling et all just sees this as Camel components and can use that.
Also at design time, for example the Apache Camel IDEA plugin will see the connector as a 3rd party Camel component
and offer code assistance to it etc.

You can have as many connectors you want, and a Camel component can have many connectors.
For example you can have multiple connectors to the `camel-salesforce` component, where each connectors
is specialized to do a different use-case with Salesforce.


### How to create a Connector

You can use the Maven archetype `camel-archetype-connector` to create a new connector. You would need to specify
some values as input to select the existing Camel component to use as base, and then in addition the name and title
of the connector, and a few other values as well.

You can also copy the existing examples from the `connectors` directory where the following connectors examples are provided:

- `foo-connector` - A connector that is based on the Timer component from `camel-core`.
- `bar-connector` - A connector that is based on the 3rd party `beverage-component`.
- `wine-connector` - Another connector that is based on the 3rd party `beverage-component`.
- `twitter-find` - A connector based on twitter to search for keywords.

You can find an example using these connectors in the `foo-bar-wine-example` in the `connectors` directory.


### Setting up connector in Maven

To build a connector you need to at least include the following dependencies in the Maven pom.xml file

[source,xml]
------------
    <!-- camel-connector -->
    <dependency>
      <groupId>org.apache.camel</groupId>
      <artifactId>camel-connector</artifactId>
    </dependency>

    <!-- camel and spring boot compiler plugins -->
    <dependency>
      <groupId>org.apache.camel</groupId>
      <artifactId>apt</artifactId>
    </dependency>
------------

And these following Maven plugins:

[source,xml]
------------
      <!-- generate components meta-data and validate component includes documentation etc -->
      <plugin>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-package-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>prepare</id>
            <goals>
              <goal>prepare-components</goal>
            </goals>
            <phase>generate-resources</phase>
          </execution>
          <execution>
            <id>validate</id>
            <goals>
              <goal>validate-components</goal>
            </goals>
            <phase>prepare-package</phase>
          </execution>
        </executions>
      </plugin>

      <!-- generate connector -->
      <plugin>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-connector-maven-plugin</artifactId>
        <version>${camel.version}</version>
        <executions>
          <execution>
            <id>connector</id>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
------------


### Spring Boot compliant

A Camel connector works great with Spring Boot. If a connector has been configured to allow configuration on the component and/or endpoint level which is done in the `camel-connector.json` file, such as

      "componentOptions" : [ "consumerKey", "consumerSecret", "accessToken", "accessTokenSecret" ],
      "endpointOptions" : [ "keywords" ],

Then the `camel-connector-maven-plugin` will be able to generate Spring Boot auto configuration for these options.
This allows users to easily configure these options if using Spring Boot with the connector.

NOTE: There's no distinction between component/endpoint options on spring-boot auto configuration side so all the options are flattered to a single namespace thus they appear as connector options and then the connector figures out where they should be applied.

TIP: The options configured through spring-boot auto configuration classes can be overridden by standard endpoint options.

To enable Spring Boot generation you need to enable this in the `camel-connector-maven-plugin` by adding
an `<execution>` with the `prepare-spring-boot-auto-configuration` goal:

[source,xml]
------------
    <!-- generate connector -->
    <plugin>
      <groupId>org.apache.camel</groupId>
      <artifactId>camel-connector-maven-plugin</artifactId>
      <version>${camel.version}</version>
      <executions>
        <execution>
          <id>boot</id>
          <goals>
            <goal>prepare-spring-boot-auto-configuration</goal>
          </goals>
        </execution>
        <execution>
          <id>connector</id>
          <goals>
            <goal>jar</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
------------

You will also need to add the `spring-boot-configuration-processor` in the Maven pom.xml file

[source,xml]
------------
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-configuration-processor</artifactId>
      <version>${spring-boot.version}</version>
    </dependency>
------------

An example on how to configure a component in spring boot can be taken from the twitter-find connector:

[source]
------------
    camel.connector.twitter-find.consumer-key = ...
    camel.connector.twitter-find.consumer-secret = ...
    camel.connector.twitter-find.access-token = ...
    camel.connector.twitter-find.access-token-secret = ...
    camel.connector.twitter-find.keywords = apache-camel
------------

You may need to instantiate multiple instance of the connector i.e. to use different logins and this is now possible through the 'configurations' parameters:

[source]
------------
    camel.connector.twitter-find.configurations.tw-find1.consumer-key = ...
    camel.connector.twitter-find.configurations.tw-find1.consumer-secret = ...
    camel.connector.twitter-find.configurations.tw-find1.access-token = ...
    camel.connector.twitter-find.configurations.tw-find1.access-token-secret = ...
    camel.connector.twitter-find.configurations.tw-find1.keywords = apache-camel

    camel.connector.twitter-find.configurations.tw-find2.consumer-key = ...
    camel.connector.twitter-find.configurations.tw-find2.consumer-secret = ...
    camel.connector.twitter-find.configurations.tw-find2.access-token = ...
    camel.connector.twitter-find.configurations.tw-find2.access-token-secret = ...
    camel.connector.twitter-find.configurations.tw-find2.keywords = apache-karaf
------------

This would create two instances of the twitter-find connector each one configured with its own list of options.
You can now use the new connectors as standard components like:

[source,java]
------------
    @Component
    public class MyRouteBuilder implements RouteBuilder{
        public void configure() throws Exception {
            from("tw-find1")
                .log("On account 1 I got:  ${body}")
            from("tw-find2")
                .log("On account 2 I got: ${body}")
        }
    }
------------


### Input and Output Data Type

Every connector *must* define which input and output data type are in use.

The following data types are in use:

[width="100%",cols="2m,8",options="header"]
|=========================================
| Data Type | Description
| none | No data
| any | Supports any kind of data. You can also use `*` instead of `any`
| java | Java data. An optional sub type can define the fully qualified class name such as `java:com.foo.MyCustomer`.
| text | Text based data
| xml | XML based data. An option sub type can define the XML namespace of the XML root element.
| json | JSon based data. An option sub type can define the fully qualified class name of a Java POJO that maps to this JSon structure.
|=========================================

For example to accept any incoming data type and output Java as `com.foo.MyCustomer` you would
configure the `camel-connector.json` file:

    "inputDataType": "any",
    "outputDataType": "java:com.foo.MyCustomer",


### The connectors schema file

A connector has a schema file `camel-connector.json` located in `src/main/resources` directory.

This schema holds the information where you can pre-configure and specify which options a connector should offer.

The options the connector can provide is a limited set of all the existing options that comes from the Camel component
its based upon. Each option can then also be pre-configured with a default-value.

To understand this schema file, its easier to study those existing connectors from the `connectors` directory.
