camel git commit: Added bean-language.adoc and constant.adoc to camel-core docs directory

[ac...@apache.org]

Repository: camel
Updated Branches:
  refs/heads/master 0149a2239 -> e058d67bc


Added bean-language.adoc and constant.adoc to camel-core docs directory


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

Branch: refs/heads/master
Commit: e058d67bcbcf4317a88a5500c9cce1e7243ba513
Parents: 0149a22
Author: Andrea Cosentino <an...@gmail.com>
Authored: Mon May 2 09:07:44 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Mon May 2 09:08:44 2016 +0200

----------------------------------------------------------------------
 camel-core/src/main/docs/bean-language.adoc | 156 +++++++++++++++++++++++
 camel-core/src/main/docs/constant.adoc      |  41 ++++++
 2 files changed, 197 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/e058d67b/camel-core/src/main/docs/bean-language.adoc
----------------------------------------------------------------------
diff --git a/camel-core/src/main/docs/bean-language.adoc b/camel-core/src/main/docs/bean-language.adoc
new file mode 100644
index 0000000..573ef96
--- /dev/null
+++ b/camel-core/src/main/docs/bean-language.adoc
@@ -0,0 +1,156 @@
+[[BeanLanguage-BeanLanguage]]
+Bean Language
+~~~~~~~~~~~~~
+
+The purpose of the Bean Language is to be able to implement an
+link:expression.html[Expression] or link:predicate.html[Predicate] using
+a simple method on a bean.
+
+So the idea is you specify a bean name which will then be resolved in
+the link:registry.html[Registry] such as the link:spring.html[Spring]
+ApplicationContext then a method is invoked to evaluate the
+link:expression.html[Expression] or link:predicate.html[Predicate].
+
+If no method name is provided then one is attempted to be chosen using
+the rules for link:bean-binding.html[Bean Binding]; using the type of
+the message body and using any annotations on the bean methods.
+
+The link:bean-binding.html[Bean Binding] rules are used to bind the
+link:message.html[Message] Exchange to the method parameters; so you can
+annotate the bean to extract headers or other expressions such as
+link:xpath.html[XPath] or link:xquery.html[XQuery] from the message.
+
+[[BeanLanguage-UsingBeanExpressionsfromtheJavaDSL]]
+Using Bean Expressions from the Java DSL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[source,java]
+----------------------------------------------
+from("activemq:topic:OrdersTopic").
+  filter().method("myBean", "isGoldCustomer").
+    to("activemq:BigSpendersQueue");
+----------------------------------------------
+
+[[BeanLanguage-UsingBeanExpressionsfromXML]]
+Using Bean Expressions from XML
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[source,xml]
+--------------------------------------------------
+<route>
+  <from uri="activemq:topic:OrdersTopic"/>
+  <filter>
+    <method ref="myBean" method="isGoldCustomer"/>
+    <to uri="activemq:BigSpendersQueue"/>
+  </filter>
+</route>
+--------------------------------------------------
+
+*Bean attribute now deprecated*
+
+Note, the `bean` attribute of the method expression element is now
+deprecated. You should now make use of `ref` attribute instead.
+
+[[BeanLanguage-Writingtheexpressionbean]]
+Writing the expression bean
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The bean in the above examples is just any old Java Bean with a method
+called isGoldCustomer() that returns some object that is easily
+converted to a *boolean* value in this case, as its used as a predicate.
+
+So we could implement it like this...
+
+[source,java]
+----------------------------------------------------
+public class MyBean {
+  public boolean isGoldCustomer(Exchange exchange) {
+    ...
+  }
+}
+----------------------------------------------------
+
+We can also use the link:bean-integration.html[Bean Integration]
+annotations. For example you could do...
+
+[source,java]
+------------------------------------------------
+public boolean isGoldCustomer(String body) {...}
+------------------------------------------------
+
+or
+
+[source,java]
+----------------------------------------------------------------------------
+public boolean isGoldCustomer(@Header(name = "foo") Integer fooHeader) {...}
+----------------------------------------------------------------------------
+
+So you can bind parameters of the method to the Exchange, the
+link:message.html[Message] or individual headers, properties, the body
+or other expressions.
+
+[[BeanLanguage-Nonregistrybeans]]
+Non registry beans
+^^^^^^^^^^^^^^^^^^
+
+The link:bean-language.html[Bean Language] also supports invoking beans
+that isn't registered in the link:registry.html[Registry]. This is
+usable for quickly to invoke a bean from Java DSL where you don't need
+to register the bean in the link:registry.html[Registry] such as the
+link:spring.html[Spring] ApplicationContext.
+
+Camel can instantiate the bean and invoke the method if given a class or
+invoke an already existing instance. This is illustrated from the
+example below:
+
+[source,java]
+----------------------------------------------------------------------------------
+        from("activemq:topic:OrdersTopic").
+                filter().expression(BeanLanguage(MyBean.class, "isGoldCustomer")).
+                to("activemq:BigSpendersQueue");
+----------------------------------------------------------------------------------
+
+The 2nd parameter `isGoldCustomer` is an optional parameter to explicit
+set the method name to invoke. If not provided Camel will try to invoke
+the best suited method. If case of ambiguity Camel will thrown an
+Exception. In these situations the 2nd parameter can solve this problem.
+Also the code is more readable if the method name is provided. The 1st
+parameter can also be an existing instance of a Bean such as:
+
+[source,java]
+-----------------------------------------------------------------------------
+   private MyBean my;
+
+        from("activemq:topic:OrdersTopic").
+                filter().expression(BeanLanguage.bean(my, "isGoldCustomer")).
+                to("activemq:BigSpendersQueue");
+-----------------------------------------------------------------------------
+
+In Camel 2.2 onwards you can avoid the `BeanLanguage` and have it just
+as:
+
+[source,java]
+----------------------------------------------------------------
+   private MyBean my;
+
+        from("activemq:topic:OrdersTopic").
+                filter().expression(bean(my, "isGoldCustomer")).
+                to("activemq:BigSpendersQueue");
+----------------------------------------------------------------
+
+Which also can be done in a bit shorter and nice way:
+
+[source,java]
+------------------------------------------------------
+   private MyBean my;
+
+        from("activemq:topic:OrdersTopic").
+                filter().method(my, "isGoldCustomer").
+                to("activemq:BigSpendersQueue");
+------------------------------------------------------
+
+[[BeanLanguage-Dependencies]]
+Dependencies
+^^^^^^^^^^^^
+
+The Bean language is part of *camel-core*.

