You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2016/02/09 08:39:10 UTC
[1/5] camel git commit: XML Security component Asciidoc documentation
Repository: camel
Updated Branches:
refs/heads/master 2e032ff0e -> 942496c66
XML Security component Asciidoc documentation
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/dffb0d61
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/dffb0d61
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/dffb0d61
Branch: refs/heads/master
Commit: dffb0d61172f68f2bb16dde7f6725d2aa6526d36
Parents: 2e032ff
Author: Antonin Stefanutti <an...@stefanutti.fr>
Authored: Mon Feb 8 10:25:47 2016 +0100
Committer: Claus Ibsen <da...@apache.org>
Committed: Tue Feb 9 08:38:57 2016 +0100
----------------------------------------------------------------------
.../src/main/docs/xmlsecurity.adoc | 708 +++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 709 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/dffb0d61/components/camel-xmlsecurity/src/main/docs/xmlsecurity.adoc
----------------------------------------------------------------------
diff --git a/components/camel-xmlsecurity/src/main/docs/xmlsecurity.adoc b/components/camel-xmlsecurity/src/main/docs/xmlsecurity.adoc
new file mode 100644
index 0000000..f50f9a0
--- /dev/null
+++ b/components/camel-xmlsecurity/src/main/docs/xmlsecurity.adoc
@@ -0,0 +1,708 @@
+[[XMLSecuritycomponent-XMLSecuritycomponent]]
+XML Security component
+~~~~~~~~~~~~~~~~~~~~~~
+
+*Available as of Camel 2.12.0*
+
+With this Apache Camel component, you can generate and validate XML
+signatures as described in the W3C standard
+http://www.w3.org/TR/xmldsig-core/[XML Signature Syntax and Processing]
+or as described in the successor
+http://www.w3.org/TR/xmldsig-core1/[version 1.1]. For XML Encryption
+support, please refer to the XML Security link:data-format.html[Data
+Format].
+
+You can find an introduction to XML signature
+http://www.oracle.com/technetwork/articles/javase/dig-signatures-141823.html[here].
+The implementation of the component is based on
+http://docs.oracle.com/javase/6/docs/technotes/guides/security/xmldsig/overview.html[JSR
+105], the Java API corresponding to the W3C standard and supports the
+Apache Santuario and the JDK provider for JSR 105. The implementation
+will first try to use the Apache Santuario provider; if it does not find
+the Santuario provider, it will use the JDK provider. Further, the
+implementation is DOM based.
+
+Since Camel 2.15.0 we also provide support for *XAdES-BES/EPES* for the
+signer endpoint; see subsection "XAdES-BES/EPES for the Signer
+Endpoint".
+
+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-xmlsecurity</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel core version -->
+</dependency>
+----
+
+[[XMLSecuritycomponent-XMLSignatureWrappingModes]]
+XML Signature Wrapping Modes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+XML Signature differs between enveloped, enveloping, and detached XML
+signature. In the
+http://www.w3.org/TR/xmldsig-core1/#def-SignatureEnveloped[enveloped]
+XML signature case, the XML Signature is wrapped by the signed XML
+Document; which means that the XML signature element is a child element
+of a parent element, which belongs to the signed XML Document. In the
+http://www.w3.org/TR/xmldsig-core1/#def-SignatureEnveloping[enveloping]
+XML signature case, the XML Signature contains the signed content. All
+other cases are called
+http://www.w3.org/TR/xmldsig-core1/#def-SignatureDetached[detached] XML
+signatures. A certain form of detached XML signature is supported since
+**2.14.0**.
+
+In the *enveloped XML signature* case, the supported generated XML
+signature has the following structure (Variables are surrounded by `[]`).
+
+[source,xml]
+----
+<[parent element]>
+ ... <!-- Signature element is added as last child of the parent element-->
+ <Signature Id="generated_unique_signature_id">
+ <SignedInfo>
+ <Reference URI="">
+ <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
+ (<Transform>)* <!-- By default "http://www.w3.org/2006/12/xml-c14n11" is added to the transforms -->
+ <DigestMethod>
+ <DigestValue>
+ </Reference>
+ (<Reference URI="#[keyinfo_Id]">
+ <Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
+ <DigestMethod>
+ <DigestValue>
+ </Reference>)?
+ <!-- further references possible, see option 'properties' below -->
+ </SignedInfo>
+ <SignatureValue>
+ (<KeyInfo Id="[keyinfo_id]">)?
+ <!-- Object elements possible, see option 'properties' below -->
+ </Signature>
+</[parent element]>
+----
+
+In the *enveloping XML signature* case, the supported generated XML
+signature has the structure:
+
+[source,xml]
+----
+<Signature Id="generated_unique_signature_id">
+ <SignedInfo>
+ <Reference URI="#generated_unique_object_id" type="[optional_type_value]">
+ (<Transform>)* <!-- By default "http://www.w3.org/2006/12/xml-c14n11" is added to the transforms -->
+ <DigestMethod>
+ <DigestValue>
+ </Reference>
+ (<Reference URI="#[keyinfo_id]">
+ <Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
+ <DigestMethod>
+ <DigestValue>
+ </Reference>)?
+ <!-- further references possible, see option 'properties' below -->
+ </SignedInfo>
+ <SignatureValue>
+ (<KeyInfo Id="[keyinfo_id]">)?
+ <Object Id="generated_unique_object_id"/> <!-- The Object element contains the in-message body; the object ID can either be generated or set by the option parameter "contentObjectId" -->
+ <!-- Further Object elements possible, see option 'properties' below -->
+</Signature>
+----
+
+As of 2.14.0 *detached XML signatures* with the following structure
+are supported (see also sub-chapter XML Signatures as Siblings of Signed
+Elements):
+
+[source,xml]
+----
+(<[signed element] Id="[id_value]">
+<!-- signed element must have an attribute of type ID -->
+ ...
+
+</[signed element]>
+<other sibling/>*
+<!-- between the signed element and the corresponding signature element, there can be other siblings.
+ Signature element is added as last sibling. -->
+<Signature Id="generated_unique_ID">
+ <SignedInfo>
+ <CanonicalizationMethod>
+ <SignatureMethod>
+ <Reference URI="#[id_value]" type="[optional_type_value]">
+ <!-- reference URI contains the ID attribute value of the signed element -->
+ (<Transform>)* <!-- By default "http://www.w3.org/2006/12/xml-c14n11" is added to the transforms -->
+ <DigestMethod>
+ <DigestValue>
+ </Reference>
+ (<Reference URI="#[generated_keyinfo_Id]">
+ <Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
+ <DigestMethod>
+ <DigestValue>
+ </Reference>)?
+ </SignedInfo>
+ <SignatureValue>
+ (<KeyInfo Id="[generated_keyinfo_id]">)?
+</Signature>)+
+----
+
+
+
+[[XMLSecuritycomponent-URIFormat]]
+URI Format
+^^^^^^^^^^
+
+The camel component consists of two endpoints which have the following
+URI format:
+
+[source]
+----
+xmlsecurity:sign:name[?options]
+xmlsecurity:verify:name[?options]
+----
+
+* With the signer endpoint, you can generate a XML signature for the
+body of the in-message which can be either a XML document or a plain
+text. The enveloped, enveloping, or detached (as of 12.14) XML
+signature(s) will be set to the body of the out-message.
+* With the verifier endpoint, you can validate an enveloped or
+enveloping XML signature or even several detached (as of 2.14.0) XML
+signatures contained in the body of the in-message; if the validation is
+successful, then the original content is extracted from the XML
+signature and set to the body of the out-message.
+* The `name` part in the URI can be chosen by the user to distinguish
+between different signer/verifier endpoints within the camel context.
+
+[[XMLSecuritycomponent-BasicExample]]
+Basic Example
+^^^^^^^^^^^^^
+
+The following example shows the basic usage of the component.
+
+[source,java]
+----
+from("direct:enveloping").to("xmlsecurity:sign://enveloping?keyAccessor=#accessor",
+ "xmlsecurity:verify://enveloping?keySelector=#selector",
+ "mock:result")
+----
+
+In Spring XML:
+
+[source,xml]
+----
+<from uri="direct:enveloping" />
+ <to uri="xmlsecurity:sign://enveloping?keyAccessor=#accessor" />
+ <to uri="xmlsecurity:verify://enveloping?keySelector=#selector" />
+<to uri="mock:result" />
+----
+
+For the signing process, a private key is necessary. You specify a key
+accessor bean which provides this private key. For the validation, the
+corresponding public key is necessary; you specify a key selector bean
+which provides this public key.
+
+The key accessor bean must implement the
+https://github.com/apache/camel/blob/master/components/camel-xmlsecurity/src/main/java/org/apache/camel/component/xmlsecurity/api/KeyAccessor.java[`KeyAccessor`]
+interface. The package `org.apache.camel.component.xmlsecurity.api`
+contains the default implementation class
+https://github.com/apache/camel/blob/master/components/camel-xmlsecurity/src/main/java/org/apache/camel/component/xmlsecurity/api/DefaultKeyAccessor.java[`DefaultKeyAccessor`]
+which reads the private key from a Java keystore.
+
+The key selector bean must implement the
+http://docs.oracle.com/javase/6/docs/api/javax/xml/crypto/KeySelector.html[`javax.xml.crypto.KeySelector`]
+interface. The package `org.apache.camel.component.xmlsecurity.api`
+contains the default implementation class
+https://github.com/apache/camel/blob/master/components/camel-xmlsecurity/src/main/java/org/apache/camel/component/xmlsecurity/api/DefaultKeySelector.java[`DefaultKeySelector`]
+which reads the public key from a keystore.
+
+In the example, the default signature algorithm
+`http://www.w3.org/2000/09/xmldsig#rsa-sha1` is used. You can set the
+signature algorithm of your choice by the option `signatureAlgorithm`
+(see below). The signer endpoint creates an _enveloping_ XML signature.
+If you want to create an _enveloped_ XML signature then you must specify
+the parent element of the Signature element; see option
+`parentLocalName` for more details.
+
+For creating _detached_ XML signatures, see sub-chapter "Detached XML
+Signatures as Siblings of the Signed Elements".
+
+[[XMLSecuritycomponent-ComponentOptions]]
+Component Options
+^^^^^^^^^^^^^^^^
+
+// component options: START
+The XML Security component supports 2 options which are listed below.
+
+
+[width="100%",cols="2s,1m,8",options="header"]
+|=======================================================================
+| Name | Java Type | Description
+| signerConfiguration | XmlSignerConfiguration | To use a shared XmlSignerConfiguration configuration to use as base for configuring endpoints.
+| verifierConfiguration | XmlVerifierConfiguration | To use a shared XmlVerifierConfiguration configuration to use as base for configuring endpoints.
+|=======================================================================
+// component options: END
+
+
+[[XMLSecuritycomponent-EndpointOptions]]
+Endpoint Options
+^^^^^^^^^^^^^^^^
+
+// endpoint options: START
+The XML Security component supports 38 endpoint options which are listed below:
+
+[width="100%",cols="2s,1,1m,1m,5",options="header"]
+|=======================================================================
+| Name | Group | Default | Java Type | Description
+| command | producer | | XmlCommand | *Required* Whether to sign or verify.
+| name | producer | | String | *Required* The name part in the URI can be chosen by the user to distinguish between different signer/verifier endpoints within the camel context.
+| baseUri | common | | String | You can set a base URI which is used in the URI dereferencing. Relative URIs are then concatenated with the base URI.
+| clearHeaders | common | true | Boolean | Determines if the XML signature specific headers be cleared after signing and verification. Defaults to true.
+| cryptoContextProperties | common | | Map | Sets the crypto context properties. See link XMLCryptoContextsetProperty(String Object). Possible properties are defined in XMLSignContext an XMLValidateContext (see Supported Properties). The following properties are set by default to the value link BooleanTRUE for the XML validation. If you want to switch these features off you must set the property value to link BooleanFALSE. org.jcp.xml.dsig.validateManifests javax.xml.crypto.dsig.cacheReference
+| disallowDoctypeDecl | common | true | Boolean | Disallows that the incoming XML document contains DTD DOCTYPE declaration. The default value is link BooleanTRUE.
+| omitXmlDeclaration | common | false | Boolean | Indicator whether the XML declaration in the outgoing message body should be omitted. Default value is false. Can be overwritten by the header link XmlSignatureConstantsHEADER_OMIT_XML_DECLARATION.
+| outputXmlEncoding | common | | String | The character encoding of the resulting signed XML document. If null then the encoding of the original XML document is used.
+| schemaResourceUri | common | | String | Classpath to the XML Schema. Must be specified in the detached XML Signature case for determining the ID attributes might be set in the enveloped and enveloping case. If set then the XML document is validated with the specified XML schema. The schema resource URI can be overwritten by the header link XmlSignatureConstantsHEADER_SCHEMA_RESOURCE_URI.
+| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange
+| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
+| uriDereferencer | advanced | | URIDereferencer | If you want to restrict the remote access via reference URIs you can set an own dereferencer. Optional parameter. If not set the provider default dereferencer is used which can resolve URI fragments HTTP file and XPpointer URIs. Attention: The implementation is provider dependent!
+| addKeyInfoReference | sign | true | Boolean | In order to protect the KeyInfo element from tampering you can add a reference to the signed info element so that it is protected via the signature value. The default value is true. Only relevant when a KeyInfo is returned by KeyAccessor. and link KeyInfogetId() is not null.
+| canonicalizationMethod | sign | http://www.w3.org/TR/2001/REC-xml-c14n-20010315 | AlgorithmMethod | Canonicalization method used to canonicalize the SignedInfo element before the digest is calculated. You can use the helper methods XmlSignatureHelper.getCanonicalizationMethod(String algorithm) or getCanonicalizationMethod(String algorithm List inclusiveNamespacePrefixes) to create a canonicalization method.
+| contentObjectId | sign | | String | Sets the content object Id attribute value. By default a UUID is generated. If you set the null value then a new UUID will be generated. Only used in the enveloping case.
+| contentReferenceType | sign | | String | Type of the content reference. The default value is null. This value can be overwritten by the header link XmlSignatureConstantsHEADER_CONTENT_REFERENCE_TYPE.
+| contentReferenceUri | sign | | String | Reference URI for the content to be signed. Only used in the enveloped case. If the reference URI contains an ID attribute value then the resource schema URI ( link setSchemaResourceUri(String)) must also be set because the schema validator will then find out which attributes are ID attributes. Will be ignored in the enveloping or detached case.
+| digestAlgorithm | sign | | String | Digest algorithm URI. Optional parameter. This digest algorithm is used for calculating the digest of the input message. If this digest algorithm is not specified then the digest algorithm is calculated from the signature algorithm. Example: http://www.w3.org/2001/04/xmlencsha256
+| keyAccessor | sign | | KeyAccessor | For the signing process a private key is necessary. You specify a key accessor bean which provides this private key. The key accessor bean must implement the KeyAccessor interface. The package org.apache.camel.component.xmlsecurity.api contains the default implementation class DefaultKeyAccessor which reads the private key from a Java keystore.
+| parentLocalName | sign | | String | Local name of the parent element to which the XML signature element will be added. Only relevant for enveloped XML signature. Alternatively you can also use link setParentXpath(XPathFilterParameterSpec). Default value is null. The value must be null for enveloping and detached XML signature. This parameter or the parameter link setParentXpath(XPathFilterParameterSpec) for enveloped signature and the parameter link setXpathsToIdAttributes(List) for detached signature must not be set in the same configuration. If the parameters parentXpath and parentLocalName are specified in the same configuration then an exception is thrown.
+| parentNamespace | sign | | String | Namespace of the parent element to which the XML signature element will be added.
+| parentXpath | sign | | XPathFilterParameterSpec | Sets the XPath to find the parent node in the enveloped case. Either you specify the parent node via this method or the local name and namespace of the parent with the methods link setParentLocalName(String) and link setParentNamespace(String). Default value is null. The value must be null for enveloping and detached XML signature. If the parameters parentXpath and parentLocalName are specified in the same configuration then an exception is thrown.
+| plainText | sign | false | Boolean | Indicator whether the message body contains plain text. The default value is false indicating that the message body contains XML. The value can be overwritten by the header link XmlSignatureConstantsHEADER_MESSAGE_IS_PLAIN_TEXT.
+| plainTextEncoding | sign | UTF-8 | String | Encoding of the plain text. Only relevant if the message body is plain text (see parameter link plainText. Default value is UTF-8.
+| prefixForXmlSignatureNamespace | sign | ds | String | Namespace prefix for the XML signature namespace http://www.w3.org/2000/09/xmldsig. Default value is ds. If null or an empty value is set then no prefix is used for the XML signature namespace. See best practice http://www.w3.org/TR/xmldsig-bestpractices/signing-xml- without-namespaces
+| properties | sign | | XmlSignatureProperties | For adding additional References and Objects to the XML signature which contain additional properties you can provide a bean which implements the XmlSignatureProperties interface.
+| signatureAlgorithm | sign | http://www.w3.org/2000/09/xmldsig#rsa-sha1 | String | Signature algorithm. Default value is http://www.w3.org/2000/09/xmldsigrsa-sha1.
+| signatureId | sign | | String | Sets the signature Id. If this parameter is not set (null value) then a unique ID is generated for the signature ID (default). If this parameter is set to (empty string) then no Id attribute is created in the signature element.
+| transformMethods | sign | | List | Transforms which are executed on the message body before the digest is calculated. By default C14n is added and in the case of enveloped signature (see option parentLocalName) also http://www.w3.org/2000/09/xmldsigenveloped-signature is added at position 0 of the list. Use methods in XmlSignatureHelper to create the transform methods.
+| xpathsToIdAttributes | sign | | List | Define the elements which are signed in the detached case via XPATH expressions to ID attributes (attributes of type ID). For each element found via the XPATH expression a detached signature is created whose reference URI contains the corresponding attribute value (preceded by ''). The signature becomes the last sibling of the signed element. Elements with deeper hierarchy level are signed first. You can also set the XPATH list dynamically via the header link XmlSignatureConstantsHEADER_XPATHS_TO_ID_ATTRIBUTES. The parameter link setParentLocalName(String) or link setParentXpath(XPathFilterParameterSpec) for enveloped signature and this parameter for detached signature must not be set in the same configuration.
+| keySelector | verify | | KeySelector | Provides the key for validating the XML signature.
+| outputNodeSearch | verify | | String | Sets the output node search value for determining the node from the XML signature document which shall be set to the output message body. The class of the value depends on the type of the output node search. The output node search is forwarded to XmlSignature2Message.
+| outputNodeSearchType | verify | Default | String | Determines the search type for determining the output node which is serialized into the output message bodyF. See link setOutputNodeSearch(Object). The supported default search types you can find in DefaultXmlSignature2Message.
+| removeSignatureElements | verify | false | Boolean | Indicator whether the XML signature elements (elements with local name Signature and namesapce http://www.w3.org/2000/09/xmldsig) shall be removed from the document set to the output message. Normally this is only necessary if the XML signature is enveloped. The default value is link BooleanFALSE. This parameter is forwarded to XmlSignature2Message. This indicator has no effect if the output node search is of type link DefaultXmlSignature2MessageOUTPUT_NODE_SEARCH_TYPE_DEFAULT.F
+| secureValidation | verify | true | Boolean | Enables secure validation. If true then secure validation is enabled.
+| validationFailedHandler | verify | | ValidationFailedHandler | Handles the different validation failed situations. The default implementation throws specific exceptions for the different situations (All exceptions have the package name org.apache.camel.component.xmlsecurity.api and are a sub-class of XmlSignatureInvalidException. If the signature value validation fails a XmlSignatureInvalidValueException is thrown. If a reference validation fails a XmlSignatureInvalidContentHashException is thrown. For more detailed information see the JavaDoc.
+| xmlSignature2Message | verify | | XmlSignature2Message | Bean which maps the XML signature to the output-message after the validation. How this mapping should be done can be configured by the options outputNodeSearchType outputNodeSearch and removeSignatureElements. The default implementation offers three possibilities which are related to the three output node search types Default ElementName and XPath. The default implementation determines a node which is then serialized and set to the body of the output message If the search type is ElementName then the output node (which must be in this case an element) is determined by the local name and namespace defined in the search value (see option outputNodeSearch). If the search type is XPath then the output node is determined by the XPath specified in the search value (in this case the output node can be of type Element TextNode or Document). If the output node search type is Default then the following rules apply: In the enveloped X
ML signature case (there is a reference with URI= and transform http://www.w3.org/2000/09/xmldsigenveloped-signature) the incoming XML document without the Signature element is set to the output message body. In the non-enveloped XML signature case the message body is determined from a referenced Object; this is explained in more detail in chapter Output Node Determination in Enveloping XML Signature Case.
+| xmlSignatureChecker | verify | | XmlSignatureChecker | This interface allows the application to check the XML signature before the validation is executed. This step is recommended in http://www.w3.org/TR/xmldsig-bestpractices/check-what-is-signed
+|=======================================================================
+// endpoint options: END
+
+
+[[XMLSecuritycomponent-OutputNodeDeterminationinEnvelopingXMLSignatureCase]]
+Output Node Determination in Enveloping XML Signature Case
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+After the validation the node is extracted from the XML signature
+document which is finally returned to the output-message body. In the
+enveloping XML signature case, the default implementation
+https://github.com/apache/camel/blob/master/components/camel-xmlsecurity/src/main/java/org/apache/camel/component/xmlsecurity/api/DefaultXmlSignature2Message.java[`DefaultXmlSignature2Message`]
+of
+https://github.com/apache/camel/blob/master/components/camel-xmlsecurity/src/main/java/org/apache/camel/component/xmlsecurity/api/XmlSignature2Message.java[`XmlSignature2Message`]
+does this for the node search type `Default` in the following way (see
+option `xmlSignature2Message`):
+
+* First an object reference is determined:
+
+** Only same document references are taken into account (URI must start
+with `#`)
+** Also indirect same document references to an object via manifest are
+taken into account.
+** The resulting number of object references must be 1.
+
+* Then, the object is dereferenced and the object must only contain one
+XML element. This element is returned as output node.
+
+This does mean that the enveloping XML signature must have either the
+structure:
+
+[source,xml]
+----
+<Signature>
+ <SignedInfo>
+ <Reference URI="#object"/>
+ <!-- further references possible but they must not point to an Object or Manifest containing an object reference -->
+ ...
+ </SignedInfo>
+
+ <Object Id="object">
+ <!-- contains one XML element which is extracted to the message body -->
+ <Object>
+ <!-- further object elements possible which are not referenced-->
+ ...
+ (<KeyInfo>)?
+</Signature>
+----
+
+or the structure:
+
+[source,xml]
+----
+<Signature>
+ <SignedInfo>
+ <Reference URI="#manifest"/>
+ <!-- further references are possible but they must not point to an Object or other manifest containing an object reference -->
+ ...
+ </SignedInfo>
+
+ <Object >
+ <Manifest Id="manifest">
+ <Reference URI=#object/>
+ </Manifest>
+ </Objet>
+ <Object Id="object">
+ <!-- contains the DOM node which is extracted to the message body -->
+ </Object>
+ <!-- further object elements possible which are not referenced -->
+ ...
+ (<KeyInfo>)?
+</Signature>
+----
+
+[[XMLSecuritycomponent-DetachedXMLSignaturesasSiblingsoftheSignedElements]]
+Detached XML Signatures as Siblings of the Signed Elements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Since 2.14.0**
+
+You can create detached signatures where the signature is a sibling of
+the signed element. The following example contains two detached
+signatures. The first signature is for the element `C` and the second
+signature is for element `A`. The signatures are _nested_; the second
+signature is for the element `A` which also contains the first signature.
+
+*Example Detached XML Signatures*
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" ?>
+<root>
+ <A ID="IDforA">
+ <B>
+ <C ID="IDforC">
+ <D>dvalue</D>
+ </C>
+ <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
+ Id="_6bf13099-0568-4d76-8649-faf5dcb313c0">
+ <ds:SignedInfo>
+ <ds:CanonicalizationMethod
+ Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
+ <ds:SignatureMethod
+ Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
+ <ds:Reference URI="#IDforC">
+ ...
+ </ds:Reference>
+ </ds:SignedInfo>
+ <ds:SignatureValue>aUDFmiG71</ds:SignatureValue>
+ </ds:Signature>
+ </B>
+ </A>
+ <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"Id="_6b02fb8a-30df-42c6-ba25-76eba02c8214">
+ <ds:SignedInfo>
+ <ds:CanonicalizationMethod
+ Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
+ <ds:SignatureMethod
+ Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
+ <ds:Reference URI="#IDforA">
+ ...
+ </ds:Reference>
+ </ds:SignedInfo>
+ <ds:SignatureValue>q3tvRoGgc8cMUqUSzP6C21zb7tt04riPnDuk=</ds:SignatureValue>
+ </ds:Signature>
+<root>
+----
+
+The example shows that you can sign several elements and that for each
+element a signature is created as sibling. The elements to be signed
+must have an attribute of type ID. The ID type of the attribute must be
+defined in the XML schema (see option `schemaResourceUri`). You
+specify a list of XPATH expressions pointing to attributes of type ID
+(see option `xpathsToIdAttributes`). These attributes determine the
+elements to be signed. The elements are signed by the same key given by
+the `keyAccessor` bean. Elements with higher (i.e. deeper) hierarchy level
+are signed first. In the example, the element `C` is signed before the
+element `A`.
+
+*Java DSL Example*
+
+[source,java]
+----
+from("direct:detached")
+ .to("xmlsecurity:sign://detached?keyAccessor=#keyAccessorBeant&xpathsToIdAttributes=#xpathsToIdAttributesBean&schemaResourceUri=Test.xsd")
+ .to("xmlsecurity:verify://detached?keySelector=#keySelectorBean&schemaResourceUri=org/apache/camel/component/xmlsecurity/Test.xsd")
+ .to("mock:result");
+----
+
+*Spring Example*
+
+[source,xml]
+----
+
+<bean id="xpathsToIdAttributesBean" class="java.util.ArrayList">
+ <constructor-arg type="java.util.Collection">
+ <list>
+ <bean
+ class="org.apache.camel.component.xmlsecurity.api.XmlSignatureHelper"
+ factory-method="getXpathFilter">
+ <constructor-arg type="java.lang.String"
+ value="/ns:root/a/@ID" />
+ <constructor-arg>
+ <map key-type="java.lang.String" value-type="java.lang.String">
+ <entry key="ns" value="http://test" />
+ </map>
+ </constructor-arg>
+ </bean>
+ </list>
+ </constructor-arg>
+ </bean>
+...
+ <from uri="direct:detached" />
+ <to
+ uri="xmlsecurity:sign://detached?keyAccessor=#keyAccessorBean&xpathsToIdAttributes=#xpathsToIdAttributesBean&schemaResourceUri=Test.xsd" />
+ <to
+ uri="xmlsecurity:verify://detached?keySelector=#keySelectorBean&schemaResourceUri=Test.xsd" />
+ <to uri="mock:result" />
+----
+
+
+[[XMLSecuritycomponent-XAdES-BESEPESfortheSignerEndpoint]]
+XAdES-BES/EPES for the Signer Endpoint
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Available as of Camel 2.15.0*
+
+http://www.etsi.org/deliver/etsi_ts/101900_101999/101903/01.04.02_60/ts_101903v010402p.pdf[XML
+Advanced Electronic Signatures (XAdES)] defines extensions to XML
+Signature. This standard was defined by the
+http://www.etsi.org/[European Telecommunication Standards Institute] and
+allows you to create signatures which are compliant to the
+http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2000:013:0012:0020:EN:PDF[European
+Union Directive (1999/93/EC) on a Community framework for electronic
+signatures]. XAdES defines different sets of signature properties which
+are called signature forms. We support the signature forms *Basic
+Electronic Signature* (XAdES-BES) and *Explicit Policy Based Electronic
+Signature* (XAdES-EPES) for the Signer Endpoint. The forms
+**Electronic ****Signature with Validation Data** XAdES-T and XAdES-C
+are not supported.
+
+
+We support the following properties of the XAdES-EPES form ("?" denotes
+zero or one occurrence):
+
+
+*Supported XAdES-EPES Properties*
+
+[source,xml]
+----
+<QualifyingProperties Target>
+ <SignedProperties>
+ <SignedSignatureProperties>
+ (SigningTime)?
+ (SigningCertificate)?
+ (SignaturePolicyIdentifier)
+ (SignatureProductionPlace)?
+ (SignerRole)?
+ </SignedSignatureProperties>
+ <SignedDataObjectProperties>
+ (DataObjectFormat)?
+ (CommitmentTypeIndication)?
+ </SignedDataObjectProperties>
+ </SignedProperties>
+</QualifyingProperties>
+----
+
+The properties of the XAdES-BES form are the same except that
+the `SignaturePolicyIdentifier` property is not part of XAdES-BES.
+
+You can configure the XAdES-BES/EPES properties via the
+bean `org.apache.camel.component.xmlsecurity.api.XAdESSignatureProperties`
+or `org.apache.camel.component.xmlsecurity.api.DefaultXAdESSignatureProperties. XAdESSignatureProperties` does
+support all properties mentioned above except
+the `SigningCertificate` property. To get
+the `SigningCertificate` property, you must overwrite either the
+method `XAdESSignatureProperties.getSigningCertificate()` or `XAdESSignatureProperties.getSigningCertificateChain()`. The
+class `DefaultXAdESSignatureProperties` overwrites the
+method `getSigningCertificate()` and allows you to specify the signing
+certificate via a keystore and alias. The following example shows all
+parameters you can specify. If you do not need certain parameters you
+can just omit them.
+
+*XAdES-BES/EPES Example in Java DSL*
+
+[source,java]
+----
+ Keystore keystore = ... // load a keystore
+DefaultKeyAccessor accessor = new DefaultKeyAccessor();
+accessor.setKeyStore(keystore);
+accessor.setPassword("password");
+accessor.setAlias("cert_alias"); // signer key alias
+
+DefaultXAdESSignatureProperties props = new DefaultXAdESSignatureProperties();
+props.setNamespace("http://uri.etsi.org/01903/v1.3.2#"); // sets the namespace for the XAdES elements; the namspace is related to the XAdES version, default value is "http://uri.etsi.org/01903/v1.3.2#", other possible values are "http://uri.etsi.org/01903/v1.1.1#" and "http://uri.etsi.org/01903/v1.2.2#"
+props.setPrefix("etsi"); // sets the prefix for the XAdES elements, default value is "etsi"
+
+// signing certificate
+props.setKeystore(keystore));
+props.setAlias("cert_alias"); // specify the alias of the signing certificate in the keystore = signer key alias
+props.setDigestAlgorithmForSigningCertificate(DigestMethod.SHA256); // possible values for the algorithm are "http://www.w3.org/2000/09/xmldsig#sha1", "http://www.w3.org/2001/04/xmlenc#sha256", "http://www.w3.org/2001/04/xmldsig-more#sha384", "http://www.w3.org/2001/04/xmlenc#sha512", default value is "http://www.w3.org/2001/04/xmlenc#sha256"
+props.setSigningCertificateURIs(Collections.singletonList("http://certuri"));
+
+// signing time
+props.setAddSigningTime(true);
+
+// policy
+props.setSignaturePolicy(XAdESSignatureProperties.SIG_POLICY_EXPLICIT_ID);
+// also the values XAdESSignatureProperties.SIG_POLICY_NONE ("None"), and XAdESSignatureProperties.SIG_POLICY_IMPLIED ("Implied")are possible, default value is XAdESSignatureProperties.SIG_POLICY_EXPLICIT_ID ("ExplicitId")
+// For "None" and "Implied" you must not specify any further policy parameters
+props.setSigPolicyId("urn:oid:1.2.840.113549.1.9.16.6.1");
+props.setSigPolicyIdQualifier("OIDAsURN"); //allowed values are empty string, "OIDAsURI", "OIDAsURN"; default value is empty string
+props.setSigPolicyIdDescription("invoice version 3.1");
+props.setSignaturePolicyDigestAlgorithm(DigestMethod.SHA256);// possible values for the algorithm are "http://www.w3.org/2000/09/xmldsig#sha1", http://www.w3.org/2001/04/xmlenc#sha256", "http://www.w3.org/2001/04/xmldsig-more#sha384", "http://www.w3.org/2001/04/xmlenc#sha512", default value is http://www.w3.org/2001/04/xmlenc#sha256"
+props.setSignaturePolicyDigestValue("Ohixl6upD6av8N7pEvDABhEL6hM=");
+// you can add qualifiers for the signature policy either by specifying text or an XML fragment with the root element "SigPolicyQualifier"
+props.setSigPolicyQualifiers(Arrays
+ .asList(new String[] {
+ "<SigPolicyQualifier xmlns=\"http://uri.etsi.org/01903/v1.3.2#\"><SPURI>http://test.com/sig.policy.pdf</SPURI><SPUserNotice><ExplicitText>display text</ExplicitText>"
+ + "</SPUserNotice></SigPolicyQualifier>", "category B" }));
+props.setSigPolicyIdDocumentationReferences(Arrays.asList(new String[] {"http://test.com/policy.doc.ref1.txt",
+ "http://test.com/policy.doc.ref2.txt" }));
+
+// production place
+props.setSignatureProductionPlaceCity("Munich");
+props.setSignatureProductionPlaceCountryName("Germany");
+props.setSignatureProductionPlacePostalCode("80331");
+props.setSignatureProductionPlaceStateOrProvince("Bavaria");
+
+//role
+// you can add claimed roles either by specifying text or an XML fragment with the root element "ClaimedRole"
+props.setSignerClaimedRoles(Arrays.asList(new String[] {"test",
+ "<a:ClaimedRole xmlns:a=\"http://uri.etsi.org/01903/v1.3.2#\"><TestRole>TestRole</TestRole></a:ClaimedRole>" }));
+props.setSignerCertifiedRoles(Collections.singletonList(new XAdESEncapsulatedPKIData("Ahixl6upD6av8N7pEvDABhEL6hM=",
+ "http://uri.etsi.org/01903/v1.2.2#DER", "IdCertifiedRole")));
+
+// data object format
+props.setDataObjectFormatDescription("invoice");
+props.setDataObjectFormatMimeType("text/xml");
+props.setDataObjectFormatIdentifier("urn:oid:1.2.840.113549.1.9.16.6.2");
+props.setDataObjectFormatIdentifierQualifier("OIDAsURN"); //allowed values are empty string, "OIDAsURI", "OIDAsURN"; default value is empty string
+props.setDataObjectFormatIdentifierDescription("identifier desc");
+props.setDataObjectFormatIdentifierDocumentationReferences(Arrays.asList(new String[] {
+ "http://test.com/dataobject.format.doc.ref1.txt", "http://test.com/dataobject.format.doc.ref2.txt" }));
+
+//commitment
+props.setCommitmentTypeId("urn:oid:1.2.840.113549.1.9.16.6.4");
+props.setCommitmentTypeIdQualifier("OIDAsURN"); //allowed values are empty string, "OIDAsURI", "OIDAsURN"; default value is empty string
+props.setCommitmentTypeIdDescription("description for commitment type ID");
+props.setCommitmentTypeIdDocumentationReferences(Arrays.asList(new String[] {"http://test.com/commitment.ref1.txt",
+ "http://test.com/commitment.ref2.txt" }));
+// you can specify a commitment type qualifier either by simple text or an XML fragment with root element "CommitmentTypeQualifier"
+props.setCommitmentTypeQualifiers(Arrays.asList(new String[] {"commitment qualifier",
+ "<c:CommitmentTypeQualifier xmlns:c=\"http://uri.etsi.org/01903/v1.3.2#\"><C>c</C></c:CommitmentTypeQualifier>" }));
+
+beanRegistry.bind("xmlSignatureProperties",props);
+beanRegistry.bind("keyAccessorDefault",keyAccessor);
+
+// you must reference the properties bean in the "xmlsecurity" URI
+from("direct:xades").to("xmlsecurity:sign://xades?keyAccessor=#keyAccessorDefault&properties=#xmlSignatureProperties")
+ .to("mock:result");
+----
+
+*XAdES-BES/EPES Example in Spring XML*
+
+[source,xml]
+----
+...
+<from uri="direct:xades" />
+ <to
+ uri="xmlsecurity:sign://xades?keyAccessor=#accessorRsa&properties=#xadesProperties" />
+ <to uri="mock:result" />
+...
+<bean id="xadesProperties"
+ class="org.apache.camel.component.xmlsecurity.api.XAdESSignatureProperties">
+ <!-- For more properties see the the previous Java DSL example.
+ If you want to have a signing certificate then use the bean class DefaultXAdESSignatureProperties (see the previous Java DSL example). -->
+ <property name="signaturePolicy" value="ExplicitId" />
+ <property name="sigPolicyId" value="http://www.test.com/policy.pdf" />
+ <property name="sigPolicyIdDescription" value="factura" />
+ <property name="signaturePolicyDigestAlgorithm" value="http://www.w3.org/2000/09/xmldsig#sha1" />
+ <property name="signaturePolicyDigestValue" value="Ohixl6upD6av8N7pEvDABhEL1hM=" />
+ <property name="signerClaimedRoles" ref="signerClaimedRoles_XMLSigner" />
+ <property name="dataObjectFormatDescription" value="Factura electrónica" />
+ <property name="dataObjectFormatMimeType" value="text/xml" />
+</bean>
+<bean class="java.util.ArrayList" id="signerClaimedRoles_XMLSigner">
+ <constructor-arg>
+ <list>
+ <value>Emisor</value>
+ <value><ClaimedRole
+ xmlns="http://uri.etsi.org/01903/v1.3.2#"><test
+ xmlns="http://test.com/">test</test></ClaimedRole></value>
+ </list>
+ </constructor-arg>
+</bean>
+----
+
+[[XMLSecuritycomponent-Headers]]
+Headers
++++++++
+
+[width="100%",cols="1m,1m,4",options="header",]
+|=======================================================================
+|Header |Type |Description
+|CamelXmlSignatureXAdESQualifyingPropertiesId |String |for the 'Id'
+attribute value of `QualifyingProperties` element
+
+|CamelXmlSignatureXAdESSignedDataObjectPropertiesId |String |for the
+'Id' attribute value of `SignedDataObjectProperties` element
+
+|CamelXmlSignatureXAdESSignedSignaturePropertiesId |String |for the
+'Id' attribute value of `SignedSignatureProperties` element
+
+|CamelXmlSignatureXAdESDataObjectFormatEncoding |String |for the value
+of the Encoding element of the `DataObjectFormat` element
+
+|CamelXmlSignatureXAdESNamespace |String | overwrites the XAdES
+namespace parameter value
+
+|CamelXmlSignatureXAdESPrefix |String |overwrites the XAdES prefix
+parameter value
+|=======================================================================
+
+[[XMLSecuritycomponent-LimitationswithregardtoXAdESversion1.4.2]]
+Limitations with regard to XAdES version 1.4.2
+++++++++++++++++++++++++++++++++++++++++++++++
+
+* No support for signature form XAdES-T and XAdES-C
+* Only signer part implemented. Verifier part currently not available.
+* No support for the `QualifyingPropertiesReference` element (see
+section 6.3.2 of spec).
+* No support for the `Transforms` element contained in
+the `SignaturePolicyId` element contained in
+the `SignaturePolicyIdentifier element`
+* No support of the `CounterSignature` element -> no support for
+the `UnsignedProperties` element
+* At most one `DataObjectFormat` element. More than one
+`DataObjectFormat` element makes no sense because we have only one data
+object which is signed (this is the incoming message body to the XML
+signer endpoint).
+* At most one `CommitmentTypeIndication` element. More than one
+`CommitmentTypeIndication` element makes no sense because we have only
+one data object which is signed (this is the incoming message body to
+the XML signer endpoint).
+* A `CommitmentTypeIndication` element contains always the
+`AllSignedDataObjects` element. The `ObjectReference` element within
+`CommitmentTypeIndication` element is not supported.
+* The `AllDataObjectsTimeStamp` element is not supported
+* The `IndividualDataObjectsTimeStamp` element is not supported
+
+[[XMLSecuritycomponent-SeeAlso]]
+See Also
+^^^^^^^^
+
+* http://www.w3.org/TR/xmldsig-bestpractices/[Best Practices]
http://git-wip-us.apache.org/repos/asf/camel/blob/dffb0d61/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 18f8465..36e57b4 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -106,6 +106,7 @@
* [SJMS](sjms.adoc)
* [SJMS Batch](sjms-batch.adoc)
* [Twitter](twitter.adoc)
+ * [XML Security](xmlsecurity.adoc)
* [Yammer](yammer.adoc)
* [ZooKeeper](zookeeper.adoc)
[4/5] camel git commit: Use shorthand Karaf commands
Posted by da...@apache.org.
Use shorthand Karaf commands
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/45efeb7e
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/45efeb7e
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/45efeb7e
Branch: refs/heads/master
Commit: 45efeb7eb4635528a2ceb11ab2514d46c585954f
Parents: 9802034
Author: Antonin Stefanutti <an...@stefanutti.fr>
Authored: Mon Feb 8 19:32:21 2016 +0100
Committer: Claus Ibsen <da...@apache.org>
Committed: Tue Feb 9 08:38:58 2016 +0100
----------------------------------------------------------------------
examples/camel-example-cdi-osgi/README.md | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/45efeb7e/examples/camel-example-cdi-osgi/README.md
----------------------------------------------------------------------
diff --git a/examples/camel-example-cdi-osgi/README.md b/examples/camel-example-cdi-osgi/README.md
index b5fe812..4d7c8ae 100644
--- a/examples/camel-example-cdi-osgi/README.md
+++ b/examples/camel-example-cdi-osgi/README.md
@@ -56,15 +56,15 @@ This example can be executed within Karaf 2.x, 3.x and 4.x. From the command lin
2. For Karaf 2.x, install the following pre-requisites:
```sh
- karaf@root()> features:addUrl mvn:org.apache.camel.karaf/apache-camel/${version}/xml/features
- karaf@root()> features:addUrl mvn:org.apache.activemq/activemq-karaf/5.12.1/xml/features
+ karaf@root()> chooseurl camel 2.17.0
+ karaf@root()> chooseurl activemq 5.12.1
karaf@root()> features:install activemq-broker-noweb pax-cdi-weld camel-sjms camel-cdi
```
3. Then install and start the example:
```sh
- karaf@root()> osgi:install -s mvn:org.apache.camel/camel-example-cdi-osgi/${version}
+ karaf@root()> install -s mvn:org.apache.camel/camel-example-cdi-osgi/2.17.0
```
Alternatively, with the new commands introduced since Karaf 3.x:
@@ -72,15 +72,15 @@ Alternatively, with the new commands introduced since Karaf 3.x:
2. Install the pre-requisites:
```sh
- karaf@root()> feature:repo-add mvn:org.apache.camel.karaf/apache-camel/${version}/xml/features
- karaf@root()> feature:repo-add mvn:org.apache.activemq/activemq-karaf/5.12.1/xml/features
+ karaf@root()> repo-add camel 2.17.0
+ karaf@root()> repo-add activemq 5.12.1
karaf@root()> feature:install activemq-broker-noweb pax-cdi-weld camel-sjms camel-cdi
```
3. Then install and start the example:
```sh
- karaf@root()> bundle:install -s mvn:org.apache.camel/camel-example-cdi-osgi/${version}
+ karaf@root()> install -s mvn:org.apache.camel/camel-example-cdi-osgi/2.17.0
```
By tailing the log with:
@@ -165,7 +165,7 @@ context, e.g.:
Finally, you can stop the example with:
```sh
-karaf@root()> bundle:uninstall camel-example-cdi-osgi
+karaf@root()> uninstall camel-example-cdi-osgi
```
And check in the log that the Camel context has been gracefully
[5/5] camel git commit: Add Weld version info in Camel CDI OSGi
example
Posted by da...@apache.org.
Add Weld version info in Camel CDI OSGi example
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/942496c6
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/942496c6
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/942496c6
Branch: refs/heads/master
Commit: 942496c66fc1df5f08fde1bf1a04dbe016a47b4e
Parents: 45efeb7
Author: Antonin Stefanutti <an...@stefanutti.fr>
Authored: Mon Feb 8 19:55:12 2016 +0100
Committer: Claus Ibsen <da...@apache.org>
Committed: Tue Feb 9 08:38:59 2016 +0100
----------------------------------------------------------------------
examples/camel-example-cdi-osgi/README.md | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/942496c6/examples/camel-example-cdi-osgi/README.md
----------------------------------------------------------------------
diff --git a/examples/camel-example-cdi-osgi/README.md b/examples/camel-example-cdi-osgi/README.md
index 4d7c8ae..3d8d740 100644
--- a/examples/camel-example-cdi-osgi/README.md
+++ b/examples/camel-example-cdi-osgi/README.md
@@ -45,7 +45,12 @@ The Camel application can be stopped pressing <kbd>ctrl</kbd>+<kbd>c</kbd> in th
#### OSGi / Karaf
-This example can be executed within Karaf 2.x, 3.x and 4.x. From the command line:
+This example can be executed within Karaf 2.x, 3.x and 4.x. Note that it uses
+the `pax-cdi-weld` feature from the PAX CDI version used by Camel and which defines
+the Weld version used. For instance, Camel `2.17.0` depends on PAX CDI `1.0.0.RC1`
+whose `pax-cdi-weld` feature relies on Weld version `2.2.11.Final`.
+
+To run the example, from the command line:
1. In the Karaf install root directory, start Karaf:
[3/5] camel git commit: Karaf user guide Asciidoc documentation
Posted by da...@apache.org.
Karaf user guide Asciidoc documentation
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/ae50d660
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/ae50d660
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/ae50d660
Branch: refs/heads/master
Commit: ae50d6602e79b7cfc73f552c7c55c7e2e22e41c7
Parents: dffb0d6
Author: Antonin Stefanutti <an...@stefanutti.fr>
Authored: Mon Feb 8 18:36:55 2016 +0100
Committer: Claus Ibsen <da...@apache.org>
Committed: Tue Feb 9 08:38:58 2016 +0100
----------------------------------------------------------------------
docs/user-manual/en/SUMMARY.md | 3 +
docs/user-manual/en/karaf.adoc | 528 ++++++++++++++++++++++++++++++++++++
2 files changed, 531 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/ae50d660/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 36e57b4..3d25860 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -118,3 +118,6 @@
* Data Formats
* [XML JSON](xmljson.adoc)
+
+* User Guide
+ * [Karaf](karaf.adoc)
http://git-wip-us.apache.org/repos/asf/camel/blob/ae50d660/docs/user-manual/en/karaf.adoc
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/karaf.adoc b/docs/user-manual/en/karaf.adoc
new file mode 100644
index 0000000..6b03f55
--- /dev/null
+++ b/docs/user-manual/en/karaf.adoc
@@ -0,0 +1,528 @@
+:experimental:
+
+[[Karaf-KarafSupport]]
+Karaf Support
+~~~~~~~~~~~~~
+
+Apache Camel is designed to work nicely into
+http://karaf.apache.org[Apache Karaf] OSGi container.
+
+It includes:
+
+* Camel features descriptor allowing to easily and quickly install Camel
+in Karaf.
+* Karaf commands allowing you to view, start, stop, get info, about the
+Camel contexts and routes running in the Karaf instance. +
+
+NOTE: Karaf commands are available starting with Camel 2.8.0, and the
+commands was renamed in Camel 2.9.0.
+
+Here are the versions that are compatible:
+
+[width="100%",cols="1m,1m",options="header",]
+|============================
+|Camel Version |Karaf Version
+|2.2.0 |1.2.0
+|2.3.0 |1.3.0
+|2.4.0 |1.4.0
+|2.5.0 |2.1.0
+|2.7.0 |2.2.0
+|2.7.2 |2.2.2
+|2.8.2 |2.2.4
+|2.9.0 |2.2.5
+|2.10.0 |2.2.8
+|2.11.0 |2.3.1
+|2.12.0 |2.3.2
+|2.13.0 |2.3.3
+|2.14.0 |2.3.7
+|2.15.0 |2.4.0
+|============================
+
+[[Karaf-PreparingKarafforCamel]]
+Preparing Karaf for Camel
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Camel uses several bundles to provide low level package, such as
+`javax.annotation` or `javax.xml.bind`.
+
+Due to that, we mustn't use the default system package coming from the
+JDK. It means that we need to _exclude_ some packages from system
+packages in order to use packages provided by tiers bundles.
+
+Camel provides a ready to use `config.properties` file that you can
+download:
+
+http://svn.apache.org/repos/asf/camel/tags/camel-2.7.2/platforms/karaf/features/src/main/resources/config.properties
+
+This file has to be copied into Karaf etc folder.
+
+TIP: *Karaf 2.2.5 or newer* +
+Notice that Karaf 2.2.5 now provides an extra configuration file that
+has been configured to work with Camel and CXF, so its recommended to
+use this file if you use Karaf 2.2.5 or newer. You can prepare Karaf by
+copying the `etc/jre.properties.cxf` and override the existing
+`etc/jre.properties` file.
+
+
+[[Karaf-InstallCamelinKaraf]]
+Install Camel in Karaf
+~~~~~~~~~~~~~~~~~~~~~~
+
+Assuming that you have a running Karaf instance, you can register the
+Camel features descriptor:
+
+[source,sh]
+----
+karaf@root> features:addurl mvn:org.apache.camel.karaf/apache-camel/2.8.2/xml/features
+----
+
+From Karaf 2.2.6 onwards this has been simplified as there is a new
+`features:chooseurl` command that is pre-setup for Camel:
+
+[source,sh]
+----
+karaf@root> features:chooseurl camel 2.9.1
+----
+
+Now, we have all Camel features available:
+
+[source,sh]
+----
+karaf@root> features:list|grep -i camel
+[uninstalled] [2.8.0 ] camel repo-0
+[uninstalled] [2.8.0 ] camel-core repo-0
+[uninstalled] [2.8.0 ] camel-spring repo-0
+[uninstalled] [2.8.0 ] camel-blueprint repo-0
+[uninstalled] [2.8.0 ] camel-test repo-0
+[uninstalled] [2.8.0 ] camel-cxf repo-0
+[uninstalled] [2.8.0 ] camel-cache repo-0
+[uninstalled] [2.8.0 ] camel-castor repo-0
+[uninstalled] [2.8.0 ] camel-crypto repo-0
+[uninstalled] [2.8.0 ] camel-http repo-0
+[uninstalled] [2.8.0 ] camel-http4 repo-0
+[uninstalled] [2.8.0 ] camel-mina repo-0
+[uninstalled] [2.8.0 ] camel-jetty repo-0
+[uninstalled] [2.8.0 ] camel-servlet repo-0
+[uninstalled] [2.8.0 ] camel-jms repo-0
+...
+----
+
+To install Camel, just install the `camel` feature:
+
+[source,sh]
+----
+karaf@root> features:install camel
+----
+
+You have to install the Camel features depending of your requirements.
+
+For instance, if you want to use blueprint as Camel DSL, you have to
+install the `camel-blueprint` feature:
+
+[source,sh]
+----
+karaf@root> features:install camel-blueprint
+----
+
+If, in your route, you use an endpoint like `stream:out`, you have to
+install the `camel-stream` feature:
+
+[source,sh]
+----
+karaf@root> features:install camel-stream
+----
+
+[[Karaf-Karafcommands]]
+Karaf commands
+~~~~~~~~~~~~~~
+
+When you install the camel feature, new Karaf commands become available
+automatically.
+
+[[Karaf-KarafcommandsinCamel2.8.x]]
+Karaf commands in Camel 2.8.x
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[width="100%",cols="1s,4",options="header",]
+|=======================================================================
+|Command |Description
+|camel:list-contexts |Lists the camel contexts available in the
+current Karaf instance
+
+|camel:list-routes |Displays the list of Camel routes available in the
+current Karaf instance
+
+|camel:info-context |Displays detail information about a given Camel
+context
+
+|camel:start-context |Starts the given Camel context
+
+|camel:stop-context |Stops the given Camel context
+
+|camel:info-route |Provides detail information about a Camel route
+
+|camel:show-route |Renders the route in XML
+
+|camel:start-route |Starts the given route
+
+|camel:stop-route |Stops the given route
+|=======================================================================
+
+[[Karaf-KarafcommandsinCamel2.9onwards]]
+Karaf commands in Camel 2.9 onwards
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[width="100%",cols="1s,4",options="header",]
+|=======================================================================
+|Command |Description
+|camel:context-list |Lists the camel contexts available in the current
+Karaf instance
+
+|camel:context-info |Displays detail information about a given Camel
+context
+
+|camel:context-start |Starts the given Camel context
+
+|camel:context-stop |Stops the given Camel context (it becomes
+unavailable and it can't be started afterwards)
+
+|camel:route-list |Displays the list of Camel routes available in the
+current Karaf instance
+
+|camel:route-info |Provides detail information about a Camel route
+
+|camel:route-show |Renders the route in XML
+
+|camel:route-start |Starts the given route. From Camel *2.10* onwards
+you can use `*` as wildcard to match multiple routes.
+
+|camel:route-stop |Stops the given route. From Camel *2.10* onwards
+you can use `*` as wildcard to match multiple routes.
+
+|camel:route-suspend |Suspends the given route. From Camel *2.10*
+onwards you can use `*` as wildcard to match multiple routes.
+
+|camel:route-resume |Resumes the given route. From Camel *2.10*
+onwards you can use `*` as wildcard to match multiple routes.
+|=======================================================================
+
+[[Karaf-KarafcommandsinCamel2.10onwards]]
+Karaf commands in Camel 2.10 onwards
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[width="100%",cols="1s,4",options="header",]
+|=======================================================================
+|Command |Description
+|camel:endpoint-list |Lists endpoints from all camel contexts
+available in the current Karaf instance
+|=======================================================================
+
+[[Karaf-KarafcommandsinCamel2.11onwards]]
+Karaf commands in Camel 2.11 onwards
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[width="100%",cols="1s,4",options="header",]
+|=======================================================================
+|Command |Description
+|camel:route-profile |To profile route(s)
+
+|camel:route-reset-stats |To reset performance stats on the given
+route(s)
+|=======================================================================
+
+[[Karaf-KarafcommandsinCamel2.12.4onwards]]
+Karaf commands in Camel 2.12.4 onwards
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[width="100%",cols="1s,4",options="header",]
+|=========================================================
+|Command |Description
+|camel:context-suspend |Suspends the given Camel context
+|camel:context-resume |Resumes the given Camel context
+|=========================================================
+
+[[Karaf-camel:context-list]]
+`camel:context-list`
+^^^^^^^^^^^^^^^^^^^^
+
+The `camel:context-list` command displays the list of Camel contexts
+available in the current Karaf instance:
+
+[source,sh]
+----
+karaf@root> camel:context-list
+Name Status Uptime
+[66-camel-3 ] [Started ] [14.559 seconds ]
+----
+
+It displays the context name/ID (used in others commands), the current
+status (started/stopped), the uptime (since when the context has been
+started).
+
+[[Karaf-camel:route-list]]
+`camel:route-list`
+^^^^^^^^^^^^^^^^^^
+
+The `camel:route-list` command displays the list of Camel routes
+available in the current Karaf instance:
+
+[source,sh]
+----
+karaf@root> camel:route-list
+[route1 ]
+----
+
+You can also filter the routes by Camel context:
+
+[source,sh]
+----
+karaf@root> camel:route-list 66-camel-3
+[route1 ]
+----
+
+TIP: use the kbd:[TAB] key to completion on the Camel context ID.
+
+[[Karaf-camel:info-context]]
+`camel:info-context`
+^^^^^^^^^^^^^^^^^^^^
+
+The `camel:context-info` command displays detail information about a
+given Camel context:
+
+add the `--verbose` option (following the context name) to also list
+the endpoints:
+
+[source]
+----
+karaf@root> camel:context-info 66-camel-3
+Camel Context 66-camel-3
+ Name: 66-camel-3
+ Version: 2.8.0
+ Status: Started
+ Uptime: 1 minute
+
+Advanced
+ Auto Startup: true
+ Starting Routes: false
+ Suspended: false
+ Tracing: false
+
+Properties
+
+Components
+ timer
+ properties
+ log
+
+Endpoints
+ timer://test
+ log://test
+
+Routes
+ route1
+
+Used Languages
+----
+
+You can see the current Camel version used by the Camel context, some
+context attributes, the components involved in the context, and the
+endpoints defined.
+
+TIP: use kbd:[TAB] key for completion on the Camel context name.
+
+[[Karaf-camel:context-start]]
+`camel:context-start`
+^^^^^^^^^^^^^^^^^^^^^
+
+The `camel:context-start` command starts a given Camel context:
+
+[source,sh]
+----
+karaf@root> camel:context-start 66-camel-3
+----
+
+TIP: use kbd:[TAB] key for completion on the Camel context name.
+
+[[Karaf-camel:context-stop]]
+`camel:context-stop`
+^^^^^^^^^^^^^^^^^^^^
+
+The `camel:context-stop` command stops a given Camel context. After
+stopping the context it becomes unavailable and cannot be started again.
+
+[source,sh]
+----
+karaf@root> karaf@root> camel:context-stop 66-camel-3
+----
+
+TIP: use kbd:[TAB] key for completion on the Camel context name.
+
+[[Karaf-camel:route-info]]
+`camel:route-info`
+^^^^^^^^^^^^^^^^^^
+
+The `camel:route-info` command provides detail information about a
+Camel route:
+
+[source]
+----
+karaf@root> camel:route-info route1
+Camel Route route1
+ Camel Context: 66-camel-3
+
+Properties
+ id = route1
+ parent = 2e7aacc1
+
+Statistics
+ Exchanges Total: 98
+ Exchanges Completed: 98
+ Exchanges Failed: 0
+ Min Processing Time: 1ms
+ Max Processing Time: 2ms
+ Mean Processing Time: 1ms
+ Total Processing Time: 134ms
+ Last Processing Time: 1ms
+ First Exchange Date: 2011-06-29 07:21:57
+ Last Exchange Completed Date: 2011-06-29 07:23:34
+
+Definition
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<route id="route1" xmlns="http://camel.apache.org/schema/spring">
+ <from uri="timer:test"/>
+ <to uri="log:test" id="to1"/>
+</route>
+----
+
+You can see some statistics (the number of processed exchanges, the
+processing time, etc) and a XML rendering of your route (whatever DSL
+used to define the route).
+
+TIP: use kbd:[TAB] key for completion on the route name.
+
+[[Karaf-camel:route-show]]
+`camel:route-show`
+^^^^^^^^^^^^^^^^^^
+
+The `camel:route-show` command renders the route in XML. It's
+independent from the DSL used to define the route:
+
+[source]
+----
+karaf@root> camel:route-show route1
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<route id="route1" xmlns="http://camel.apache.org/schema/spring">
+ <from uri="timer:test"/>
+ <to uri="log:test" id="to1"/>
+</route>
+----
+
+TIP: use kbd:[TAB] key for completion on the route name.
+
+[[Karaf-camel:route-start]]
+`camel:route-start`
+^^^^^^^^^^^^^^^^^^^
+
+The `camel:route-start` command starts a Camel route:
+
+[source,sh]
+----
+karaf@root> camel:route-start route1
+----
+
+TIP: use kbd:[TAB] key for completion on the route name.
+
+[[Karaf-camel:route-stop]]
+`camel:route-stop`
+^^^^^^^^^^^^^^^^^^
+
+The `camel:route-stop` command stops a Camel route:
+
+[source,sh]
+----
+karaf@root> camel:route-stop route1
+----
+
+[[Karaf-Camel2.9ornewer]]
+Camel 2.9 or newer
+++++++++++++++++++
+
+[[Karaf-camel:route-suspend]]
+`camel:route-suspend`
+^^^^^^^^^^^^^^^^^^^^^
+
+The `camel:route-suspend` command suspends a Camel route:
+
+[source,sh]
+----
+karaf@root> camel:route-suspend route1
+----
+
+TIP: use kbd:[TAB] key for completion on the route name.
+
+[[Karaf-camel:route-resume]]
+`camel:route-resume`
+^^^^^^^^^^^^^^^^^^^^
+
+The `camel:route-resume` command resume a Camel route:
+
+[source,sh]
+----
+karaf@root> camel:route-resume route1
+----
+
+TIP: use kbd:[TAB] key for completion on the route name.
+
+[[Karaf-Camel2.10ornewer]]
+Camel 2.10 or newer
++++++++++++++++++++
+
+[[Karaf-camel:endpoint-list]]
+`camel:endpoint-list`
+^^^^^^^^^^^^^^^^^^^^^
+
+The `camel:endpoint-list` command displays the list of the endpoints
+available in all camel contexts of the current Karaf instance:
+
+[source]
+----
+karaf@root> camel:endpoint-list
+camel-id uri Status
+[test ] [timer://test ] [Started ]
+[test ] [direct://A ] [Started ]
+----
+
+It displays the context name/ID (used in others commands), the URI of
+the endpoint and the current status (started/stopped).
+
+[[Karaf-Camel2.12.4ornewer]]
+Camel 2.12.4 or newer
+++++++++++++++++++++++
+
+[[Karaf-camel:context-suspend]]
+`camel:context-suspend`
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The `camel:context-suspend` command suspends a given Camel context.
+It then may be resumed again.
+
+[source,sh]
+----
+karaf@root> karaf@root> camel:context-suspend 66-camel-3
+----
+
+TIP: use kbd:[TAB] key for completion on the Camel context name.
+
+[[Karaf-camel:context-resume]]
+`camel:context-resume`
+^^^^^^^^^^^^^^^^^^^^^^
+
+The `camel:context-resume` command resumes a given Camel context.
+After that it returns to the _started_ state.
+
+[source,sh]
+----
+karaf@root> karaf@root> camel:context-resume 66-camel-3
+----
+
+TIP: use kbd:[TAB] key for completion on the Camel context name.
[2/5] camel git commit: Longer getting started Asciidoc documentation
Posted by da...@apache.org.
Longer getting started Asciidoc documentation
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/98020340
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/98020340
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/98020340
Branch: refs/heads/master
Commit: 98020340ad25a40ccd33bff296e332b76d0466d1
Parents: ae50d6602
Author: Antonin Stefanutti <an...@stefanutti.fr>
Authored: Mon Feb 8 19:12:59 2016 +0100
Committer: Claus Ibsen <da...@apache.org>
Committed: Tue Feb 9 08:38:58 2016 +0100
----------------------------------------------------------------------
docs/user-manual/en/SUMMARY.md | 1 +
docs/user-manual/en/book-getting-started.adoc | 575 +++++++++++++++++++++
2 files changed, 576 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/98020340/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 3d25860..ceadc22 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -3,6 +3,7 @@
* [Introduction](README.md)
* [Legal Notice](notice.md)
* [Getting Started](getting-started.adoc)
+* [Longer Getting Started Guide](book-getting-started.adoc)
* [Architecture](architecture.adoc)
* [Endpoint](endpoint.adoc)
http://git-wip-us.apache.org/repos/asf/camel/blob/98020340/docs/user-manual/en/book-getting-started.adoc
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/book-getting-started.adoc b/docs/user-manual/en/book-getting-started.adoc
new file mode 100644
index 0000000..b6926f2
--- /dev/null
+++ b/docs/user-manual/en/book-getting-started.adoc
@@ -0,0 +1,575 @@
+[[chapter-getting-started]]
+[[BookGettingStarted-GettingStartedwithApacheCamel]]
+Getting Started with Apache Camel
+---------------------------------
+
+[[BookGettingStarted-eip-book]]
+
+[[BookGettingStarted-TheEnterpriseIntegrationPatternsEIPBook]]
+The _Enterprise Integration Patterns_ (EIP) book
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The purpose of a _patterns_ book is not to advocate new techniques that
+the authors have invented, but rather to document existing best
+practices within a particular field. By doing this, the authors of a
+patterns book hope to spread knowledge of best practices and promote a
+vocabulary for discussing architectural designs. +
+One of the most famous patterns books is
+http://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612[_Design
+Patterns: Elements of Reusable Object-oriented Software_] by Erich
+Gamma, Richard Helm, Ralph Johnson and John Vlissides, commonly known as
+the http://en.wikipedia.org/wiki/Design_Patterns["Gang of Four" (GoF)]
+book. Since the publication of __Design Patterns__, many other pattern
+books, of varying quality, have been written. One famous patterns book
+is called
+http://www.amazon.com/Enterprise-Integration-Patterns-Designing-Deploying/dp/0321200683[_Enterprise
+Integration Patterns: Designing, Building, and Deploying Messaging
+Solutions_] by Gregor Hohpe and Bobby Woolf. It is common for people to
+refer to this book by its initials __EIP__. As the subtitle of EIP
+suggests, the book focuses on design patterns for asynchronous messaging
+systems. The book discusses 65 patterns. Each pattern is given a textual
+name and most are also given a graphical symbol, intended to be used in
+architectural diagrams.
+
+[[BookGettingStarted-TheCamelproject]]
+The Camel project
+~~~~~~~~~~~~~~~~~
+
+Camel (http://camel.apache.org) is an open-source, Java-based project
+that helps the user implement many of the design patterns in the EIP
+book. Because Camel implements many of the design patterns in the EIP
+book, it would be a good idea for people who work with Camel to have the
+EIP book as a reference.
+
+[[BookGettingStarted-OnlinedocumentationforCamel]]
+Online documentation for Camel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The documentation is all under the Documentation category on the
+right-side menu of the Camel website (also available in
+http://camel.apache.org/manual.html[PDF form]).
+link:books.html[Camel-related books] are also available, in particular
+the http://manning.com/ibsen[Camel in Action] book, presently serving as
+the Camel bible -- it has a
+http://www.manning.com/ibsen/chapter1sample.pdf[free Chapter One (pdf)],
+which is highly recommended to read to get more familiar with Camel.
+
+[[BookGettingStarted-Ausefultipfornavigatingtheonlinedocumentation]]
+A useful tip for navigating the online documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The breadcrumbs at the top of the online Camel documentation can help
+you navigate between parent and child subsections. +
+For example, If you are on the "Languages" documentation page then the
+left-hand side of the reddish bar contains the following links.
+
+[source,brush:,java;,gutter:,false;,theme:,Default]
+----
+Apache Camel > Documentation > Architecture > Languages
+----
+
+As you might expect, clicking on "Apache Camel" takes you back to the
+home page of the Apache Camel project, and clicking on "Documentation"
+takes you to the main documentation page. You can interpret the
+"Architecture" and "Languages" buttons as indicating you are in the
+"Languages" section of the "Architecture" chapter. Adding browser
+bookmarks to pages that you frequently reference can also save time.
+
+[[BookGettingStarted-online-javadoc-docs]]
+
+[[BookGettingStarted-OnlineJavadocdocumentation]]
+Online Javadoc documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Apache Camel website provides
+http://camel.apache.org/maven/current/camel-core/apidocs/index.html[Javadoc
+documentation]. It is important to note that the Javadoc documentation
+is spread over several _independent_ Javadoc hierarchies rather than
+being all contained in a single Javadoc hierarchy. In particular, there
+is one Javadoc hierarchy for the _core_ APIs of Camel, and a separate
+Javadoc hierarchy for each component technology supported by Camel. For
+example, if you will be using Camel with ActiveMQ and FTP then you need
+to look at the Javadoc hierarchies for the
+http://camel.apache.org/maven/current/camel-core/apidocs/index.html[core
+API] and
+http://camel.apache.org/maven/current/camel-spring/apidocs/index.html[Spring
+API].
+
+[[BookGettingStarted-ConceptsandterminologyfundamentaltoCamel]]
+Concepts and terminology fundamental to Camel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this section some of the concepts and terminology that are
+fundamental to Camel are explained. This section is not meant as a
+complete Camel tutorial, but as a first step in that direction.
+
+[[BookGettingStarted-endpoint]]
+
+[[BookGettingStarted-Endpoint]]
+Endpoint
+^^^^^^^^
+
+The term _endpoint_ is often used when talking about inter-process
+communication. For example, in client-server communication, the client
+is one endpoint and the server is the other endpoint. Depending on the
+context, an endpoint might refer to an _address_, such as a `host:port`
+pair for TCP-based communication, or it might refer to a _software
+entity_ that is contactable at that address. For example, if somebody
+uses `www.example.com:80` as an example of an endpoint, they might be
+referring to the actual port at that host name (that is, an address), or
+they might be referring to the web server (that is, software contactable
+at that address). Often, the distinction between the address and
+software contactable at that address is not an important one.
+
+Some middleware technologies make it possible for several software
+entities to be contactable at the same physical address. For example,
+CORBA is an object-oriented, remote-procedure-call (RPC) middleware
+standard. If a CORBA server process contains several objects then a
+client can communicate with any of these objects at the same _physical_
+address (host:port), but a client communicates with a particular object
+via that object's _logical_ address (called an _IOR_ in CORBA
+terminology), which consists of the physical address (`host:port`) plus an
+id that uniquely identifies the object within its server process. (An
+IOR contains some additional information that is not relevant to this
+present discussion.) When talking about CORBA, some people may use the
+term "endpoint" to refer to a CORBA server's _physical address_, while
+other people may use the term to refer to the _logical address_ of a
+single CORBA object, and other people still might use the term to refer
+to any of the following:
+
+* The physical address (`host:port`) of the CORBA server process
+* The logical address (`host:port` plus `id`) of a CORBA object
+* The CORBA server process (a relatively heavyweight software entity)
+* A CORBA object (a lightweight software entity)
+
+Because of this, you can see that the term _endpoint_ is ambiguous in at
+least two ways. First, it is ambiguous because it might refer to an
+address or to a software entity contactable at that address. Second, it
+is ambiguous in the _granularity_ of what it refers to: a heavyweight
+versus lightweight software entity, or physical address versus logical
+address. It is useful to understand that different people use the term
+_endpoint_ in slightly different (and hence ambiguous) ways because
+Camel's usage of this term might be different to whatever meaning you
+had previously associated with the term.
+
+Camel provides out-of-the-box support for endpoints implemented with
+many different communication technologies. Here are some examples of the
+Camel-supported endpoint technologies.
+
+* A JMS queue.
+* A web service.
+* A file. A file may sound like an unlikely type of endpoint, until you
+realize that in some systems one application might write information to
+a file and, later, another application might read that file.
+* An FTP server.
+* An email address. A client can send a message to an email address, and
+a server can read an incoming message from a mail server.
+* A POJO (plain old Java object).
+
+In a Camel-based application, you create (Camel wrappers around) some
+endpoints and connect these endpoints with __routes__, which I will
+discuss later in link:book-getting-started.html[Section 4.8 ("Routes,
+RouteBuilders and Java DSL")]. Camel defines a Java interface called
+`Endpoint`. Each Camel-supported endpoint has a class that implements
+this `Endpoint` interface. As I discussed in
+link:book-getting-started.html[Section 3.3 ("Online Javadoc
+documentation")], Camel provides a separate Javadoc hierarchy for each
+communications technology supported by Camel. Because of this, you will
+find documentation on, say, the `JmsEndpoint` class in the
+http://camel.apache.org/maven/current/camel-jms/apidocs/[JMS Javadoc
+hierarchy], while documentation for, say, the `FtpEndpoint` class is in
+the http://camel.apache.org/maven/current/camel-ftp/apidocs/[FTP Javadoc
+hierarchy].
+
+[[BookGettingStarted-CamelContext]]
+CamelContext
+^^^^^^^^^^^^
+
+A `CamelContext` object represents the Camel runtime system. You
+typically have one `CamelContext` object in an application. A typical
+application executes the following steps:
+
+1. Create a `CamelContext` object.
+2. Add endpoints – and possibly components, which are discussed in
+link:book-getting-started.html[Section 4.5 ("Components")] – to the
+`CamelContext` object.
+3. Add routes to the `CamelContext` object to connect the endpoints.
+4. Invoke the `start()` operation on the `CamelContext` object. This
+starts Camel-internal threads that are used to process the sending,
+receiving and processing of messages in the endpoints.
+5. Eventually invoke the `stop()` operation on the `CamelContext`
+object. Doing this gracefully stops all the endpoints and Camel-internal
+threads.
+
+Note that the `CamelContext.start()` operation does not block
+indefinitely. Rather, it starts threads internal to each `Component` and
+`Endpoint` and then `start()` returns. Conversely, `CamelContext.stop()`
+waits for all the threads internal to each `Endpoint` and `Component` to
+terminate and then `stop()` returns.
+
+If you neglect to call `CamelContext.start()` in your application then
+messages will not be processed because internal threads will not have
+been created.
+
+If you neglect to call `CamelContext.stop()` before terminating your
+application then the application may terminate in an inconsistent state.
+If you neglect to call `CamelContext.stop()` in a JUnit test then the
+test may fail due to messages not having had a chance to be fully
+processed.
+
+[[BookGettingStarted-CamelTemplate]]
+CamelTemplate
+^^^^^^^^^^^^^
+
+Camel used to have a class called `CamelClient`, but this was renamed to
+be `CamelTemplate` to be similar to a naming convention used in some
+other open-source projects, such as the `TransactionTemplate` and
+`JmsTemplate` classes in http://www.springframework.org/[Spring].
+
+The `CamelTemplate` class is a thin wrapper around the `CamelContext`
+class. It has methods that send a `Message` or `Exchange` – both
+discussed in link:book-getting-started.html[Section 4.6 ("Message and
+Exchange")]) – to an `Endpoint` – discussed in
+link:book-getting-started.html[Section 4.1 ("Endpoint")]. This provides
+a way to enter messages into source endpoints, so that the messages will
+move along routes – discussed in link:book-getting-started.html[Section
+4.8 ("Routes, RouteBuilders and Java DSL")] – to destination endpoints.
+
+[[BookGettingStarted-url-uri-urn-iri]]
+
+[[BookGettingStarted-TheMeaningofURL,URI,URNandIRI]]
+The Meaning of URL, URI, URN and IRI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some Camel methods take a parameter that is a _URI_ string. Many people
+know that a URI is "something like a URL" but do not properly understand
+the relationship between URI and URL, or indeed its relationship with
+other acronyms such as IRI and URN.
+
+Most people are familiar with _URLs_ (uniform resource locators), such
+as `http://...`, `ftp://...`, `mailto:...`. Put simply, a URL specifies
+the _location_ of a resource.
+
+A _URI_ (uniform resource identifier) is a URL _or_ a URN. So, to fully
+understand what URI means, you need to first understand what is a URN. +
+_URN_ is an acronym for __uniform resource name__. There are may "unique
+identifier" schemes in the world, for example, ISBNs (globally unique
+for books), social security numbers (unique within a country), customer
+numbers (unique within a company's customers database) and telephone
+numbers. Each "unique identifier" scheme has its own notation. A URN is
+a wrapper for different "unique identifier" schemes. The syntax of a URN
+is `urn:<scheme-name>:<unique-identifier>`. A URN uniquely identifies a
+_resource_, such as a book, person or piece of equipment. By itself, a
+URN does not specify the _location_ of the resource. Instead, it is
+assumed that a _registry_ provides a mapping from a resource's URN to
+its location. The URN specification does not state what form a registry
+takes, but it might be a database, a server application, a wall chart or
+anything else that is convenient. Some hypothetical examples of URNs are
+`urn:employee:08765245`, `urn:customer:uk:3458:hul8` and
+`urn:foo:0000-0000-9E59-0000-5E-2`. The `<scheme-name>` (`employee`,
+`customer` and `foo` in these examples) part of a URN implicitly defines
+how to parse and interpret the `<unique-identifier>` that follows it. An
+arbitrary URN is meaningless unless: (1) you know the semantics implied
+by the `<scheme-name>`, and (2) you have access to the registry
+appropriate for the `<scheme-name>`. A registry does not have to be public
+or globally accessible. For example, `urn:employee:08765245` might be
+meaningful only within a specific company.
+
+To date, URNs are not (yet) as popular as URLs. For this reason, URI is
+widely misused as a synonym for URL.
+
+_IRI_ is an acronym for __internationalized resource identifier__. An
+IRI is simply an internationalized version of a URI. In particular, a
+URI can contain letters and digits in the US-ASCII character set, while
+a IRI can contain those same letters and digits, and _also_ European
+accented characters, Greek letters, Chinese ideograms and so on.
+
+[[BookGettingStarted-Components]]
+Components
+^^^^^^^^^^
+
+_Component_ is confusing terminology; _EndpointFactory_ would have been
+more appropriate because a `Component` is a factory for creating
+`Endpoint` instances. For example, if a Camel-based application uses
+several JMS queues then the application will create one instance of the
+`JmsComponent` class (which implements the `Component` interface), and
+then the application invokes the `createEndpoint()` operation on this
+`JmsComponent` object several times. Each invocation of
+`JmsComponent.createEndpoint()` creates an instance of the `JmsEndpoint`
+class (which implements the `Endpoint` interface). Actually,
+application-level code does not invoke `Component.createEndpoint()`
+directly. Instead, application-level code normally invokes
+`CamelContext.getEndpoint()`; internally, the `CamelContext` object
+finds the desired `Component` object (as I will discuss shortly) and
+then invokes `createEndpoint()` on it.
+
+Consider the following code:
+
+[source,java]
+----
+myCamelContext.getEndpoint("pop3://john.smith@mailserv.example.com?password=myPassword");
+----
+
+The parameter to `getEndpoint()` is a URI. The URI _prefix_ (that is,
+the part before `:`) specifies the name of a component. Internally, the
+`CamelContext` object maintains a mapping from names of components to
+`Component` objects. For the URI given in the above example, the
+`CamelContext` object would probably map the `pop3` prefix to an
+instance of the `MailComponent` class. Then the `CamelContext` object
+invokes
+`createEndpoint("pop3://john.smith@mailserv.example.com?password=myPassword")`
+on that `MailComponent` object. The `createEndpoint()` operation splits
+the URI into its component parts and uses these parts to create and
+configure an `Endpoint` object. +
+In the previous paragraph, I mentioned that a `CamelContext` object
+maintains a mapping from component names to `Component` objects. This
+raises the question of how this map is populated with named `Component`
+objects. There are two ways of populating the map. The first way is for
+application-level code to invoke
+`CamelContext.addComponent(String componentName, Component component)`.
+The example below shows a single `MailComponent` object being registered
+in the map under 3 different names.
+
+[source,java]
+----
+Component mailComponent = new org.apache.camel.component.mail.MailComponent();
+myCamelContext.addComponent("pop3", mailComponent);
+myCamelContext.addComponent("imap", mailComponent);
+myCamelContext.addComponent("smtp", mailComponent);
+----
+
+The second (and preferred) way to populate the map of named `Component`
+objects in the `CamelContext` object is to let the `CamelContext` object
+perform lazy initialization. This approach relies on developers
+following a convention when they write a class that implements the
+`Component` interface. I illustrate the convention by an example. Let's
+assume you write a class called `com.example.myproject.FooComponent` and
+you want Camel to automatically recognize this by the name `foo`. To do
+this, you have to write a properties file called
+`META-INF/services/org/apache/camel/component/foo` (without a
+`.properties` file extension) that has a single entry in it called
+`class`, the value of which is the fully-scoped name of your class. This
+is shown below:
+
+.META-INF/services/org/apache/camel/component/foo
+[source]
+----
+class=com.example.myproject.FooComponent
+----
+
+If you want Camel to also recognize the class by the name `bar` then you
+write another properties file in the same directory called `bar` that
+has the same contents. Once you have written the properties file(s), you
+create a JAR file that contains the `com.example.myproject.FooComponent`
+class and the properties file(s), and you add this jar file to your
+CLASSPATH. Then, when application-level code invokes
+`createEndpoint("foo:...")` on a `CamelContext` object, Camel will find
+the "foo"" properties file on the CLASSPATH, get the value of the
+`class` property from that properties file, and use reflection APIs to
+create an instance of the specified class.
+
+As I said in link:book-getting-started.html[Section 4.1 ("Endpoint")],
+Camel provides out-of-the-box support for numerous communication
+technologies. The out-of-the-box support consists of classes that
+implement the `Component` interface plus properties files that enable a
+`CamelContext` object to populate its map of named `Component`
+objects.
+
+Earlier in this section I gave the following example of calling
+`CamelContext.getEndpoint()`:
+
+[source,java]
+----
+myCamelContext.getEndpoint("pop3://john.smith@mailserv.example.com?password=myPassword");
+----
+
+When I originally gave that example, I said that the parameter to
+`getEndpoint()` was a URI. I said that because the online Camel
+documentation and the Camel source code both claim the parameter is a
+URI. In reality, the parameter is restricted to being a URL. This is
+because when Camel extracts the component name from the parameter, it
+looks for the first ":", which is a simplistic algorithm. To understand
+why, recall from link:book-getting-started.html[Section 4.4 ("The
+Meaning of URL, URI, URN and IRI")] that a URI can be a URL _or_ a URN.
+Now consider the following calls to `getEndpoint`:
+
+[source,java]
+----
+myCamelContext.getEndpoint("pop3:...");
+myCamelContext.getEndpoint("jms:...");
+myCamelContext.getEndpoint("urn:foo:...");
+myCamelContext.getEndpoint("urn:bar:...");
+----
+
+Camel identifies the components in the above example as `pop3`, `jms`,
+`urn` and `urn`. It would be more useful if the latter components were
+identified as `urn:foo` and `urn:bar` or, alternatively, as `foo` and
+`bar` (that is, by skipping over the `urn:` prefix). So, in practice you
+must identify an endpoint with a URL (a string of the form
+`<scheme>:...`) rather than with a URN (a string of the form
+`urn:<scheme>:...`). This lack of proper support for URNs means the you
+should consider the parameter to `getEndpoint()` as being a URL rather
+than (as claimed) a URI.
+
+[[BookGettingStarted-message-and-exchange]]
+
+[[BookGettingStarted-MessageandExchange]]
+Message and Exchange
+^^^^^^^^^^^^^^^^^^^^
+
+The `Message` interface provides an abstraction for a single message,
+such as a request, reply or exception message.
+
+There are concrete classes that implement the `Message` interface for
+each Camel-supported communications technology. For example, the
+`JmsMessage` class provides a JMS-specific implementation of the
+`Message` interface. The public API of the `Message` interface provides
+get- and set-style methods to access the _message id_, _body_ and
+individual _header_ fields of a message.
+
+The `Exchange` interface provides an abstraction for an exchange of
+messages, that is, a request message and its corresponding reply or
+exception message. In Camel terminology, the request, reply and
+exception messages are called _in_, _out_ and _fault_ messages.
+
+There are concrete classes that implement the `Exchange` interface for
+each Camel-supported communications technology. For example, the
+`JmsExchange` class provides a JMS-specific implementation of the
+`Exchange` interface. The public API of the `Exchange` interface is
+quite limited. This is intentional, and it is expected that each class
+that implements this interface will provide its own technology-specific
+operations.
+
+Application-level programmers rarely access the `Exchange` interface (or
+classes that implement it) directly. However, many classes in Camel are
+generic types that are instantiated on (a class that implements)
+`Exchange`. Because of this, the `Exchange` interface appears a lot in
+the generic signatures of classes and methods.
+
+[[BookGettingStarted-Processor]]
+Processor
+^^^^^^^^^
+
+The `Processor` interface represents a class that processes a message.
+The signature of this interface is shown below:
+
+.Processor
+[source,java]
+----
+package org.apache.camel;
+public interface Processor {
+ void process(Exchange exchange) throws Exception;
+}
+----
+
+Notice that the parameter to the `process()` method is an `Exchange`
+rather than a `Message`. This provides flexibility. For example, an
+implementation of this method initially might call `exchange.getIn()` to
+get the input message and process it. If an error occurs during
+processing then the method can call `exchange.setException()`.
+
+An application-level developer might implement the `Processor` interface
+with a class that executes some business logic. However, there are many
+classes in the Camel library that implement the `Processor` interface in
+a way that provides support for a design pattern in the
+link:book-getting-started.html[EIP book]. For example, `ChoiceProcessor`
+implements the message router pattern, that is, it uses a cascading
+if-then-else statement to route a message from an input queue to one of
+several output queues. Another example is the `FilterProcessor` class
+which discards messages that do not satisfy a stated _predicate_ (that
+is, condition).
+
+[[BookGettingStarted-routes]]
+
+[[BookGettingStarted-Routes,RouteBuildersandJavaDSL]]
+Routes, RouteBuilders and Java DSL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A _route_ is the step-by-step movement of a `Message` from an input
+queue, through arbitrary types of decision making (such as filters and
+routers) to a destination queue (if any). Camel provides two ways for an
+application developer to specify routes. One way is to specify route
+information in an XML file. A discussion of that approach is outside the
+scope of this document. The other way is through what Camel calls a Java
+_DSL_ (domain-specific language).
+
+[[BookGettingStarted-IntroductiontoJavaDSL]]
+Introduction to Java DSL
+++++++++++++++++++++++++
+
+For many people, the term "domain-specific language" implies a compiler
+or interpreter that can process an input file containing keywords and
+syntax specific to a particular domain. This is _not_ the approach taken
+by Camel. Camel documentation consistently uses the term "Java DSL"
+instead of "DSL", but this does not entirely avoid potential confusion.
+The Camel "Java DSL" is a class library that can be used in a way that
+looks almost like a DSL, except that it has a bit of Java syntactic
+baggage. You can see this in the example below. Comments afterwards
+explain some of the constructs used in the example.
+
+.*Example of Camel's "Java DSL"*
+[source,java]
+----
+RouteBuilder builder = new RouteBuilder() {
+ public void configure() {
+ from("queue:a").filter(header("foo").isEqualTo("bar")).to("queue:b");
+ from("queue:c").choice()
+ .when(header("foo").isEqualTo("bar")).to("queue:d")
+ .when(header("foo").isEqualTo("cheese")).to("queue:e")
+ .otherwise().to("queue:f");
+ }
+};
+CamelContext myCamelContext = new DefaultCamelContext();
+myCamelContext.addRoutes(builder);
+----
+
+The first line in the above example creates an object which is an
+instance of an anonymous subclass of `RouteBuilder` with the specified
+`configure()` method.
+
+The `CamelContext.addRoutes(RouterBuilder builder)` method invokes
+`builder.setContext(this)` – so the `RouteBuilder` object knows which
+`CamelContext` object it is associated with – and then invokes
+`builder.configure()`. The body of `configure()` invokes methods such as
+`from()`, `filter()`, `choice()`, `when()`, `isEqualTo()`, `otherwise()`
+and `to()`.
+
+The `RouteBuilder.from(String uri)` method invokes `getEndpoint(uri)` on
+the `CamelContext` associated with the `RouteBuilder` object to get the
+specified `Endpoint` and then puts a `FromBuilder` _wrapper_ around this
+`Endpoint`. The `FromBuilder.filter(Predicate predicate)` method creates
+a `FilterProcessor` object for the `Predicate` (that is, condition)
+object built from the `header("foo").isEqualTo("bar")` expression. In
+this way, these operations incrementally build up a `Route` object (with
+a `RouteBuilder` wrapper around it) and add it to the `CamelContext`
+object associated with the `RouteBuilder`.
+
+[[BookGettingStarted-CritiqueofJavaDSL]]
+Critique of Java DSL
+++++++++++++++++++++
+
+The online Camel documentation compares Java DSL favorably against the
+alternative of configuring routes and endpoints in a XML-based Spring
+configuration file. In particular, Java DSL is less verbose than its XML
+counterpart. In addition, many integrated development environments
+(IDEs) provide an auto-completion feature in their editors. This
+auto-completion feature works with Java DSL, thereby making it easier
+for developers to write Java DSL.
+
+However, there is another option that the Camel documentation neglects
+to consider: that of writing a parser that can process DSL stored in,
+say, an external file. Currently, Camel does not provide such a DSL
+parser, and I do not know if it is on the "to do" list of the Camel
+maintainers. I think that a DSL parser would offer a significant benefit
+over the current Java DSL. In particular, the DSL would have a syntactic
+definition that could be expressed in a relatively short BNF form. The
+effort required by a Camel user to learn how to use DSL by reading this
+BNF would almost certainly be significantly less than the effort
+currently required to study the API of the `RouterBuilder` classes.
+
+[[BookGettingStarted-ContinueLearningaboutCamel]]
+Continue Learning about Camel
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Return to the main link:getting-started.html[Getting Started] page for
+additional introductory reference information.