camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acosent...@apache.org
Subject [1/6] camel git commit: Added camel-apns docs to gitbook
Date Tue, 26 Jan 2016 10:39:47 GMT
Repository: camel
Updated Branches:
  refs/heads/master 3861ba00b -> 3437b3ed7


Added camel-apns docs to gitbook


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

Branch: refs/heads/master
Commit: aadade78cc7534548301c77a16feed4a329c66d5
Parents: 46baa9f
Author: Andrea Cosentino <ancosen@gmail.com>
Authored: Tue Jan 26 09:59:02 2016 +0100
Committer: Andrea Cosentino <ancosen@gmail.com>
Committed: Tue Jan 26 11:38:16 2016 +0100

----------------------------------------------------------------------
 components/camel-amqp/src/main/docs/amqp.adoc | 168 ++++++++++++
 components/camel-apns/src/main/docs/apns.adoc | 294 +++++++++++++++++++++
 docs/user-manual/en/SUMMARY.md                |   1 +
 3 files changed, 463 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/aadade78/components/camel-amqp/src/main/docs/amqp.adoc
----------------------------------------------------------------------
diff --git a/components/camel-amqp/src/main/docs/amqp.adoc b/components/camel-amqp/src/main/docs/amqp.adoc
new file mode 100644
index 0000000..5526dce
--- /dev/null
+++ b/components/camel-amqp/src/main/docs/amqp.adoc
@@ -0,0 +1,168 @@
+[[AMQP-AMQP]]
+AMQP
+~~~~
+
+The *amqp:* component supports the http://www.amqp.org/[AMQP 1.0
+protocol] using the JMS Client API of the http://qpid.apache.org/[Qpid]
+project. In case you want to use AMQP 0.9 (in particular RabbitMQ) you
+might also be interested in the link:rabbitmq.html[Camel RabbitMQ]
+component. Please keep in mind that prior to the Camel 2.17.0 AMQP
+component supported AMQP 0.9 and above, however since Camel 2.17.0 it
+supports only AMQP 1.0.
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this component:
+
+[source,xml]
+------------------------------------------------------------------------------------------------
+<dependency>
+    <groupId>org.apache.camel</groupId>
+    <artifactId>camel-amqp</artifactId>
+    <version>${camel.version}</version> <!-- use the same version as your
Camel core version -->
+</dependency>
+------------------------------------------------------------------------------------------------
+
+[[AMQP-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source,java]
+---------------------------------------------
+amqp:[queue:|topic:]destinationName[?options]
+---------------------------------------------
+
+[[AMQP-AMQPOptions]]
+AMQP Options
+^^^^^^^^^^^^
+
+You can specify all of the various configuration options of the
+link:../../../../camel-jms/src/main/docs/readme.html[JMS] component after the destination
name.
+
+[[AMQP-Usage]]
+Usage
+^^^^^
+
+As AMQP component is inherited from JMS component, the usage of the
+former is almost identical to the latter:
+
+*Using AMQP component*
+
+[source,java]
+------------------------------------
+// Consuming from AMQP queue
+from("amqp:queue:incoming").
+  to(...);
+ 
+// Sending message to the AMQP topic
+from(...).
+  to("amqp:topic:notify");
+------------------------------------
+
+[[AMQP-ConfiguringAMQPcomponent]]
+Configuring AMQP component
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Starting from the Camel 2.16.1 you can also use the
+`AMQPComponent#amqp10Component(String connectionURI)` factory method to
+return the AMQP 1.0 component with the pre-configured topic prefix: 
+
+*Creating AMQP 1.0 component*
+
+[source,java]
+-----------------------------------------------------------------------------------------
+ AMQPComponent amqp = AMQPComponent.amqp10Component("amqp://guest:guest@localhost:5672");
+-----------------------------------------------------------------------------------------
+
+Keep in mind that starting from the
+Camel 2.17 the `AMQPComponent#amqp10Component(String connectionURI)` factory
+method has been deprecated on the behalf of the
+`AMQPComponent#amqpComponent(String connectionURI)`: 
+
+*Creating AMQP 1.0 component*
+
+[source,java]
+--------------------------------------------------------------------------------------------------------
+AMQPComponent amqp = AMQPComponent.amqpComponent("amqp://localhost:5672");
+ 
+AMQPComponent authorizedAmqp = AMQPComponent.amqpComponent("amqp://localhost:5672", "user",
"password");
+--------------------------------------------------------------------------------------------------------
+
+Starting from Camel 2.17, in order to automatically configure the AMQP
+component, you can also add an instance
+of `org.apache.camel.component.amqp.AMQPConnectionDetails` to the
+registry. For example for Spring Boot you just have to define bean:
+
+*AMQP connection details auto-configuration*
+
+[source,java]
+-------------------------------------------------------------------------------------
+@Bean
+AMQPConnectionDetails amqpConnection() {
+  return new AMQPConnectionDetails("amqp://lcoalhost:5672"); 
+}
+ 
+@Bean
+AMQPConnectionDetails securedAmqpConnection() {
+  return new AMQPConnectionDetails("amqp://lcoalhost:5672", "username", "password"); 
+}
+-------------------------------------------------------------------------------------
+
+ 
+
+You can also rely on the link:properties.html[Camel properties] to read
+the AMQP connection details. Factory
+method `AMQPConnectionDetails.discoverAMQP()` attempts to read Camel
+properties in a Kubernetes-like convention, just as demonstrated on the
+snippet below:
+
+ 
+
+*AMQP connection details auto-configuration*
+
+[source,java]
+-----------------------------------------------
+export AMQP_SERVICE_HOST = "mybroker.com"
+export AMQP_SERVICE_PORT = "6666"
+export AMQP_SERVICE_USERNAME = "username"
+export AMQP_SERVICE_PASSWORD = "password"
+ 
+...
+ 
+@Bean
+AMQPConnectionDetails amqpConnection() {
+  return AMQPConnectionDetails.discoverAMQP(); 
+}
+-----------------------------------------------
+
+[[AMQP-Usingtopics]]
+Using topics
+^^^^^^^^^^^^
+
+To have using topics working with `camel-amqp` you need to configure the
+component to use `topic://` as topic prefix, as shown below:
+
+[source,java]
+-------------------------------------------------------------------------------------------------------------------------------
+ <bean id="amqp" class="org.apache.camel.component.amqp.AmqpComponent">
+        <property name="connectionFactory">
+          <bean class="org.apache.qpid.amqp_1_0.jms.impl.ConnectionFactoryImpl" factory-method="createFromURL">
+            <constructor-arg index="0" type="java.lang.String" value="amqp://localhost:5672"
/>
+            <property name="topicPrefix" value="topic://" />  <!-- only necessary
when connecting to ActiveMQ over AMQP 1.0 -->
+          </bean>
+        </property>
+ </bean>
+-------------------------------------------------------------------------------------------------------------------------------
+
+Keep in mind that both  `AMQPComponent#amqpComponent()` methods and
+`AMQPConnectionDetails` pre-configure the component with the topic
+prefix, so you don't have to configure it explicitly.
+
+[[AMQP-SeeAlso]]
+See Also
+^^^^^^^^
+
+* link:configuring-camel.html[Configuring Camel]
+* link:component.html[Component]
+* link:endpoint.html[Endpoint]
+* link:getting-started.html[Getting Started]
+

http://git-wip-us.apache.org/repos/asf/camel/blob/aadade78/components/camel-apns/src/main/docs/apns.adoc
----------------------------------------------------------------------
diff --git a/components/camel-apns/src/main/docs/apns.adoc b/components/camel-apns/src/main/docs/apns.adoc
new file mode 100644
index 0000000..ada0bae
--- /dev/null
+++ b/components/camel-apns/src/main/docs/apns.adoc
@@ -0,0 +1,294 @@
+[[APNS-ApnsComponent]]
+Apns Component
+~~~~~~~~~~~~~~
+
+*Available as of Camel 2.8*
+
+The *apns* component is used for sending notifications to iOS devices.
+The apns components use https://github.com/notnoop/java-apns[javapns]
+library. +
+ The component supports sending notifications to Apple Push Notification
+Servers (APNS) and consuming feedback from the servers.
+
+The consumer is configured with 3600 seconds for polling by default
+because it is a best practice to consume feedback stream from Apple Push
+Notification Servers only from time to time. For example: every 1 hour
+to avoid flooding the servers.
+
+The feedback stream gives informations about inactive devices. You only
+need to get this informations every some hours if your mobile
+application is not a heavily used one.
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this component:
+
+[source,xml]
+------------------------------------------------------------
+<dependency>
+    <groupId>org.apache.camel</groupId>
+    <artifactId>camel-apns</artifactId>
+    <version>x.x.x</version>
+    <!-- use the same version as your Camel core version -->
+</dependency>
+------------------------------------------------------------
+
+[[APNS-URIformat]]
+URI format
+^^^^^^^^^^
+
+To send notifications:
+
+[source,java]
+---------------------
+apns:notify[?options]
+---------------------
+
+To consume feedback:
+
+[source,java]
+-----------------------
+apns:consumer[?options]
+-----------------------
+
+[[APNS-Options]]
+Options
+^^^^^^^
+
+[[APNS-Producer]]
+Producer
+++++++++
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Property |Default |Description
+|`tokens` |        |Empty by default. Configure this property in case you want to statically
+declare tokens related to devices you want to notify. Tokens are
+separated by comma.
+|=======================================================================
+
+[[APNS-Consumer]]
+Consumer
+++++++++
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Property |Default |Description
+|`delay` |`3600` |Delay in seconds between each poll.
+
+|`initialDelay` |`10` |Seconds before polling starts.
+
+|`timeUnit` |`SECONDS` |Time Unit for polling.
+
+|`userFixedDelay` |`true` |If `true`, use fixed delay between pools, otherwise fixed rate
is used.
+See
+http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/ScheduledExecutorService.html[ScheduledExecutorService]
+in JDK for details.
+|=======================================================================
+
+You can append query options to the URI in the following format,
+`?option=value&option=value&...`
+
+[[APNS-Component]]
+Component
++++++++++
+
+The `ApnsComponent` must be configured with a
+`com.notnoop.apns.ApnsService`. The service can be created and
+configured using the
+`org.apache.camel.component.apns.factory.ApnsServiceFactory`. See
+further below for an example. And as well in the
+https://svn.apache.org/repos/asf/camel/trunk/components/camel-apns/[test
+source code].
+
+[[APNS-Exchangedataformat]]
+Exchange data format
+^^^^^^^^^^^^^^^^^^^^
+
+When Camel will fetch feedback data corresponding to inactive devices,
+it will retrieve a List of InactiveDevice objects. Each InactiveDevice
+object of the retrieved list will be setted as the In body, and then
+processed by the consumer endpoint.
+
+[[APNS-MessageHeaders]]
+Message Headers
+^^^^^^^^^^^^^^^
+
+Camel Apns uses these headers.
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Property |Default |Description
+|`CamelApnsTokens` | |Empty by default.
+|`CamelApnsMessageType` |`STRING, PAYLOAD, APNS_NOTIFICATION`  |In case you choose PAYLOAD
for the message type, then the message will
+be considered as a APNS payload and sent as is. In case you choose
+STRING, message will be converted as a APNS payload. From *Camel 2.16*
+onwards APNS_NOTIFICATION is used for sending message body as
+com.notnoop.apns.ApnsNotification types.
+|=======================================================================
+
+[[APNS-ApnsServiceFactorybuildercallback]]
+ApnsServiceFactory builder callback
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`ApnsServiceFactory` comes with the empty callback method that could be
+used to configure (or even replace) the default `ApnsServiceBuilder`
+instance. The signature of the method could look as follows:
+
+[source,java]
+----------------------------------------------------------------------------------------
+protected ApnsServiceBuilder configureServiceBuilder(ApnsServiceBuilder serviceBuilder);
+----------------------------------------------------------------------------------------
+
+And could be used like as follows:
+
+[source,java]
+-------------------------------------------------------------------------------------------
+ApnsServiceFactory proxiedApnsServiceFactory = new ApnsServiceFactory(){
+  
+  @Override
+  protected ApnsServiceBuilder configureServiceBuilder(ApnsServiceBuilder serviceBuilder)
{
+    return serviceBuilder.withSocksProxy("my.proxy.com", 6666);
+  }
+
+};
+-------------------------------------------------------------------------------------------
+
+[[APNS-Samples]]
+Samples
+^^^^^^^
+
+[[APNS-CamelXmlroute]]
+Camel Xml route
++++++++++++++++
+
+[source,xml]
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------
+<beans xmlns="http://www.springframework.org/schema/beans"
+       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xmlns:camel="http://camel.apache.org/schema/spring"
+       xsi:schemaLocation="
+        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
+        http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">
+
+    <!-- Replace by desired values -->
+    <bean id="apnsServiceFactory" class="org.apache.camel.component.apns.factory.ApnsServiceFactory">
+
+        <!-- Optional configuration of feedback host and port -->
+        <!-- <property name="feedbackHost" value="localhost" /> -->
+        <!-- <property name="feedbackPort" value="7843" /> -->
+
+        <!-- Optional configuration of gateway host and port -->
+        <!-- <property name="gatewayHost" value="localhost" /> -->
+        <!-- <property name="gatewayPort" value="7654" /> -->
+
+        <!-- Declaration of certificate used -->
+                <!-- from Camel 2.11 onwards you can use prefix: classpath:, file: to
refer to load the certificate from classpath or file. Default it classpath -->
+        <property name="certificatePath" value="certificate.p12" />
+        <property name="certificatePassword" value="MyCertPassword" />
+
+        <!-- Optional connection strategy - By Default: No need to configure -->
+        <!-- Possible options: NON_BLOCKING, QUEUE, POOL or Nothing -->
+        <!-- <property name="connectionStrategy" value="POOL" /> -->
+        <!-- Optional pool size -->
+        <!-- <property name="poolSize" value="15" /> -->
+
+        <!-- Optional connection strategy - By Default: No need to configure -->
+        <!-- Possible options: EVERY_HALF_HOUR, EVERY_NOTIFICATION or Nothing (Corresponds
to NEVER javapns option) -->
+        <!-- <property name="reconnectionPolicy" value="EVERY_HALF_HOUR" /> -->
+    </bean>
+
+    <bean id="apnsService" factory-bean="apnsServiceFactory" factory-method="getApnsService"
/>
+
+    <!-- Replace this declaration by wanted configuration -->
+    <bean id="apns" class="org.apache.camel.component.apns.ApnsComponent">
+        <property name="apnsService" ref="apnsService" />
+    </bean>
+
+    <camelContext id="camel-apns-test" xmlns="http://camel.apache.org/schema/spring">
+            <route id="apns-test">
+                    <from uri="apns:consumer?initialDelay=10&amp;delay=3600&amp;timeUnit=SECONDS"
/>
+                    <to uri="log:org.apache.camel.component.apns?showAll=true&amp;multiline=true"
/>
+                    <to uri="mock:result" />
+            </route>
+    </camelContext>
+
+</beans>
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+[[APNS-CamelJavaroute]]
+Camel Java route
+++++++++++++++++
+
+[[APNS-Createcamelcontextanddeclareapnscomponentprogrammatically]]
+Create camel context and declare apns component programmatically
+
+[source,java]
+----------------------------------------------------------------------------------
+    protected CamelContext createCamelContext() throws Exception {
+        CamelContext camelContext = super.createCamelContext();
+
+        ApnsServiceFactory apnsServiceFactory = new ApnsServiceFactory();
+        apnsServiceFactory.setCertificatePath("classpath:/certificate.p12");
+        apnsServiceFactory.setCertificatePassword("MyCertPassword");
+
+        ApnsService apnsService = apnsServiceFactory.getApnsService(camelContext);
+
+        ApnsComponent apnsComponent = new ApnsComponent(apnsService);
+        camelContext.addComponent("apns", apnsComponent);
+
+        return camelContext;
+    }
+----------------------------------------------------------------------------------
+
+[[APNS-ApnsProducer-iOStargetdevicedynamicallyconfiguredviaheader:"CamelApnsTokens"]]
+ApnsProducer - iOS target device dynamically configured via header:
+`"CamelApnsTokens"`
+
+[source,java]
+---------------------------------------------------------------------------------------
+    protected RouteBuilder createRouteBuilder() throws Exception {
+        return new RouteBuilder() {
+            public void configure() throws Exception {
+                from("direct:test")
+                    .setHeader(ApnsConstants.HEADER_TOKENS, constant(IOS_DEVICE_TOKEN))
+                    .to("apns:notify");
+                }
+        }
+    }
+---------------------------------------------------------------------------------------
+
+[[APNS-ApnsProducer-iOStargetdevicestaticallyconfiguredviauri]]
+ApnsProducer - iOS target device statically configured via uri
+
+[source,java]
+------------------------------------------------------------------
+    protected RouteBuilder createRouteBuilder() throws Exception {
+        return new RouteBuilder() {
+            public void configure() throws Exception {
+                from("direct:test").
+                to("apns:notify?tokens=" + IOS_DEVICE_TOKEN);
+            }
+        };
+    }
+------------------------------------------------------------------
+
+[[APNS-ApnsConsumer]]
+ApnsConsumer
+
+[source,java]
+--------------------------------------------------------------------------
+from("apns:consumer?initialDelay=10&delay=3600&timeUnit=SECONDS")
+    .to("log:com.apache.camel.component.apns?showAll=true&multiline=true")
+    .to("mock:result");
+--------------------------------------------------------------------------
+
+[[APNS-SeeAlso]]
+See Also
+^^^^^^^^
+
+* http://camel.apache.org/component.html[Component]
+* http://camel.apache.org/endpoint.html[Endpoint]
+*
+http://blog.xebia.fr/2010/09/30/creer-un-composant-apache-camel-de-connexion-a-lapns-1-sur-3/[Blog
+about using APNS (in french)]
+

http://git-wip-us.apache.org/repos/asf/camel/blob/aadade78/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index cc95e01..275b1a0 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -72,6 +72,7 @@
 	* [Async Http Client (AHC)](ahc.adoc)
 	* [AHC Websocket (AHC-WS)](ahc-ws.adoc)
 	* [Amqp](amqp.adoc)
+	* [Apns](apns.adoc)
 	* [Atom](atom.adoc)
 	* [CDI](cdi.adoc)
 	* [JMS](jms.adoc) 


Mime
View raw message