http://git-wip-us.apache.org/repos/asf/camel/blob/e058d67b/camel-core/src/main/docs/constant.adoc
----------------------------------------------------------------------
diff --git a/camel-core/src/main/docs/constant.adoc b/camel-core/src/main/docs/constant.adoc
new file mode 100644
index 0000000..b54df7d
--- /dev/null
+++ b/camel-core/src/main/docs/constant.adoc
@@ -0,0 +1,41 @@
+[[Constant-ConstantExpressionLanguage]]
+Constant Expression Language
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Constant Expression Language is really just a way to specify
+constant strings as a type of expression.
+
+[[Constant-Exampleusage]]
+Example usage
+^^^^^^^^^^^^^
+
+The setHeader element of the Spring DSL can utilize a constant
+expression like:
+
+[source,xml]
+------------------------------------------
+<route>
+  <from uri="seda:a"/>
+  <setHeader headerName="theHeader">
+    <constant>the value</constant>        
+  </setHeader>
+  <to uri="mock:b"/>     
+</route>
+------------------------------------------
+
+in this case, the link:message.html[Message] coming from the seda:a
+link:endpoint.html[Endpoint] will have 'theHeader' header set to the
+constant value 'the value'.
+
+And the same example using Java DSL:
+
+[source,java]
+--------------------------------------------------------------------------
+from("seda:a").setHeader("theHeader", constant("the value")).to("mock:b");
+--------------------------------------------------------------------------
+
+[[Constant-Dependencies]]
+Dependencies
+^^^^^^^^^^^^
+
+The Constant language is part of *camel-core*.