[15/17] camel git commit: CAMEL-10721: connector docs

[da...@apache.org]

CAMEL-10721: connector docs


Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/f79d981f
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/f79d981f
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/f79d981f

Branch: refs/heads/master
Commit: f79d981f7c425fb4c504eaeda3e9814539aa5b1e
Parents: 9bf705d
Author: Claus Ibsen <da...@apache.org>
Authored: Thu Jan 19 09:22:57 2017 +0100
Committer: Claus Ibsen <da...@apache.org>
Committed: Thu Jan 19 11:00:00 2017 +0100

----------------------------------------------------------------------
 .../src/main/docs/connector-component.adoc      | 59 ++++++++++++++++++++
 1 file changed, 59 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/f79d981f/connectors/camel-connector/src/main/docs/connector-component.adoc
----------------------------------------------------------------------
diff --git a/connectors/camel-connector/src/main/docs/connector-component.adoc b/connectors/camel-connector/src/main/docs/connector-component.adoc
new file mode 100644
index 0000000..be13741
--- /dev/null
+++ b/connectors/camel-connector/src/main/docs/connector-component.adoc
@@ -0,0 +1,59 @@
+## 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 calender 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 is 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`.
+
+You can find an example using these connectors in the `foo-bar-wine-example` in the `connectors` directory.
+
+
+### 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.
\ No newline at end of file