http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-protobuf/src/main/docs/protobuf-dataformat.adoc ---------------------------------------------------------------------- diff --git a/components/camel-protobuf/src/main/docs/protobuf-dataformat.adoc b/components/camel-protobuf/src/main/docs/protobuf-dataformat.adoc new file mode 100644 index 0000000..ea8ec7a --- /dev/null +++ b/components/camel-protobuf/src/main/docs/protobuf-dataformat.adoc @@ -0,0 +1,160 @@ +[[Protobuf-Protobuf-ProtocolBuffers]] +Protobuf - Protocol Buffers +--------------------------- + +"Protocol Buffers - Google's data interchange format" + +INFO: Available from Camel 2.2 + +Camel provides a link:data-format.html[Data Format] to serialse between +Java and the Protocol Buffer protocol. The project's site details why +you may wish to +http://code.google.com/apis/protocolbuffers/docs/overview.html[choose +this format over xml]. Protocol Buffer is language-neutral and +platform-neutral, so messages produced by your Camel routes may be +consumed by other language implementations. + +http://code.google.com/apis/protocolbuffers/[API Site] + + http://code.google.com/p/protobuf/[Protobuf Implementation] + + +http://code.google.com/apis/protocolbuffers/docs/javatutorial.html[Protobuf +Java Tutorial] + +[[Protobuf-Protobufoverview]] +Protobuf overview +~~~~~~~~~~~~~~~~~ + +This quick overview of how to use Protobuf. For more detail see the +http://code.google.com/apis/protocolbuffers/docs/javatutorial.html[complete +tutorial] + +[[Protobuf-Definingtheprotoformat]] +Defining the proto format +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first step is to define the format for the body of your exchange. +This is defined in a .proto file as so: + +*addressbook.proto* + +[source,java] +------------------------------------------------------------ + +package org.apache.camel.component.protobuf; + +option java_package = "org.apache.camel.component.protobuf"; +option java_outer_classname = "AddressBookProtos"; + +message Person { + required string name = 1; + required int32 id = 2; + optional string email = 3; + + enum PhoneType { + MOBILE = 0; + HOME = 1; + WORK = 2; + } + + message PhoneNumber { + required string number = 1; + optional PhoneType type = 2 [default = HOME]; + } + + repeated PhoneNumber phone = 4; +} + +message AddressBook { + repeated Person person = 1; +} +------------------------------------------------------------ + +[[Protobuf-GeneratingJavaclasses]] +Generating Java classes +^^^^^^^^^^^^^^^^^^^^^^^ + +The Protobuf SDK provides a compiler which will generate the Java +classes for the format we defined in our .proto file. You can run the +compiler for any additional supported languages you require. + +`protoc --java_out=. ./addressbook.proto` + +This will generate a single Java class named AddressBookProtos which +contains inner classes for Person and AddressBook. Builders are also +implemented for you. The generated classes implement +com.google.protobuf.Message which is required by the serialisation +mechanism. For this reason it important that only these classes are used +in the body of your exchanges. Camel will throw an exception on route +creation if you attempt to tell the link:data-format.html[Data Format] +to use a class that does not implement com.google.protobuf.Message. Use +the generated builders to translate the data from any of your existing +domain classes. + +[[Protobuf-JavaDSL]] +Java DSL +~~~~~~~~ + +You can use create the ProtobufDataFormat instance and pass it to Camel +DataFormat marshal and unmarsha API like this. + +[source,java] +----------------------------------------------------------------------------------- + ProtobufDataFormat format = new ProtobufDataFormat(Person.getDefaultInstance()); + + from("direct:in").marshal(format); + from("direct:back").unmarshal(format).to("mock:reverse"); +----------------------------------------------------------------------------------- + +Or use the DSL protobuf() passing the unmarshal default instance or +default instance class name like this. + +[source,java] +-------------------------------------------------------------------------------------------------- + // You don't need to specify the default instance for protobuf marshaling + from("direct:marshal").marshal().protobuf(); + from("direct:unmarshalA").unmarshal(). + protobuf("org.apache.camel.dataformat.protobuf.generated.AddressBookProtos$Person"). + to ("mock:reverse"); + + from("direct:unmarshalB").unmarshal().protobuf(Person.getDefaultInstance()).to("mock:reverse"); +-------------------------------------------------------------------------------------------------- + +[[Protobuf-SpringDSL]] +Spring DSL +~~~~~~~~~~ + +The following example shows how to use Castor to unmarshal using Spring +configuring the protobuf data type + +[source,java] +---------------------------------------------------------------------------------------------------------- +<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";> + <route> + <from uri="direct:start"/> + <unmarshal> + <protobuf instanceClass="org.apache.camel.dataformat.protobuf.generated.AddressBookProtos$Person" /> + </unmarshal> + <to uri="mock:result"/> + </route> +</camelContext> +---------------------------------------------------------------------------------------------------------- + +[[Protobuf-Dependencies]] +Dependencies +^^^^^^^^^^^^ + +To use Protobuf in your camel routes you need to add the a dependency on +*camel-protobuf* which implements this data format. + +If you use maven you could just add the following to your pom.xml, +substituting the version number for the latest & greatest release (see +link:download.html[the download page for the latest versions]). + +[source,java] +----------------------------------------- +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-protobuf</artifactId> + <version>2.2.0</version> +</dependency> +-----------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-protobuf/src/main/docs/protobuf.adoc ---------------------------------------------------------------------- diff --git a/components/camel-protobuf/src/main/docs/protobuf.adoc b/components/camel-protobuf/src/main/docs/protobuf.adoc deleted file mode 100644 index ea8ec7a..0000000 --- a/components/camel-protobuf/src/main/docs/protobuf.adoc +++ /dev/null @@ -1,160 +0,0 @@ -[[Protobuf-Protobuf-ProtocolBuffers]] -Protobuf - Protocol Buffers ---------------------------- - -"Protocol Buffers - Google's data interchange format" - -INFO: Available from Camel 2.2 - -Camel provides a link:data-format.html[Data Format] to serialse between -Java and the Protocol Buffer protocol. The project's site details why -you may wish to -http://code.google.com/apis/protocolbuffers/docs/overview.html[choose -this format over xml]. Protocol Buffer is language-neutral and -platform-neutral, so messages produced by your Camel routes may be -consumed by other language implementations. - -http://code.google.com/apis/protocolbuffers/[API Site] + - http://code.google.com/p/protobuf/[Protobuf Implementation] + - -http://code.google.com/apis/protocolbuffers/docs/javatutorial.html[Protobuf -Java Tutorial] - -[[Protobuf-Protobufoverview]] -Protobuf overview -~~~~~~~~~~~~~~~~~ - -This quick overview of how to use Protobuf. For more detail see the -http://code.google.com/apis/protocolbuffers/docs/javatutorial.html[complete -tutorial] - -[[Protobuf-Definingtheprotoformat]] -Defining the proto format -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The first step is to define the format for the body of your exchange. -This is defined in a .proto file as so: - -*addressbook.proto* - -[source,java] ------------------------------------------------------------- - -package org.apache.camel.component.protobuf; - -option java_package = "org.apache.camel.component.protobuf"; -option java_outer_classname = "AddressBookProtos"; - -message Person { - required string name = 1; - required int32 id = 2; - optional string email = 3; - - enum PhoneType { - MOBILE = 0; - HOME = 1; - WORK = 2; - } - - message PhoneNumber { - required string number = 1; - optional PhoneType type = 2 [default = HOME]; - } - - repeated PhoneNumber phone = 4; -} - -message AddressBook { - repeated Person person = 1; -} ------------------------------------------------------------- - -[[Protobuf-GeneratingJavaclasses]] -Generating Java classes -^^^^^^^^^^^^^^^^^^^^^^^ - -The Protobuf SDK provides a compiler which will generate the Java -classes for the format we defined in our .proto file. You can run the -compiler for any additional supported languages you require. - -`protoc --java_out=. ./addressbook.proto` - -This will generate a single Java class named AddressBookProtos which -contains inner classes for Person and AddressBook. Builders are also -implemented for you. The generated classes implement -com.google.protobuf.Message which is required by the serialisation -mechanism. For this reason it important that only these classes are used -in the body of your exchanges. Camel will throw an exception on route -creation if you attempt to tell the link:data-format.html[Data Format] -to use a class that does not implement com.google.protobuf.Message. Use -the generated builders to translate the data from any of your existing -domain classes. - -[[Protobuf-JavaDSL]] -Java DSL -~~~~~~~~ - -You can use create the ProtobufDataFormat instance and pass it to Camel -DataFormat marshal and unmarsha API like this. - -[source,java] ------------------------------------------------------------------------------------ - ProtobufDataFormat format = new ProtobufDataFormat(Person.getDefaultInstance()); - - from("direct:in").marshal(format); - from("direct:back").unmarshal(format).to("mock:reverse"); ------------------------------------------------------------------------------------ - -Or use the DSL protobuf() passing the unmarshal default instance or -default instance class name like this. - -[source,java] --------------------------------------------------------------------------------------------------- - // You don't need to specify the default instance for protobuf marshaling - from("direct:marshal").marshal().protobuf(); - from("direct:unmarshalA").unmarshal(). - protobuf("org.apache.camel.dataformat.protobuf.generated.AddressBookProtos$Person"). - to ("mock:reverse"); - - from("direct:unmarshalB").unmarshal().protobuf(Person.getDefaultInstance()).to("mock:reverse"); --------------------------------------------------------------------------------------------------- - -[[Protobuf-SpringDSL]] -Spring DSL -~~~~~~~~~~ - -The following example shows how to use Castor to unmarshal using Spring -configuring the protobuf data type - -[source,java] ----------------------------------------------------------------------------------------------------------- -<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";> - <route> - <from uri="direct:start"/> - <unmarshal> - <protobuf instanceClass="org.apache.camel.dataformat.protobuf.generated.AddressBookProtos$Person" /> - </unmarshal> - <to uri="mock:result"/> - </route> -</camelContext> ----------------------------------------------------------------------------------------------------------- - -[[Protobuf-Dependencies]] -Dependencies -^^^^^^^^^^^^ - -To use Protobuf in your camel routes you need to add the a dependency on -*camel-protobuf* which implements this data format. - -If you use maven you could just add the following to your pom.xml, -substituting the version number for the latest & greatest release (see -link:download.html[the download page for the latest versions]). - -[source,java] ------------------------------------------ -<dependency> - <groupId>org.apache.camel</groupId> - <artifactId>camel-protobuf</artifactId> - <version>2.2.0</version> -</dependency> ------------------------------------------ http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-quartz/src/main/docs/quartz-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-quartz/src/main/docs/quartz-component.adoc b/components/camel-quartz/src/main/docs/quartz-component.adoc index be1db78..d9156d0 100644 --- a/components/camel-quartz/src/main/docs/quartz-component.adoc +++ b/components/camel-quartz/src/main/docs/quartz-component.adoc @@ -48,13 +48,14 @@ Options ^^^^^^^ + // component options: START The Quartz component supports 7 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | factory | SchedulerFactory | To use the custom SchedulerFactory which is used to create the Scheduler. @@ -70,6 +71,7 @@ The Quartz component supports 7 options which are listed below. + // endpoint options: START The Quartz component supports 15 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-quartz2/src/main/docs/quartz2-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-quartz2/src/main/docs/quartz2-component.adoc b/components/camel-quartz2/src/main/docs/quartz2-component.adoc index f21f45f..7bdd17f 100644 --- a/components/camel-quartz2/src/main/docs/quartz2-component.adoc +++ b/components/camel-quartz2/src/main/docs/quartz2-component.adoc @@ -51,13 +51,14 @@ Options ^^^^^^^ + // component options: START The Quartz2 component supports 9 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | autoStartScheduler | boolean | Whether or not the scheduler should be auto started. This options is default true @@ -75,6 +76,7 @@ The Quartz2 component supports 9 options which are listed below. + // endpoint options: START The Quartz2 component supports 21 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-restlet/src/main/docs/restlet-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-restlet/src/main/docs/restlet-component.adoc b/components/camel-restlet/src/main/docs/restlet-component.adoc index 03a3e8a..753b8e0 100644 --- a/components/camel-restlet/src/main/docs/restlet-component.adoc +++ b/components/camel-restlet/src/main/docs/restlet-component.adoc @@ -64,13 +64,14 @@ Options ^^^^^^^ + // component options: START The Restlet component supports 20 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | controllerDaemon | Boolean | Indicates if the controller thread should be a daemon (not blocking JVM exit). @@ -99,6 +100,7 @@ The Restlet component supports 20 options which are listed below. + // endpoint options: START The Restlet component supports 21 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce-component.adoc b/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce-component.adoc index 616c501..c8d48f4 100644 --- a/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce-component.adoc +++ b/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce-component.adoc @@ -203,13 +203,14 @@ Options + // component options: START The Salesforce component supports 55 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | loginConfig | SalesforceLoginConfig | To use the shared SalesforceLoginConfig as login configuration. Properties of the shared configuration can also be set individually. @@ -279,6 +280,7 @@ The Salesforce component supports 55 options which are listed below. + // endpoint options: START The Salesforce component supports 39 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-saxon/src/main/docs/xquery-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-saxon/src/main/docs/xquery-component.adoc b/components/camel-saxon/src/main/docs/xquery-component.adoc index b88a4fb..bfabb63 100644 --- a/components/camel-saxon/src/main/docs/xquery-component.adoc +++ b/components/camel-saxon/src/main/docs/xquery-component.adoc @@ -15,13 +15,14 @@ Options ^^^^^^^ + // component options: START The XQuery component supports 1 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | moduleURIResolver | ModuleURIResolver | To use the custom ModuleURIResolver @@ -31,6 +32,7 @@ The XQuery component supports 1 options which are listed below. + // endpoint options: START The XQuery component supports 31 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-sjms/src/main/docs/sjms-batch-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-sjms/src/main/docs/sjms-batch-component.adoc b/components/camel-sjms/src/main/docs/sjms-batch-component.adoc index 4c81839..f7f607c 100644 --- a/components/camel-sjms/src/main/docs/sjms-batch-component.adoc +++ b/components/camel-sjms/src/main/docs/sjms-batch-component.adoc @@ -115,13 +115,14 @@ Component Options and Configurations + // component options: START The Simple JMS Batch component supports 1 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | connectionFactory | ConnectionFactory | A ConnectionFactory is required to enable the SjmsBatchComponent. @@ -136,6 +137,7 @@ The Simple JMS Batch component supports 1 options which are listed below. + // endpoint options: START The Simple JMS Batch component supports 21 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-sjms/src/main/docs/sjms-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-sjms/src/main/docs/sjms-component.adoc b/components/camel-sjms/src/main/docs/sjms-component.adoc index fa3a68d..a5fe12c 100644 --- a/components/camel-sjms/src/main/docs/sjms-component.adoc +++ b/components/camel-sjms/src/main/docs/sjms-component.adoc @@ -102,13 +102,14 @@ Component Options and Configurations + // component options: START The Simple JMS component supports 9 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | connectionFactory | ConnectionFactory | A ConnectionFactory is required to enable the SjmsComponent. It can be set directly or set set as part of a ConnectionResource. @@ -130,6 +131,7 @@ The Simple JMS component supports 9 options which are listed below. + // endpoint options: START The Simple JMS component supports 32 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-slack/src/main/docs/slack-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-slack/src/main/docs/slack-component.adoc b/components/camel-slack/src/main/docs/slack-component.adoc index 08563b8..91cb32d 100644 --- a/components/camel-slack/src/main/docs/slack-component.adoc +++ b/components/camel-slack/src/main/docs/slack-component.adoc @@ -46,13 +46,14 @@ Options ^^^^^^^ + // component options: START The Slack component supports 1 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | webhookUrl | String | The incoming webhook URL @@ -62,6 +63,7 @@ The Slack component supports 1 options which are listed below. + // endpoint options: START The Slack component supports 7 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-smpp/src/main/docs/smpp-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-smpp/src/main/docs/smpp-component.adoc b/components/camel-smpp/src/main/docs/smpp-component.adoc index 72a8e1d..e4cacec 100644 --- a/components/camel-smpp/src/main/docs/smpp-component.adoc +++ b/components/camel-smpp/src/main/docs/smpp-component.adoc @@ -177,13 +177,14 @@ URI Options + // component options: START The SMPP component supports 36 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | configuration | SmppConfiguration | To use the shared SmppConfiguration as configuration. Properties of the shared configuration can also be set individually. @@ -230,6 +231,7 @@ The SMPP component supports 36 options which are listed below. + // endpoint options: START The SMPP component supports 40 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-spark-rest/src/main/docs/spark-rest-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-spark-rest/src/main/docs/spark-rest-component.adoc b/components/camel-spark-rest/src/main/docs/spark-rest-component.adoc index 53d9125..8741320 100644 --- a/components/camel-spark-rest/src/main/docs/spark-rest-component.adoc +++ b/components/camel-spark-rest/src/main/docs/spark-rest-component.adoc @@ -36,13 +36,14 @@ URI Options ^^^^^^^^^^^ + // component options: START The Spark Rest component supports 11 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | port | int | Port number. Will by default use 4567 @@ -62,6 +63,7 @@ The Spark Rest component supports 11 options which are listed below. + // endpoint options: START The Spark Rest component supports 13 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-spark/src/main/docs/spark-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-spark/src/main/docs/spark-component.adoc b/components/camel-spark/src/main/docs/spark-component.adoc index 6620eb1..daf8b82 100644 --- a/components/camel-spark/src/main/docs/spark-component.adoc +++ b/components/camel-spark/src/main/docs/spark-component.adoc @@ -59,13 +59,14 @@ Spark options +++++++++++++ + // component options: START The Apache Spark component supports 2 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | rdd | JavaRDDLike | RDD to compute against. @@ -76,6 +77,7 @@ The Apache Spark component supports 2 options which are listed below. + // endpoint options: START The Apache Spark component supports 8 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-splunk/src/main/docs/splunk-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-splunk/src/main/docs/splunk-component.adoc b/components/camel-splunk/src/main/docs/splunk-component.adoc index 1e63732..31e01dd 100644 --- a/components/camel-splunk/src/main/docs/splunk-component.adoc +++ b/components/camel-splunk/src/main/docs/splunk-component.adoc @@ -94,13 +94,14 @@ URI Options ^^^^^^^^^^^ + // component options: START The Splunk component supports 1 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | splunkConfigurationFactory | SplunkConfigurationFactory | To use the SplunkConfigurationFactory @@ -110,6 +111,7 @@ The Splunk component supports 1 options which are listed below. + // endpoint options: START The Splunk component supports 43 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-spring-batch/src/main/docs/spring-batch-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-spring-batch/src/main/docs/spring-batch-component.adoc b/components/camel-spring-batch/src/main/docs/spring-batch-component.adoc index 2064f4b..3ee74a6 100644 --- a/components/camel-spring-batch/src/main/docs/spring-batch-component.adoc +++ b/components/camel-spring-batch/src/main/docs/spring-batch-component.adoc @@ -42,13 +42,14 @@ Options + // component options: START The Spring Batch component supports 2 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | jobLauncher | JobLauncher | Explicitly specifies a JobLauncher to be used. @@ -63,6 +64,7 @@ The Spring Batch component supports 2 options which are listed below. + // endpoint options: START The Spring Batch component supports 6 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-spring/src/main/docs/spring-event-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-spring/src/main/docs/spring-event-component.adoc b/components/camel-spring/src/main/docs/spring-event-component.adoc index ac6d00c..3e8b6f9 100644 --- a/components/camel-spring/src/main/docs/spring-event-component.adoc +++ b/components/camel-spring/src/main/docs/spring-event-component.adoc @@ -27,13 +27,14 @@ Spring Event Options ^^^^^^^^^^^^^^^^^^^^ + // component options: START The Spring Event component supports 1 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | applicationContext | ApplicationContext | The Spring ApplicationContext @@ -43,6 +44,7 @@ The Spring Event component supports 1 options which are listed below. + // endpoint options: START The Spring Event component supports 5 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-sql/src/main/docs/sql-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-sql/src/main/docs/sql-component.adoc b/components/camel-sql/src/main/docs/sql-component.adoc index 41d17c4..8f96e76 100644 --- a/components/camel-sql/src/main/docs/sql-component.adoc +++ b/components/camel-sql/src/main/docs/sql-component.adoc @@ -109,13 +109,14 @@ Options ^^^^^^^ + // component options: START The SQL component supports 2 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | dataSource | DataSource | Sets the DataSource to use to communicate with the database. @@ -126,6 +127,7 @@ The SQL component supports 2 options which are listed below. + // endpoint options: START The SQL component supports 46 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-sql/src/main/docs/sql-stored-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-sql/src/main/docs/sql-stored-component.adoc b/components/camel-sql/src/main/docs/sql-stored-component.adoc index 70ed167..976327f 100644 --- a/components/camel-sql/src/main/docs/sql-stored-component.adoc +++ b/components/camel-sql/src/main/docs/sql-stored-component.adoc @@ -67,13 +67,14 @@ Options ^^^^^^^ + // component options: START The SQL StoredProcedure component supports 1 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | dataSource | DataSource | Sets the DataSource to use to communicate with the database. @@ -83,6 +84,7 @@ The SQL StoredProcedure component supports 1 options which are listed below. + // endpoint options: START The SQL StoredProcedure component supports 8 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-ssh/src/main/docs/ssh-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-ssh/src/main/docs/ssh-component.adoc b/components/camel-ssh/src/main/docs/ssh-component.adoc index bdccfd8..93b5dc8 100644 --- a/components/camel-ssh/src/main/docs/ssh-component.adoc +++ b/components/camel-ssh/src/main/docs/ssh-component.adoc @@ -34,13 +34,14 @@ Options ^^^^^^^ + // component options: START The SSH component supports 11 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | configuration | SshConfiguration | To use the shared SSH configuration @@ -60,6 +61,7 @@ The SSH component supports 11 options which are listed below. + // endpoint options: START The SSH component supports 27 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-stomp/src/main/docs/stomp-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-stomp/src/main/docs/stomp-component.adoc b/components/camel-stomp/src/main/docs/stomp-component.adoc index 4d6bf26..b7e69dd 100644 --- a/components/camel-stomp/src/main/docs/stomp-component.adoc +++ b/components/camel-stomp/src/main/docs/stomp-component.adoc @@ -38,13 +38,14 @@ Options ^^^^^^^ + // component options: START The Stomp component supports 5 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | configuration | StompConfiguration | To use the shared stomp configuration @@ -59,6 +60,7 @@ The Stomp component supports 5 options which are listed below. + // endpoint options: START The Stomp component supports 10 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-syslog/src/main/docs/syslog-dataformat.adoc ---------------------------------------------------------------------- diff --git a/components/camel-syslog/src/main/docs/syslog-dataformat.adoc b/components/camel-syslog/src/main/docs/syslog-dataformat.adoc new file mode 100644 index 0000000..3cead3e --- /dev/null +++ b/components/camel-syslog/src/main/docs/syslog-dataformat.adoc @@ -0,0 +1,137 @@ +[[Syslog-SyslogDataFormat]] +Syslog DataFormat +~~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.6* + +The *syslog* dataformat is used for working with +http://www.ietf.org/rfc/rfc3164.txt[RFC3164] and RFC5424 messages. + +This component supports the following: + +* UDP consumption of syslog messages +* Agnostic data format using either plain String objects or +SyslogMessage model objects. +* link:type-converter.html[Type Converter] from/to SyslogMessage and +String +* Integration with the link:mina.html[camel-mina] component. +* Integration with the link:netty.html[camel-netty] component. +* *Camel 2.14:* Encoder and decoder for +the link:netty.html[camel-netty] component. +* *Camel 2.14:* Support for RFC5424 also. + +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-syslog</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +------------------------------------------------------------ + +[[Syslog-RFC3164Syslogprotocol]] +RFC3164 Syslog protocol +^^^^^^^^^^^^^^^^^^^^^^^ + +Syslog uses the user datagram protocol (UDP) +https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=1&linkCreation=true&fromPageId=24185759[1] +as its underlying transport layer mechanism. + + The UDP port that has been assigned to syslog is 514. + +To expose a Syslog listener service we reuse the existing +link:mina.html[camel-mina] component or link:netty.html[camel-netty] +where we just use the `Rfc3164SyslogDataFormat` to marshal and unmarshal +messages. Notice that from *Camel 2.14* onwards the syslog dataformat is +renamed to `SyslogDataFormat`. + +[[Syslog-RFC5424Syslogprotocol]] +RFC5424 Syslog protocol +^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.14* + +To expose a Syslog listener service we reuse the +existing link:mina.html[camel-mina] component +or link:netty.html[camel-netty] where we just use +the `SyslogDataFormat` to marshal and unmarshal messages + +[[Syslog-ExposingaSysloglistener]] +Exposing a Syslog listener +++++++++++++++++++++++++++ + +In our Spring XML file, we configure an endpoint to listen for udp +messages on port 10514, note that in netty we disable the defaultCodec, +this + + will allow a fallback to a NettyTypeConverter and delivers the message +as an InputStream: + +[source,xml] +------------------------------------------------------------------------------------------ +<camelContext id="myCamel" xmlns="http://camel.apache.org/schema/spring";> + + <dataFormats> + <syslog id="mySyslog"/> + </dataFormats> + + <route> + <from uri="netty:udp://localhost:10514?sync=false&allowDefaultCodec=false"/> + <unmarshal ref="mySyslog"/> + <to uri="mock:stop1"/> + </route> + +</camelContext> +------------------------------------------------------------------------------------------ + +The same route using link:mina.html[camel-mina] + +[source,xml] +------------------------------------------------------------------------- +<camelContext id="myCamel" xmlns="http://camel.apache.org/schema/spring";> + + <dataFormats> + <syslog id="mySyslog"/> + </dataFormats> + + <route> + <from uri="mina:udp://localhost:10514"/> + <unmarshal ref="mySyslog"/> + <to uri="mock:stop1"/> + </route> + +</camelContext> +------------------------------------------------------------------------- + +[[Syslog-Sendingsyslogmessagestoaremotedestination]] +Sending syslog messages to a remote destination ++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,xml] +------------------------------------------------------------------------- +<camelContext id="myCamel" xmlns="http://camel.apache.org/schema/spring";> + + <dataFormats> + <syslog id="mySyslog"/> + </dataFormats> + + <route> + <from uri="direct:syslogMessages"/> + <marshal ref="mySyslog"/> + <to uri="mina:udp://remotehost:10514"/> + </route> + +</camelContext> +------------------------------------------------------------------------- + +[[Syslog-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/96f3710b/components/camel-syslog/src/main/docs/syslog.adoc ---------------------------------------------------------------------- diff --git a/components/camel-syslog/src/main/docs/syslog.adoc b/components/camel-syslog/src/main/docs/syslog.adoc deleted file mode 100644 index 3cead3e..0000000 --- a/components/camel-syslog/src/main/docs/syslog.adoc +++ /dev/null @@ -1,137 +0,0 @@ -[[Syslog-SyslogDataFormat]] -Syslog DataFormat -~~~~~~~~~~~~~~~~~ - -*Available as of Camel 2.6* - -The *syslog* dataformat is used for working with -http://www.ietf.org/rfc/rfc3164.txt[RFC3164] and RFC5424 messages. - -This component supports the following: - -* UDP consumption of syslog messages -* Agnostic data format using either plain String objects or -SyslogMessage model objects. -* link:type-converter.html[Type Converter] from/to SyslogMessage and -String -* Integration with the link:mina.html[camel-mina] component. -* Integration with the link:netty.html[camel-netty] component. -* *Camel 2.14:* Encoder and decoder for -the link:netty.html[camel-netty] component. -* *Camel 2.14:* Support for RFC5424 also. - -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-syslog</artifactId> - <version>x.x.x</version> - <!-- use the same version as your Camel core version --> -</dependency> ------------------------------------------------------------- - -[[Syslog-RFC3164Syslogprotocol]] -RFC3164 Syslog protocol -^^^^^^^^^^^^^^^^^^^^^^^ - -Syslog uses the user datagram protocol (UDP) -https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=1&linkCreation=true&fromPageId=24185759[1] -as its underlying transport layer mechanism. + - The UDP port that has been assigned to syslog is 514. - -To expose a Syslog listener service we reuse the existing -link:mina.html[camel-mina] component or link:netty.html[camel-netty] -where we just use the `Rfc3164SyslogDataFormat` to marshal and unmarshal -messages. Notice that from *Camel 2.14* onwards the syslog dataformat is -renamed to `SyslogDataFormat`. - -[[Syslog-RFC5424Syslogprotocol]] -RFC5424 Syslog protocol -^^^^^^^^^^^^^^^^^^^^^^^ - -*Available as of Camel 2.14* - -To expose a Syslog listener service we reuse the -existing link:mina.html[camel-mina] component -or link:netty.html[camel-netty] where we just use -the `SyslogDataFormat` to marshal and unmarshal messages - -[[Syslog-ExposingaSysloglistener]] -Exposing a Syslog listener -++++++++++++++++++++++++++ - -In our Spring XML file, we configure an endpoint to listen for udp -messages on port 10514, note that in netty we disable the defaultCodec, -this + - will allow a fallback to a NettyTypeConverter and delivers the message -as an InputStream: - -[source,xml] ------------------------------------------------------------------------------------------- -<camelContext id="myCamel" xmlns="http://camel.apache.org/schema/spring";> - - <dataFormats> - <syslog id="mySyslog"/> - </dataFormats> - - <route> - <from uri="netty:udp://localhost:10514?sync=false&allowDefaultCodec=false"/> - <unmarshal ref="mySyslog"/> - <to uri="mock:stop1"/> - </route> - -</camelContext> ------------------------------------------------------------------------------------------- - -The same route using link:mina.html[camel-mina] - -[source,xml] -------------------------------------------------------------------------- -<camelContext id="myCamel" xmlns="http://camel.apache.org/schema/spring";> - - <dataFormats> - <syslog id="mySyslog"/> - </dataFormats> - - <route> - <from uri="mina:udp://localhost:10514"/> - <unmarshal ref="mySyslog"/> - <to uri="mock:stop1"/> - </route> - -</camelContext> -------------------------------------------------------------------------- - -[[Syslog-Sendingsyslogmessagestoaremotedestination]] -Sending syslog messages to a remote destination -+++++++++++++++++++++++++++++++++++++++++++++++ - -[source,xml] -------------------------------------------------------------------------- -<camelContext id="myCamel" xmlns="http://camel.apache.org/schema/spring";> - - <dataFormats> - <syslog id="mySyslog"/> - </dataFormats> - - <route> - <from uri="direct:syslogMessages"/> - <marshal ref="mySyslog"/> - <to uri="mina:udp://remotehost:10514"/> - </route> - -</camelContext> -------------------------------------------------------------------------- - -[[Syslog-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/96f3710b/components/camel-twitter/src/main/docs/twitter-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-twitter/src/main/docs/twitter-component.adoc b/components/camel-twitter/src/main/docs/twitter-component.adoc index 69723fb..77152c6 100644 --- a/components/camel-twitter/src/main/docs/twitter-component.adoc +++ b/components/camel-twitter/src/main/docs/twitter-component.adoc @@ -56,13 +56,14 @@ settings which is mandatory to configure before using. + // component options: START The Twitter component supports 8 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | accessToken | String | The access token @@ -80,6 +81,7 @@ The Twitter component supports 8 options which are listed below. + You can also configure these options directly in the endpoint. [[Twitter-ConsumerEndpoints]] http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-undertow/src/main/docs/undertow-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-undertow/src/main/docs/undertow-component.adoc b/components/camel-undertow/src/main/docs/undertow-component.adoc index 7fd77d7..5374c8b 100644 --- a/components/camel-undertow/src/main/docs/undertow-component.adoc +++ b/components/camel-undertow/src/main/docs/undertow-component.adoc @@ -42,13 +42,14 @@ Options + // component options: START The Undertow component supports 2 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | undertowHttpBinding | UndertowHttpBinding | To use a custom HttpBinding to control the mapping between Camel message and HttpClient. @@ -62,6 +63,7 @@ The Undertow component supports 2 options which are listed below. + // endpoint options: START The Undertow component supports 17 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-velocity/src/main/docs/velocity-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-velocity/src/main/docs/velocity-component.adoc b/components/camel-velocity/src/main/docs/velocity-component.adoc index 26ab6db..7d2d473 100644 --- a/components/camel-velocity/src/main/docs/velocity-component.adoc +++ b/components/camel-velocity/src/main/docs/velocity-component.adoc @@ -41,13 +41,14 @@ Options ^^^^^^^ + // component options: START The Velocity component supports 1 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | velocityEngine | VelocityEngine | To use the VelocityEngine otherwise a new engine is created @@ -57,6 +58,7 @@ The Velocity component supports 1 options which are listed below. + // endpoint options: START The Velocity component supports 7 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-vertx/src/main/docs/vertx-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-vertx/src/main/docs/vertx-component.adoc b/components/camel-vertx/src/main/docs/vertx-component.adoc index 734343b..2aeb289 100644 --- a/components/camel-vertx/src/main/docs/vertx-component.adoc +++ b/components/camel-vertx/src/main/docs/vertx-component.adoc @@ -40,13 +40,14 @@ Options ^^^^^^^ + // component options: START The Vert.x component supports 6 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | vertxFactory | VertxFactory | To use a custom VertxFactory implementation @@ -61,6 +62,7 @@ The Vert.x component supports 6 options which are listed below. + // endpoint options: START The Vert.x component supports 6 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-websocket/src/main/docs/websocket-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-websocket/src/main/docs/websocket-component.adoc b/components/camel-websocket/src/main/docs/websocket-component.adoc index 21068b8..d490a92 100644 --- a/components/camel-websocket/src/main/docs/websocket-component.adoc +++ b/components/camel-websocket/src/main/docs/websocket-component.adoc @@ -36,13 +36,14 @@ Websocket Options + // component options: START The Jetty Websocket component supports 12 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | staticResources | String | Set a resource path for static resources (such as .html files etc). The resources can be loaded from classpath if you prefix with classpath: otherwise the resources is loaded from file system or from JAR files. For example to load from root classpath use classpath:. or classpath:WEB-INF/static If not configured (eg null) then no static resource is in use. @@ -69,6 +70,7 @@ The Jetty Websocket component supports 12 options which are listed below. + // endpoint options: START The Jetty Websocket component supports 20 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-xmlbeans/src/main/docs/xmlBeans-dataformat.adoc ---------------------------------------------------------------------- diff --git a/components/camel-xmlbeans/src/main/docs/xmlBeans-dataformat.adoc b/components/camel-xmlbeans/src/main/docs/xmlBeans-dataformat.adoc new file mode 100644 index 0000000..1b960c6 --- /dev/null +++ b/components/camel-xmlbeans/src/main/docs/xmlBeans-dataformat.adoc @@ -0,0 +1,36 @@ +[[XmlBeans-XmlBeans]] +XmlBeans +~~~~~~~~ + +XmlBeans is a link:data-format.html[Data Format] which uses the +http://xmlbeans.apache.org/[XmlBeans library] to unmarshal an XML +payload into Java objects or to marshal Java objects into an XML +payload. + +[source,java] +------------------------------- +from("activemq:My.Queue"). + unmarshal().xmlBeans(). + to("mqseries:Another.Queue"); +------------------------------- + +[[XmlBeans-Dependencies]] +Dependencies +^^^^^^^^^^^^ + +To use XmlBeans in your camel routes you need to add the dependency on +*camel-xmlbeans* which implements this data format. + +If you use maven you could just add the following to your pom.xml, +substituting the version number for the latest & greatest release (see +link:download.html[the download page for the latest versions]). + +[source,xml] +---------------------------------------------------------- +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-xmlbeans</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +---------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-xmlbeans/src/main/docs/xmlbeans.adoc ---------------------------------------------------------------------- diff --git a/components/camel-xmlbeans/src/main/docs/xmlbeans.adoc b/components/camel-xmlbeans/src/main/docs/xmlbeans.adoc deleted file mode 100644 index 1b960c6..0000000 --- a/components/camel-xmlbeans/src/main/docs/xmlbeans.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[[XmlBeans-XmlBeans]] -XmlBeans -~~~~~~~~ - -XmlBeans is a link:data-format.html[Data Format] which uses the -http://xmlbeans.apache.org/[XmlBeans library] to unmarshal an XML -payload into Java objects or to marshal Java objects into an XML -payload. - -[source,java] -------------------------------- -from("activemq:My.Queue"). - unmarshal().xmlBeans(). - to("mqseries:Another.Queue"); -------------------------------- - -[[XmlBeans-Dependencies]] -Dependencies -^^^^^^^^^^^^ - -To use XmlBeans in your camel routes you need to add the dependency on -*camel-xmlbeans* which implements this data format. - -If you use maven you could just add the following to your pom.xml, -substituting the version number for the latest & greatest release (see -link:download.html[the download page for the latest versions]). - -[source,xml] ----------------------------------------------------------- -<dependency> - <groupId>org.apache.camel</groupId> - <artifactId>camel-xmlbeans</artifactId> - <version>x.x.x</version> - <!-- use the same version as your Camel core version --> -</dependency> ----------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-xmljson/src/main/docs/xmljson-dataformat.adoc ---------------------------------------------------------------------- diff --git a/components/camel-xmljson/src/main/docs/xmljson-dataformat.adoc b/components/camel-xmljson/src/main/docs/xmljson-dataformat.adoc new file mode 100644 index 0000000..c5fc195 --- /dev/null +++ b/components/camel-xmljson/src/main/docs/xmljson-dataformat.adoc @@ -0,0 +1,378 @@ +[[XmlJson-XMLJSONDataFormat]] +XML JSON Data Format (`camel-xmljson`) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.10* + +Camel already supports a number of data formats to perform XML and +JSON-related conversions, but all of them require a POJO either as an +input (for marshalling) or produce a POJO as output (for unmarshalling). +This data format provides the capability to convert from XML to JSON and +vice-versa directly, without stepping through intermediate POJOs. + +This data format leverages the +http://json-lib.sourceforge.net/[Json-lib] library to achieve direct +conversion. In this context, XML is considered the high-level format, +while JSON is the low-level format. Hence, the marshal/unmarshal +semantics are assigned as follows: + +* marshalling => converting from XML to JSON +* unmarshalling => converting from JSON to XML. + +[[XmlJson-Options]] +Options +^^^^^^^ + +This data format supports the following options. You can set them via +all DSLs. The defaults marked with (*) are determined by json-lib, +rather than the code of the data format itself. They are reflected here +for convenience so that you don't have to dot back and forth with the +json-lib docs. + +[width="100%",cols="1s,1m,1m,4",options="header",] +|======================================================================= +|Name |Type |Default |Description +|`encoding` |`String` |UTF-8 (*) |*Used when* *unmarshalling* *(JSON to +XML conversion).* Sets the encoding for the call to +http://json-lib.sourceforge.net/apidocs/net/sf/json/xml/XMLSerializer.html#write(net.sf.json.JSON,%20java.lang.String)[`XMLSerializer.write()`] +method, hence it is only used when producing XML. + +When producing JSON, the encoding is determined by the input String +being processed. If the conversion is performed on an InputStream, +json-lib uses the platform's default encoding (e.g. determined by the +`file.encoding` system property). + +|`elementName` |`String` |'e' (*) |*Used when* *unmarshalling*** (JSON +to XML conversion).** Specifies the name of the XML elements +representing each array element. See +http://json-lib.sourceforge.net/snippets.html#JSONObject_to_XML_change_node_names[json-lib +doc]. + +|`arrayName` |`String` |'a' (*) |*Used when* *unmarshalling*** (JSON to +XML conversion).** Specifies the name of the top-level XML element. + +For example, when converting `[1, 2, 3]`, it will be output by default +as `<a><e>1</e><e>2</e><e>3</e></a>`. By setting this option or +rootName, you can alter the name of element 'a'. + +|`rootName` |`String` |none (*) |*Used when* *unmarshalling*** (JSON to +XML conversion).** When converting any JSON construct (object, array, +null) to XML (unmarshalling), it specifies the name of the top-level +element. + +If not set, json-lib will use `arrayName` or `objectName` (default +value: 'o', at the current time it is not configurable in this data +format). If set to 'root', the JSON string `{ 'x': 'value1', 'y' : +'value2' }` would turn into `<root><x>value1</x><y>value2</y></root>`, +otherwise the 'root' element would be named 'o'. + +|`namespaceLenient` |`Boolean` |false (*) |*Used when* +*unmarshalling*** (JSON to XML conversion).** According to the json-lib +docs: "Flag to be tolerant to incomplete namespace prefixes." In most +cases, json-lib automatically changes this flag at runtime to match the +processing. + +|`namespaceMappings` |`List<NamespacesPerElementMapping>` |none |*Used +when* *unmarshalling*** (JSON to XML conversion).** Binds namespace +prefixes and URIs to specific JSON +elements. `NamespacesPerElementMapping` is a wrapper around an element +name + a Map of prefixes against URIs. + +|`expandableProperties` |`List<String>` |none |*Used when* +*unmarshalling*** (JSON to XML conversion).** With expandable +properties, JSON array elements are converted to XML as a sequence of +repetitive XML elements with the local name equal to the JSON key, for +example: `{ number: 1,2,3 }`, normally converted to: +`<number><e>1</e><e>2</e><e>3</e></number>` (where e can be modified by +setting `elementName`), would instead translate to +`<number>1</number><number>2</number><number>3</number>`, if `number` is +set as an expandable property + +|`typeHints` |`TypeHintsEnum` |YES a| +*Used when* *unmarshalling*** (JSON to XML conversion).** Adds type +hints to the resulting XML to aid conversion back to JSON. See +documentation +http://json-lib.sourceforge.net/apidocs/net/sf/json/xml/XMLSerializer.html[here] +for an explanation. `TypeHintsEnum` comprises the following values, +which lead to different combinations of the underlying XMLSerializer's +`typeHintsEnabled` and `typeHintsCompatibility` flags: + +* `TypeHintsEnum.NO` => `typeHintsEnabled` = `false` +* `TypeHintsEnum.YES` =>  `typeHintsEnabled` = +true,  `typeHintsCompatibility` = `true` +* `TypeHintsEnum.WITH_PREFIX` =>  `typeHintsEnabled` = +true,  `typeHintsCompatibility` = `false` + +|`forceTopLevelObject` |`Boolean` |false (*) |*Used when* *marshalling* +*(XML to JSON conversion).* Determines whether the resulting JSON will +start off with a top-most element whose name matches the XML root +element. If disabled, XML string `<a><x>1</x><y>2</y></a>` turns into `{ +'x: '1', 'y': '2' }`. Otherwise, it turns into `{ 'a': { 'x: '1', 'y': +'2' }}`. + +|`skipWhitespace` |`Boolean` |false (*) |*Used when* +*marshalling*** (XML to JSON conversion).** Determines whether white +spaces between XML elements will be regarded as text values or +disregarded. + +|`trimSpaces` |`Boolean` |false (*) |*Used when* *marshalling*** (XML to +JSON conversion).** Determines whether leading and trailing white spaces +will be omitted from String values. + +|`skipNamespaces` |`Boolean` |false (*) |*Used when* +*marshalling*** (XML to JSON conversion).** Signals whether namespaces +should be ignored. By default they will be added to the JSON output +using `@xmlns` elements. + +|`removeNamespacePrefixes` |`Boolean` |false (*) |*Used when* +*marshalling*** (XML to JSON conversion).** Removes the namespace +prefixes from XML qualified elements, so that the resulting JSON string +does not contain them. +|======================================================================= + +[[XmlJson-BasicUsagewithJavaDSL]] +Basic Usage with Java DSL +^^^^^^^^^^^^^^^^^^^^^^^^^ + +[[XmlJson-Explicitlyinstantiatingthedataformat]] +Explicitly instantiating the data format +++++++++++++++++++++++++++++++++++++++++ + +Just instantiate the `XmlJsonDataFormat` from package +`org.apache.camel.dataformat.xmljson`. Make sure you have installed the +`camel-xmljson` feature (if running on OSGi) or that you've included +`camel-xmljson-{version}.jar` and its transitive dependencies in your +classpath. Example initialization with a default configuration: + +[source,java] +---- +XmlJsonDataFormat xmlJsonFormat = new XmlJsonDataFormat(); +---- + +To tune the behaviour of the data format as per the options above, use +the appropriate setters: + +[source,java] +---- +XmlJsonDataFormat xmlJsonFormat = new XmlJsonDataFormat(); +xmlJsonFormat.setEncoding("UTF-8"); +xmlJsonFormat.setForceTopLevelObject(true); +xmlJsonFormat.setTrimSpaces(true); +xmlJsonFormat.setRootName("newRoot"); +xmlJsonFormat.setSkipNamespaces(true); +xmlJsonFormat.setRemoveNamespacePrefixes(true); +xmlJsonFormat.setExpandableProperties(Arrays.asList("d", "e")); +---- + +Once you've instantiated the data format, the next step is to actually +use the it from within the `marshal()` and `unmarshal()` DSL elements: + +[source,java] +---- +// from XML to JSON +from("direct:marshal").marshal(xmlJsonFormat).to("mock:json"); +// from JSON to XML +from("direct:unmarshal").unmarshal(xmlJsonFormat).to("mock:xml"); +---- + +[[XmlJson-Definingthedataformatin-line]] +Defining the data format in-line +++++++++++++++++++++++++++++++++ + +Alternatively, you can define the data format inline by using the +`xmljson()` DSL element: + +[source,java] +---- +// from XML to JSON - inline dataformat +from("direct:marshalInline").marshal().xmljson().to("mock:jsonInline"); +// from JSON to XML - inline dataformat +from("direct:unmarshalInline").unmarshal().xmljson().to("mock:xmlInline"); +---- + +If you wish, you can even pass in a `Map<String, String>` to the inline +methods to provide custom options: + +[source,java] +---- +Map<String, String> xmlJsonOptions = new HashMap<String, String>(); +xmlJsonOptions.put(org.apache.camel.model.dataformat.XmlJsonDataFormat.ENCODING, "UTF-8"); +xmlJsonOptions.put(org.apache.camel.model.dataformat.XmlJsonDataFormat.ROOT_NAME, "newRoot"); +xmlJsonOptions.put(org.apache.camel.model.dataformat.XmlJsonDataFormat.SKIP_NAMESPACES, "true"); +xmlJsonOptions.put(org.apache.camel.model.dataformat.XmlJsonDataFormat.REMOVE_NAMESPACE_PREFIXES, "true"); +xmlJsonOptions.put(org.apache.camel.model.dataformat.XmlJsonDataFormat.EXPANDABLE_PROPERTIES, "d e"); + +// from XML to JSON - inline dataformat w/ options +from("direct:marshalInlineOptions").marshal().xmljson(xmlJsonOptions).to("mock:jsonInlineOptions"); +// form JSON to XML - inline dataformat w/ options +from("direct:unmarshalInlineOptions").unmarshal().xmljson(xmlJsonOptions).to("mock:xmlInlineOptions"); +---- + +[[XmlJson-BasicusagewithSpringorBlueprintDSL]] +Basic usage with Spring or Blueprint DSL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Within the `<dataFormats>` block, simply configure an `xmljson` element +with unique IDs: + +[source,xml] +---- +<dataFormats> + <xmljson id="xmljson"/> + <xmljson id="xmljsonWithOptions" forceTopLevelObject="true" trimSpaces="true" rootName="newRoot" skipNamespaces="true" + removeNamespacePrefixes="true" expandableProperties="d e"/> +</dataFormats> +---- + +Then you simply refer to the data format object within your +`<marshal />` and `<unmarshal />` DSLs: + +[source,xml] +---- +<route> + <from uri="direct:marshal"/> + <marshal ref="xmljson"/> + <to uri="mock:json" /> +</route> + +<route> + <from uri="direct:unmarshalWithOptions"/> + <unmarshal ref="xmljsonWithOptions"/> + <to uri="mock:xmlWithOptions"/> +</route> +---- + +Enabling XML DSL autocompletion for this component is easy: just refer +to the appropriate http://camel.apache.org/xml-reference.html[Schema +locations], depending on whether you're using +http://camel.apache.org/schema/spring/[Spring] or +http://camel.apache.org/schema/blueprint/[Blueprint] DSL. Remember that +this data format is available from Camel 2.10 onwards, so only schemas +from that version onwards will include these new XML elements and +attributes. + +The syntax with link:using-osgi-blueprint-with-camel.html[Blueprint] is +identical to that of the Spring DSL. Just ensure the correct namespaces +and schemaLocations are in use. + +[[XmlJson-Namespacemappings]] +Namespace mappings +^^^^^^^^^^^^^^^^^^ + +XML has namespaces to fully qualify elements and attributes; JSON +doesn't. You need to take this into account when performing XML-JSON +conversions. + +To bridge the gap, http://json-lib.sourceforge.net/[Json-lib] has an +option to bind namespace declarations in the form of prefixes and +namespace URIs to XML output elements while unmarshalling (i.e. +converting from JSON to XML). For example, provided the following JSON +string: + +[source,json] +---- +{ "pref1:a": "value1", "pref2:b": "value2" } +---- + +you can ask Json-lib to output namespace declarations on elements +`pref1:a` and `pref2:b` to bind the prefixes `pref1` and `pref2` to +specific namespace URIs. + +To use this feature, simply create +`XmlJsonDataFormat.NamespacesPerElementMapping` objects and add them to +the `namespaceMappings` option (which is a `List`). + +The `XmlJsonDataFormat.NamespacesPerElementMapping` holds an element +name and a Map of [prefix => namespace URI]. To facilitate mapping +multiple prefixes and namespace URIs, the +`NamespacesPerElementMapping(String element, String pipeSeparatedMappings)` +constructor takes a String-based pipe-separated sequence of [prefix, +namespaceURI] pairs in the following way: +`|ns2|http://camel.apache.org/personalData|ns3|http://camel.apache.org/personalData2|`. + +In order to define a default namespace, just leave the corresponding key +field empty: +`|ns1|http://camel.apache.org/test1||http://camel.apache.org/default|`. + +Binding namespace declarations to an element name = empty string will +attach those namespaces to the root element. + +The full code would look like that: + +[source,java] +---- +XmlJsonDataFormat namespacesFormat = new XmlJsonDataFormat(); +List<XmlJsonDataFormat.NamespacesPerElementMapping> namespaces = new ArrayList<XmlJsonDataFormat.NamespacesPerElementMapping>(); +namespaces.add(new XmlJsonDataFormat. + NamespacesPerElementMapping("", "|ns1|http://camel.apache.org/test1||http://camel.apache.org/default|")); +namespaces.add(new XmlJsonDataFormat. + NamespacesPerElementMapping("surname", "|ns2|http://camel.apache.org/personalData|" + + "ns3|http://camel.apache.org/personalData2|")); +namespacesFormat.setNamespaceMappings(namespaces); +namespacesFormat.setRootElement("person"); +---- + +And you can achieve the same in Spring DSL. + +[[XmlJson-Example]] +Example ++++++++ + +Using the namespace bindings in the Java snippet above on the following +JSON string: + +[source,json] +---- +{ "name": "Raul", "surname": "Kripalani", "f": true, "g": null} +---- + + + +Would yield the following XML: + +[source,xml] +---- +<person xmlns="http://camel.apache.org/default"; xmlns:ns1="http://camel.apache.org/test1";> + <f>true</f> + <g null="true"/> + <name>Raul</name> + <surname xmlns:ns2="http://camel.apache.org/personalData"; xmlns:ns3="http://camel.apache.org/personalData2";>Kripalani</surname> +</person> +---- + +Remember that the JSON spec defines a JSON object as follows: + +_________________________________________________________ +An object is an unordered set of name/value pairs. [...]. +_________________________________________________________ + +That's why the elements are in a different order in the output XML. + +[[XmlJson-Dependencies]] +Dependencies +^^^^^^^^^^^^ + +To use the link:xmljson.html[XmlJson] dataformat in your camel routes +you need to add the following dependency to your pom: + +[source,xml] +---- +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-xmljson</artifactId> + <version>x.x.x</version> + <!-- Use the same version as camel-core, but remember that this component is only available from 2.10 onwards --> +</dependency> + +<!-- And also XOM must be included. XOM cannot be included by default due to an incompatible +license with ASF; so add this manually --> +<dependency> + <groupId>xom</groupId> + <artifactId>xom</artifactId> + <version>1.2.5</version> +</dependency> +---- + +[[XmlJson-SeeAlso]] +See Also +^^^^^^^^ + +* link:data-format.html[Data Format] +* http://json-lib.sourceforge.net/[json-lib] http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-xmljson/src/main/docs/xmljson.adoc ---------------------------------------------------------------------- diff --git a/components/camel-xmljson/src/main/docs/xmljson.adoc b/components/camel-xmljson/src/main/docs/xmljson.adoc deleted file mode 100644 index c5fc195..0000000 --- a/components/camel-xmljson/src/main/docs/xmljson.adoc +++ /dev/null @@ -1,378 +0,0 @@ -[[XmlJson-XMLJSONDataFormat]] -XML JSON Data Format (`camel-xmljson`) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Available as of Camel 2.10* - -Camel already supports a number of data formats to perform XML and -JSON-related conversions, but all of them require a POJO either as an -input (for marshalling) or produce a POJO as output (for unmarshalling). -This data format provides the capability to convert from XML to JSON and -vice-versa directly, without stepping through intermediate POJOs. - -This data format leverages the -http://json-lib.sourceforge.net/[Json-lib] library to achieve direct -conversion. In this context, XML is considered the high-level format, -while JSON is the low-level format. Hence, the marshal/unmarshal -semantics are assigned as follows: - -* marshalling => converting from XML to JSON -* unmarshalling => converting from JSON to XML. - -[[XmlJson-Options]] -Options -^^^^^^^ - -This data format supports the following options. You can set them via -all DSLs. The defaults marked with (*) are determined by json-lib, -rather than the code of the data format itself. They are reflected here -for convenience so that you don't have to dot back and forth with the -json-lib docs. - -[width="100%",cols="1s,1m,1m,4",options="header",] -|======================================================================= -|Name |Type |Default |Description -|`encoding` |`String` |UTF-8 (*) |*Used when* *unmarshalling* *(JSON to -XML conversion).* Sets the encoding for the call to -http://json-lib.sourceforge.net/apidocs/net/sf/json/xml/XMLSerializer.html#write(net.sf.json.JSON,%20java.lang.String)[`XMLSerializer.write()`] -method, hence it is only used when producing XML. + -When producing JSON, the encoding is determined by the input String -being processed. If the conversion is performed on an InputStream, -json-lib uses the platform's default encoding (e.g. determined by the -`file.encoding` system property). - -|`elementName` |`String` |'e' (*) |*Used when* *unmarshalling*** (JSON -to XML conversion).** Specifies the name of the XML elements -representing each array element. See -http://json-lib.sourceforge.net/snippets.html#JSONObject_to_XML_change_node_names[json-lib -doc]. - -|`arrayName` |`String` |'a' (*) |*Used when* *unmarshalling*** (JSON to -XML conversion).** Specifies the name of the top-level XML element. + -For example, when converting `[1, 2, 3]`, it will be output by default -as `<a><e>1</e><e>2</e><e>3</e></a>`. By setting this option or -rootName, you can alter the name of element 'a'. - -|`rootName` |`String` |none (*) |*Used when* *unmarshalling*** (JSON to -XML conversion).** When converting any JSON construct (object, array, -null) to XML (unmarshalling), it specifies the name of the top-level -element. + -If not set, json-lib will use `arrayName` or `objectName` (default -value: 'o', at the current time it is not configurable in this data -format). If set to 'root', the JSON string `{ 'x': 'value1', 'y' : -'value2' }` would turn into `<root><x>value1</x><y>value2</y></root>`, -otherwise the 'root' element would be named 'o'. - -|`namespaceLenient` |`Boolean` |false (*) |*Used when* -*unmarshalling*** (JSON to XML conversion).** According to the json-lib -docs: "Flag to be tolerant to incomplete namespace prefixes." In most -cases, json-lib automatically changes this flag at runtime to match the -processing. - -|`namespaceMappings` |`List<NamespacesPerElementMapping>` |none |*Used -when* *unmarshalling*** (JSON to XML conversion).** Binds namespace -prefixes and URIs to specific JSON -elements. `NamespacesPerElementMapping` is a wrapper around an element -name + a Map of prefixes against URIs. - -|`expandableProperties` |`List<String>` |none |*Used when* -*unmarshalling*** (JSON to XML conversion).** With expandable -properties, JSON array elements are converted to XML as a sequence of -repetitive XML elements with the local name equal to the JSON key, for -example: `{ number: 1,2,3 }`, normally converted to: -`<number><e>1</e><e>2</e><e>3</e></number>` (where e can be modified by -setting `elementName`), would instead translate to -`<number>1</number><number>2</number><number>3</number>`, if `number` is -set as an expandable property - -|`typeHints` |`TypeHintsEnum` |YES a| -*Used when* *unmarshalling*** (JSON to XML conversion).** Adds type -hints to the resulting XML to aid conversion back to JSON. See -documentation -http://json-lib.sourceforge.net/apidocs/net/sf/json/xml/XMLSerializer.html[here] -for an explanation. `TypeHintsEnum` comprises the following values, -which lead to different combinations of the underlying XMLSerializer's -`typeHintsEnabled` and `typeHintsCompatibility` flags: - -* `TypeHintsEnum.NO` => `typeHintsEnabled` = `false` -* `TypeHintsEnum.YES` =>  `typeHintsEnabled` = -true,  `typeHintsCompatibility` = `true` -* `TypeHintsEnum.WITH_PREFIX` =>  `typeHintsEnabled` = -true,  `typeHintsCompatibility` = `false` - -|`forceTopLevelObject` |`Boolean` |false (*) |*Used when* *marshalling* -*(XML to JSON conversion).* Determines whether the resulting JSON will -start off with a top-most element whose name matches the XML root -element. If disabled, XML string `<a><x>1</x><y>2</y></a>` turns into `{ -'x: '1', 'y': '2' }`. Otherwise, it turns into `{ 'a': { 'x: '1', 'y': -'2' }}`. - -|`skipWhitespace` |`Boolean` |false (*) |*Used when* -*marshalling*** (XML to JSON conversion).** Determines whether white -spaces between XML elements will be regarded as text values or -disregarded. - -|`trimSpaces` |`Boolean` |false (*) |*Used when* *marshalling*** (XML to -JSON conversion).** Determines whether leading and trailing white spaces -will be omitted from String values. - -|`skipNamespaces` |`Boolean` |false (*) |*Used when* -*marshalling*** (XML to JSON conversion).** Signals whether namespaces -should be ignored. By default they will be added to the JSON output -using `@xmlns` elements. - -|`removeNamespacePrefixes` |`Boolean` |false (*) |*Used when* -*marshalling*** (XML to JSON conversion).** Removes the namespace -prefixes from XML qualified elements, so that the resulting JSON string -does not contain them. -|======================================================================= - -[[XmlJson-BasicUsagewithJavaDSL]] -Basic Usage with Java DSL -^^^^^^^^^^^^^^^^^^^^^^^^^ - -[[XmlJson-Explicitlyinstantiatingthedataformat]] -Explicitly instantiating the data format -++++++++++++++++++++++++++++++++++++++++ - -Just instantiate the `XmlJsonDataFormat` from package -`org.apache.camel.dataformat.xmljson`. Make sure you have installed the -`camel-xmljson` feature (if running on OSGi) or that you've included -`camel-xmljson-{version}.jar` and its transitive dependencies in your -classpath. Example initialization with a default configuration: - -[source,java] ----- -XmlJsonDataFormat xmlJsonFormat = new XmlJsonDataFormat(); ----- - -To tune the behaviour of the data format as per the options above, use -the appropriate setters: - -[source,java] ----- -XmlJsonDataFormat xmlJsonFormat = new XmlJsonDataFormat(); -xmlJsonFormat.setEncoding("UTF-8"); -xmlJsonFormat.setForceTopLevelObject(true); -xmlJsonFormat.setTrimSpaces(true); -xmlJsonFormat.setRootName("newRoot"); -xmlJsonFormat.setSkipNamespaces(true); -xmlJsonFormat.setRemoveNamespacePrefixes(true); -xmlJsonFormat.setExpandableProperties(Arrays.asList("d", "e")); ----- - -Once you've instantiated the data format, the next step is to actually -use the it from within the `marshal()` and `unmarshal()` DSL elements: - -[source,java] ----- -// from XML to JSON -from("direct:marshal").marshal(xmlJsonFormat).to("mock:json"); -// from JSON to XML -from("direct:unmarshal").unmarshal(xmlJsonFormat).to("mock:xml"); ----- - -[[XmlJson-Definingthedataformatin-line]] -Defining the data format in-line -++++++++++++++++++++++++++++++++ - -Alternatively, you can define the data format inline by using the -`xmljson()` DSL element: - -[source,java] ----- -// from XML to JSON - inline dataformat -from("direct:marshalInline").marshal().xmljson().to("mock:jsonInline"); -// from JSON to XML - inline dataformat -from("direct:unmarshalInline").unmarshal().xmljson().to("mock:xmlInline"); ----- - -If you wish, you can even pass in a `Map<String, String>` to the inline -methods to provide custom options: - -[source,java] ----- -Map<String, String> xmlJsonOptions = new HashMap<String, String>(); -xmlJsonOptions.put(org.apache.camel.model.dataformat.XmlJsonDataFormat.ENCODING, "UTF-8"); -xmlJsonOptions.put(org.apache.camel.model.dataformat.XmlJsonDataFormat.ROOT_NAME, "newRoot"); -xmlJsonOptions.put(org.apache.camel.model.dataformat.XmlJsonDataFormat.SKIP_NAMESPACES, "true"); -xmlJsonOptions.put(org.apache.camel.model.dataformat.XmlJsonDataFormat.REMOVE_NAMESPACE_PREFIXES, "true"); -xmlJsonOptions.put(org.apache.camel.model.dataformat.XmlJsonDataFormat.EXPANDABLE_PROPERTIES, "d e"); - -// from XML to JSON - inline dataformat w/ options -from("direct:marshalInlineOptions").marshal().xmljson(xmlJsonOptions).to("mock:jsonInlineOptions"); -// form JSON to XML - inline dataformat w/ options -from("direct:unmarshalInlineOptions").unmarshal().xmljson(xmlJsonOptions).to("mock:xmlInlineOptions"); ----- - -[[XmlJson-BasicusagewithSpringorBlueprintDSL]] -Basic usage with Spring or Blueprint DSL -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Within the `<dataFormats>` block, simply configure an `xmljson` element -with unique IDs: - -[source,xml] ----- -<dataFormats> - <xmljson id="xmljson"/> - <xmljson id="xmljsonWithOptions" forceTopLevelObject="true" trimSpaces="true" rootName="newRoot" skipNamespaces="true" - removeNamespacePrefixes="true" expandableProperties="d e"/> -</dataFormats> ----- - -Then you simply refer to the data format object within your -`<marshal />` and `<unmarshal />` DSLs: - -[source,xml] ----- -<route> - <from uri="direct:marshal"/> - <marshal ref="xmljson"/> - <to uri="mock:json" /> -</route> - -<route> - <from uri="direct:unmarshalWithOptions"/> - <unmarshal ref="xmljsonWithOptions"/> - <to uri="mock:xmlWithOptions"/> -</route> ----- - -Enabling XML DSL autocompletion for this component is easy: just refer -to the appropriate http://camel.apache.org/xml-reference.html[Schema -locations], depending on whether you're using -http://camel.apache.org/schema/spring/[Spring] or -http://camel.apache.org/schema/blueprint/[Blueprint] DSL. Remember that -this data format is available from Camel 2.10 onwards, so only schemas -from that version onwards will include these new XML elements and -attributes. - -The syntax with link:using-osgi-blueprint-with-camel.html[Blueprint] is -identical to that of the Spring DSL. Just ensure the correct namespaces -and schemaLocations are in use. - -[[XmlJson-Namespacemappings]] -Namespace mappings -^^^^^^^^^^^^^^^^^^ - -XML has namespaces to fully qualify elements and attributes; JSON -doesn't. You need to take this into account when performing XML-JSON -conversions. - -To bridge the gap, http://json-lib.sourceforge.net/[Json-lib] has an -option to bind namespace declarations in the form of prefixes and -namespace URIs to XML output elements while unmarshalling (i.e. -converting from JSON to XML). For example, provided the following JSON -string: - -[source,json] ----- -{ "pref1:a": "value1", "pref2:b": "value2" } ----- - -you can ask Json-lib to output namespace declarations on elements -`pref1:a` and `pref2:b` to bind the prefixes `pref1` and `pref2` to -specific namespace URIs. - -To use this feature, simply create -`XmlJsonDataFormat.NamespacesPerElementMapping` objects and add them to -the `namespaceMappings` option (which is a `List`). - -The `XmlJsonDataFormat.NamespacesPerElementMapping` holds an element -name and a Map of [prefix => namespace URI]. To facilitate mapping -multiple prefixes and namespace URIs, the -`NamespacesPerElementMapping(String element, String pipeSeparatedMappings)` -constructor takes a String-based pipe-separated sequence of [prefix, -namespaceURI] pairs in the following way: -`|ns2|http://camel.apache.org/personalData|ns3|http://camel.apache.org/personalData2|`. - -In order to define a default namespace, just leave the corresponding key -field empty: -`|ns1|http://camel.apache.org/test1||http://camel.apache.org/default|`. - -Binding namespace declarations to an element name = empty string will -attach those namespaces to the root element. - -The full code would look like that: - -[source,java] ----- -XmlJsonDataFormat namespacesFormat = new XmlJsonDataFormat(); -List<XmlJsonDataFormat.NamespacesPerElementMapping> namespaces = new ArrayList<XmlJsonDataFormat.NamespacesPerElementMapping>(); -namespaces.add(new XmlJsonDataFormat. - NamespacesPerElementMapping("", "|ns1|http://camel.apache.org/test1||http://camel.apache.org/default|")); -namespaces.add(new XmlJsonDataFormat. - NamespacesPerElementMapping("surname", "|ns2|http://camel.apache.org/personalData|" + - "ns3|http://camel.apache.org/personalData2|")); -namespacesFormat.setNamespaceMappings(namespaces); -namespacesFormat.setRootElement("person"); ----- - -And you can achieve the same in Spring DSL. - -[[XmlJson-Example]] -Example -+++++++ - -Using the namespace bindings in the Java snippet above on the following -JSON string: - -[source,json] ----- -{ "name": "Raul", "surname": "Kripalani", "f": true, "g": null} ----- - - - -Would yield the following XML: - -[source,xml] ----- -<person xmlns="http://camel.apache.org/default"; xmlns:ns1="http://camel.apache.org/test1";> - <f>true</f> - <g null="true"/> - <name>Raul</name> - <surname xmlns:ns2="http://camel.apache.org/personalData"; xmlns:ns3="http://camel.apache.org/personalData2";>Kripalani</surname> -</person> ----- - -Remember that the JSON spec defines a JSON object as follows: - -_________________________________________________________ -An object is an unordered set of name/value pairs. [...]. -_________________________________________________________ - -That's why the elements are in a different order in the output XML. - -[[XmlJson-Dependencies]] -Dependencies -^^^^^^^^^^^^ - -To use the link:xmljson.html[XmlJson] dataformat in your camel routes -you need to add the following dependency to your pom: - -[source,xml] ----- -<dependency> - <groupId>org.apache.camel</groupId> - <artifactId>camel-xmljson</artifactId> - <version>x.x.x</version> - <!-- Use the same version as camel-core, but remember that this component is only available from 2.10 onwards --> -</dependency> - -<!-- And also XOM must be included. XOM cannot be included by default due to an incompatible -license with ASF; so add this manually --> -<dependency> - <groupId>xom</groupId> - <artifactId>xom</artifactId> - <version>1.2.5</version> -</dependency> ----- - -[[XmlJson-SeeAlso]] -See Also -^^^^^^^^ - -* link:data-format.html[Data Format] -* http://json-lib.sourceforge.net/[json-lib] http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-xmlsecurity/src/main/docs/xmlsecurity-component.adoc ---------------------------------------------------------------------- diff --git a/components/camel-xmlsecurity/src/main/docs/xmlsecurity-component.adoc b/components/camel-xmlsecurity/src/main/docs/xmlsecurity-component.adoc index 19f284a..e330b78 100644 --- a/components/camel-xmlsecurity/src/main/docs/xmlsecurity-component.adoc +++ b/components/camel-xmlsecurity/src/main/docs/xmlsecurity-component.adoc @@ -233,13 +233,14 @@ Component Options + // component options: START The XML Security component supports 43 options which are listed below. {% raw %} -[width="100%",cols="2s,1m,8",options="header"] +[width="100%",cols="2s,1m,7",options="header"] |======================================================================= | Name | Java Type | Description | signerConfiguration | XmlSignerConfiguration | To use a shared XmlSignerConfiguration configuration to use as base for configuring endpoints. Properties of the shared configuration can also be set individually. @@ -293,6 +294,7 @@ The XML Security component supports 43 options which are listed below. + [[XMLSecuritycomponent-EndpointOptions]] Endpoint Options ^^^^^^^^^^^^^^^^ http://git-wip-us.apache.org/repos/asf/camel/blob/96f3710b/components/camel-xstream/src/main/docs/xstream-dataformat.adoc ---------------------------------------------------------------------- diff --git a/components/camel-xstream/src/main/docs/xstream-dataformat.adoc b/components/camel-xstream/src/main/docs/xstream-dataformat.adoc new file mode 100644 index 0000000..14ce541 --- /dev/null +++ b/components/camel-xstream/src/main/docs/xstream-dataformat.adoc @@ -0,0 +1,124 @@ +[[XStream-XStream]] +XStream +~~~~~~~ + +XStream is a link:data-format.html[Data Format] which uses the +http://xstream.codehaus.org/[XStream library] to marshal and unmarshal +Java objects to and from XML. + +To use XStream in your camel routes you need to add the a dependency +on *camel-xstream* which implements this data format. + +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-xstream</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +---------------------------------------------------------- + +[[XStream-UsingtheJavaDSL]] +Using the Java DSL +^^^^^^^^^^^^^^^^^^ + +[source,java] +----------------------------------------------------------- +// lets turn Object messages into XML then send to MQSeries +from("activemq:My.Queue"). + marshal().xstream(). + to("mqseries:Another.Queue"); +----------------------------------------------------------- + +If you would like to configure the `XStream` instance used by the Camel +for the message transformation, you can simply pass a reference to that +instance on the DSL level. + +[source,java] +--------------------------------------------------------- +XStream xStream = new XStream(); +xStream.aliasField("money", PurchaseOrder.class, "cash"); +// new Added setModel option since Camel 2.14 +xStream.setModel("NO_REFERENCES"); +... + +from("direct:marshal"). + marshal(new XStreamDataFormat(xStream)). + to("mock:marshaled"); +--------------------------------------------------------- + +[[XStream-XMLInputFactoryandXMLOutputFactory]] +XMLInputFactory and XMLOutputFactory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +http://xstream.codehaus.org/[The XStream library] uses the +`javax.xml.stream.XMLInputFactory` and +`javax.xml.stream.XMLOutputFactory`, you can control which +implementation of this factory should be used. + +The Factory is discovered using this algorithm: + 1. Use the `javax.xml.stream.XMLInputFactory` , +`javax.xml.stream.XMLOutputFactory` system property. + 2. Use the `lib/xml.stream.properties` file in the `JRE_HOME` +directory. + 3. Use the Services API, if available, to determine the classname by +looking in the `META-INF/services/javax.xml.stream.XMLInputFactory`, +`META-INF/services/javax.xml.stream.XMLOutputFactory` files in jars +available to the JRE. + 4. Use the platform default XMLInputFactory,XMLOutputFactory instance. + +[[XStream-HowtosettheXMLencodinginXstreamDataFormat]] +How to set the XML encoding in Xstream DataFormat? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +From Camel 2.2.0, you can set the encoding of XML in Xstream DataFormat +by setting the Exchange's property with the key `Exchange.CHARSET_NAME`, +or setting the encoding property on Xstream from DSL or Spring config. + +[source,java] +------------------------------- +from("activemq:My.Queue"). + marshal().xstream("UTF-8"). + to("mqseries:Another.Queue"); +------------------------------- + +[[XStream-SettingthetypepermissionsofXstreamDataFormat]] +Setting the type permissions of Xstream DataFormat +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In Camel, one can always use its own processing step in the route to +filter and block certain XML documents to be routed to the XStream's +unmarhall step. From Camel 2.16.1, 2.15.5, you can +set http://x-stream.github.io/security.html[XStream's type +permissions] to automatically allow or deny the instantiation of certain +types. + +The default type permissions setting used by Camel denies all types +except for those from java.lang and java.util packages. This setting can +be changed by setting System property +org.apache.camel.xstream.permissions. Its value is a string of +comma-separated permission terms, each representing a type being allowed +or denied, depending on whether the term is prefixed with '+' (note '+' +may be omitted) or with '-', respectively. + +Each term may contain a wildcard character '*'. For example, value +"-*,java.lang.*,java.util.*" indicates denying all types except for +java.lang.* and java.util.* classes. Setting this value to an empty +string "" reverts to the default XStream's type permissions handling +which denies certain blacklisted classes and allow others. + +The type permissions setting can be extended at an individual XStream +DataFormat instance by setting its type permissions property. + +[source,java] +------------------------------------------------------------------- + <dataFormats> + <xstream id="xstream-default" + permissions="org.apache.camel.samples.xstream.*"/> + ... + +-------------------------------------------------------------------
