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 <[email protected]> Authored: Tue Jan 26 09:59:02 2016 +0100 Committer: Andrea Cosentino <[email protected]> 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&delay=3600&timeUnit=SECONDS" /> + <to uri="log:org.apache.camel.component.apns?showAll=true&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)
