Repository: camel Updated Branches: refs/heads/master b25ff047d -> 79ad2c802
Added camel-geocoder 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/79ad2c80 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/79ad2c80 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/79ad2c80 Branch: refs/heads/master Commit: 79ad2c802552740fc6db28ed80652b45cb92c5f1 Parents: b25ff04 Author: Andrea Cosentino <anco...@gmail.com> Authored: Wed Mar 30 15:44:59 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Wed Mar 30 15:45:56 2016 +0200 ---------------------------------------------------------------------- .../camel-geocoder/src/main/docs/geocoder.adoc | 163 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 164 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/79ad2c80/components/camel-geocoder/src/main/docs/geocoder.adoc ---------------------------------------------------------------------- diff --git a/components/camel-geocoder/src/main/docs/geocoder.adoc b/components/camel-geocoder/src/main/docs/geocoder.adoc new file mode 100644 index 0000000..550b456 --- /dev/null +++ b/components/camel-geocoder/src/main/docs/geocoder.adoc @@ -0,0 +1,163 @@ +[[Geocoder-GeocoderComponent]] +Geocoder Component +~~~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.12* + +The *geocoder:* component is used for looking up geocodes (latitude and +longitude) for a given address, or reverse lookup. The component uses +the https://code.google.com/p/geocoder-java/[Java API for Google +Geocoder] library. + +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-geocoder</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +------------------------------------------------------------ + +[[Geocoder-URIformat]] +URI format +^^^^^^^^^^ + +[source,java] +-------------------------------------------- +geocoder:address:name[?options] +geocoder:latlng:latitude,longitude[?options] +-------------------------------------------- + +[[Geocoder-Options]] +Options +^^^^^^^ + + +// component options: START +The Geocoder component has no options. +// component options: END + + + +// endpoint options: START +The Geocoder component supports 17 endpoint options which are listed below: + +[width="100%",cols="2s,1,1m,1m,5",options="header"] +|======================================================================= +| Name | Group | Default | Java Type | Description +| address | producer | | String | The geo address which should be prefixed with address: +| latlng | producer | | String | The geo latitude and longitude which should be prefixed with latlng: +| clientId | producer | | String | To use google premium with this client id +| clientKey | producer | | String | To use google premium with this client key +| headersOnly | producer | false | boolean | Whether to only enrich the Exchange with headers and leave the body as-is. +| language | producer | en | String | The language to use. +| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange +| httpClientConfigurer | advanced | | HttpClientConfigurer | Register a custom configuration strategy for new HttpClient instances created by producers or consumers such as to configure authentication mechanisms etc +| httpConnectionManager | advanced | | HttpConnectionManager | To use a custom HttpConnectionManager to manage connections +| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported). +| proxyAuthDomain | proxy | | String | Domain for proxy NTML authentication +| proxyAuthHost | proxy | | String | Optional host for proxy NTML authentication +| proxyAuthMethod | proxy | | String | Authentication method for proxy either as Basic Digest or NTLM. +| proxyAuthPassword | proxy | | String | Password for proxy authentication +| proxyAuthUsername | proxy | | String | Username for proxy authentication +| proxyHost | proxy | | String | The proxy host name +| proxyPort | proxy | | Integer | The proxy port number +|======================================================================= +// endpoint options: END + + +[[Geocoder-Exchangedataformat]] +Exchange data format +^^^^^^^^^^^^^^^^^^^^ + +Camel will deliver the body as a +`com.google.code.geocoder.model.GeocodeResponse` type. + + And if the address is `"current"` then the response is a String type +with a JSON representation of the current location. + +If the option `headersOnly` is set to `true` then the message body is +left as-is, and only headers will be added to the +link:exchange.html[Exchange]. + +[[Geocoder-MessageHeaders]] +Message Headers +^^^^^^^^^^^^^^^ + +[width="100%",cols="50%,50%",options="header",] +|======================================================================= +|Header |Description + +|`CamelGeoCoderStatus` |Mandatory. Status code from the geocoder library. If status is +`GeocoderStatus.OK` then additional headers is enriched + +|`CamelGeoCoderAddress` |The formatted address + +|`CamelGeoCoderLat` |The latitude of the location. + +|`CamelGeoCoderLng` |The longitude of the location. + +|`CamelGeoCoderLatlng` |The latitude and longitude of the location. Separated by comma. + +|`CamelGeoCoderCity` |The city long name. + +|`CamelGeoCoderRegionCode` |The region code. + +|`CamelGeoCoderRegionName` |The region name. + +|`CamelGeoCoderCountryLong` |The country long name. + +|`CamelGeoCoderCountryShort` |The country short name. +|======================================================================= + +Notice not all headers may be provided depending on available data and +mode in use (address vs latlng). + +[[Geocoder-Samples]] +Samples +^^^^^^^ + +In the example below we get the latitude and longitude for Paris, France + +[source,java] +----------------------------------------- + from("direct:start") + .to("geocoder:address:Paris, France") +----------------------------------------- + +If you provide a header with the `CamelGeoCoderAddress` then that +overrides the endpoint configuration, so to get the location of +Copenhagen, Denmark we can send a message with a headers as shown: + +[source,java] +------------------------------------------------------------------------------------------------------ +template.sendBodyAndHeader("direct:start", "Hello", GeoCoderConstants.ADDRESS, "Copenhagen, Denmark"); +------------------------------------------------------------------------------------------------------ + +To get the address for a latitude and longitude we can do: + +[source,java] +--------------------------------------------------------------------------------------------------------------------------------------------------- + from("direct:start") + .to("geocoder:latlng:40.714224,-73.961452") + .log("Location ${header.CamelGeocoderAddress} is at lat/lng: ${header.CamelGeocoderLatlng} and in country ${header.CamelGeoCoderCountryShort}") +--------------------------------------------------------------------------------------------------------------------------------------------------- + +Which will log + +[source,java] +-------------------------------------------------------------------------------------------------------------- +Location 285 Bedford Avenue, Brooklyn, NY 11211, USA is at lat/lng: 40.71412890,-73.96140740 and in country US +-------------------------------------------------------------------------------------------------------------- + +To get the current location you can use "current" as the address as +shown: + +[source,java] +----------------------------------- + from("direct:start") + .to("geocoder:address:current") +----------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/79ad2c80/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 82754a4..2659938 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -134,6 +134,7 @@ * [FTP](ftp.adoc) * [GAE](gae.adoc) * [Ganglia](ganglia.adoc) + * [Geocoder](geocoder.adoc) * [Ironmq](ironmq.adoc) * [JMS](jms.adoc) * [JMX](jmx.adoc)