You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/05/24 08:49:19 UTC
[1/2] camel git commit: Added camel-servletlistener docs to Gitbook
Repository: camel
Updated Branches:
refs/heads/master 6f404e73c -> cc1b73c78
Added camel-servletlistener docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/b51dc747
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/b51dc747
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/b51dc747
Branch: refs/heads/master
Commit: b51dc747205e39965140003ae7483631e2892658
Parents: 6f404e7
Author: Andrea Cosentino <an...@gmail.com>
Authored: Tue May 24 10:30:22 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Tue May 24 10:30:22 2016 +0200
----------------------------------------------------------------------
.../src/main/docs/servletlistener.adoc | 355 +++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 356 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/b51dc747/components/camel-servletlistener/src/main/docs/servletlistener.adoc
----------------------------------------------------------------------
diff --git a/components/camel-servletlistener/src/main/docs/servletlistener.adoc b/components/camel-servletlistener/src/main/docs/servletlistener.adoc
new file mode 100644
index 0000000..79040c6
--- /dev/null
+++ b/components/camel-servletlistener/src/main/docs/servletlistener.adoc
@@ -0,0 +1,355 @@
+[[ServletListenerComponent-ServletListenerComponent]]
+ServletListener Component
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Available as of Camel 2.11*
+
+This component is used for bootstrapping Camel applications in web
+applications. For example beforehand people would have to find their own
+way of bootstrapping Camel, or rely on 3rd party frameworks such as
+Spring to do it.
+
+
+NOTE: *Sidebar*
+This component supports Servlet 2.x onwards, which mean it works also in
+older web containers; which is the goal of this component.
+Though Servlet 2.x requires to use a web.xml file as configuration.
+For Servlet 3.x containers you can use annotation driven configuration
+to boostrap Camel using the @WebListener, and implement your own class,
+where you boostrap Camel. Doing this still puts the challenge how to let
+end users easily configure Camel, which you get for free with the old
+school web.xml file.
+
+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-servletlistener</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel core version -->
+</dependency>
+------------------------------------------------------------
+
+[[ServletListenerComponent-Using]]
+Using
+^^^^^
+
+You would need to chose one of the following implementations of the
+abstract class
+`org.apache.camel.component.servletlistener.CamelServletContextListener`.
+
+* `JndiCamelServletContextListener` which uses the `JndiRegistry` to
+leverage JNDI for its registry.
+* `SimpleCamelServletContextListener` which uses the `SimpleRegistry` to
+leverage a `java.util.Map` as its registry.
+
+To use this you need to configure the
+`org.apache.camel.component.servletlistener.CamelServletContextListener`
+in the `WEB-INF/web.xml` file as shown below:
+
+[[ServletListenerComponent-Options]]
+Options
+^^^^^^^
+
+The
+`org.apache.camel.component.servletlistener.CamelServletContextListener`
+supports the following options which can be configured as context-param
+in the web.xml file.
+
+[width="100%",cols="10%,20%,70%",options="header",]
+|=======================================================================
+|Option |Type |Description
+
+|propertyPlaceholder.XXX | | To configure link:using-propertyplaceholder.html[property placeholders]
+in Camel. You should prefix the option with "propertyPlaceholder.", for
+example to configure the location, use propertyPlaceholder.location as
+name. You can configure all the options from the
+link:properties.html[Properties] component.
+
+|jmx.XXX | | To configure link:camel-jmx.html[JMX]. You should prefix the option with
+"jmx.", for example to disable JMX, use jmx.disabled as name. You can
+configure all the options from `org.apache.camel.spi.ManagementAgent`.
+As well the options mentioned on the link:camel-jmx.html[JMX] page.
+
+|name |`String` |To configure the name of the link:camelcontext.html[CamelContext].
+
+|messageHistory |`Boolean` |*Camel 2.12.2:* Whether to enable or disable
+link:message-history.html[Message History] (enabled by default).
+
+|streamCache |`Boolean` |Whether to enable link:stream-caching.html[Stream caching].
+
+|trace |`Boolean` |Whether to enable link:tracer.html[Tracer].
+
+|delayer |`Long` |To set a delay value for link:delay-interceptor.html[Delay Interceptor].
+
+|handleFault |`Boolean` |Whether to enable handle fault.
+
+|errorHandlerRef |`String` |Refers to a context scoped link:error-handler.html[Error Handler] to be
+used.
+
+|autoStartup |`Boolean` |Whether to start all routes when starting Camel.
+
+|useMDCLogging |`Boolean` |Whether to use link:mdc-logging.html[MDC logging].
+
+|useBreadcrumb |`Boolean` |Whether to use link:mdc-logging.html[breadcrumb].
+
+|managementNamePattern |`String` |To set a custom naming pattern for JMX MBeans.
+
+|threadNamePattern |`String` |To set a custom naming pattern for threads.
+
+|properties.XXX | | To set custom properties on `CamelContext.getProperties`. This is seldom
+in use.
+
+|routebuilder.XXX | | To configure routes to be used. See below for more details.
+
+|CamelContextLifecycle | | Refers to a FQN classname of an implementation of
+`org.apache.camel.component.servletlistener.CamelContextLifecycle`.
+Which allows to execute custom code before and after
+link:camelcontext.html[CamelContext] has been started or stopped. See
+below for further details.
+
+|XXX | | To set any option on link:camelcontext.html[CamelContext].
+|=======================================================================
+
+[[ServletListenerComponent-Examples]]
+Examples
+^^^^^^^^
+
+See link:servlet-tomcat-no-spring-example.html[Servlet Tomcat No Spring
+Example].
+
+[[ServletListenerComponent-AccessingthecreatedCamelContext]]
+Accessing the created CamelContext
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Available as of Camel 2.14/2.13.3/2.12.5*
+
+The created�`CamelContext` is stored on the�`ServletContext` as an
+attribute with the key "CamelContext". You can get hold of the
+CamelContext if you can get hold of the�`ServletContext` as shown below:
+
+[source,java]
+--------------------------------------------------------------------
+ServletContext sc = ...
+CamelContext camel = (CamelContext) sc.getAttribute("CamelContext");
+--------------------------------------------------------------------
+
+�
+
+[[ServletListenerComponent-Configuringroutes]]
+Configuring routes
+^^^^^^^^^^^^^^^^^^
+
+You need to configure which routes to use in the web.xml file. You can
+do this in a number of ways, though all the parameters must be prefixed
+with "routeBuilder".
+
+[[ServletListenerComponent-UsingaRouteBuilderclass]]
+Using a RouteBuilder class
+++++++++++++++++++++++++++
+
+By default Camel will assume the param-value is a FQN classname for a
+Camel link:routebuilder.html[RouteBuilder] class, as shown below:
+
+[source,xml]
+---------------------------------------------------------------------------------
+ <context-param>
+ <param-name>routeBuilder-MyRoute</param-name>
+ <param-value>org.apache.camel.component.servletlistener.MyRoute</param-value>
+ </context-param>
+---------------------------------------------------------------------------------
+
+You can specify multiple classes in the same param-value as shown below:
+
+[source,xml]
+-----------------------------------------------------------------------
+ <context-param>
+ <param-name>routeBuilder-routes</param-name>
+ <!-- we can define multiple values separated by comma -->
+ <param-value>
+ org.apache.camel.component.servletlistener.MyRoute,
+ org.apache.camel.component.servletlistener.routes.BarRouteBuilder
+ </param-value>
+ </context-param>
+-----------------------------------------------------------------------
+
+The name of the parameter does not have a meaning at runtime. It just
+need to be unique and start with "routeBuilder". In the example above we
+have "routeBuilder-routes". But you could just as well have named it
+"routeBuilder.foo".
+
+[[ServletListenerComponent-Usingpackagescanning]]
+Using package scanning
+++++++++++++++++++++++
+
+You can also tell Camel to use package scanning, which mean it will look
+in the given package for all classes of
+link:routebuilder.html[RouteBuilder] types and automatic adding them as
+Camel routes. To do that you need to prefix the value with
+"packagescan:" as shown below:
+
+[source,xml]
+--------------------------------------------------------------------------------------------
+ <context-param>
+ <param-name>routeBuilder-MyRoute</param-name>
+ <!-- define the routes using package scanning by prefixing with packagescan: -->
+ <param-value>packagescan:org.apache.camel.component.servletlistener.routes</param-value>
+ </context-param>
+--------------------------------------------------------------------------------------------
+
+[[ServletListenerComponent-UsingaXMLfile]]
+Using a XML file
+++++++++++++++++
+
+You can also define Camel routes using XML DSL, though as we are not
+using Spring or Blueprint the XML file can only contain Camel route(s).
+
+In the web.xml you refer to the XML file which can be from "classpath",
+"file" or a "http" url, as shown below:
+
+[source,xml]
+------------------------------------------------------------
+ <context-param>
+ <param-name>routeBuilder-MyRoute</param-name>
+ <param-value>classpath:routes/myRoutes.xml</param-value>
+ </context-param>
+------------------------------------------------------------
+
+And the XML file is:
+
+*routes/myRoutes.xml*
+
+[source,xml]
+--------------------------------------------------------------------
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- the xmlns="http://camel.apache.org/schema/spring" is needed -->
+<routes xmlns="http://camel.apache.org/schema/spring">
+
+ <route id="foo">
+ <from uri="direct:foo"/>
+ <to uri="mock:foo"/>
+ </route>
+
+ <route id="bar">
+ <from uri="direct:bar"/>
+ <to uri="mock:bar"/>
+ </route>
+
+</routes>
+--------------------------------------------------------------------
+
+Notice that in the XML file the root tag is <routes> which must use the
+namespace "http://camel.apache.org/schema/spring". This namespace is
+having the spring in the name, but that is because of historical
+reasons, as Spring was the first and only XML DSL back in the time. At
+runtime no Spring JARs is needed. Maybe in Camel 3.0 the namespace can
+be renamed to a generic name.
+
+[[ServletListenerComponent-Configuringpropertplaceholders]]
+Configuring propert placeholders
+++++++++++++++++++++++++++++++++
+
+Here is a snippet of a web.xml configuration for setting up property
+placeholders to load `myproperties.properties` from the classpath
+
+[source,xml]
+------------------------------------------------------------------------------------------------------------------------------------
+ <!-- setup property placeholder to load properties from classpath -->
+ <!-- we do this by setting the param-name with propertyPlaceholder. as prefix and then any options such as location, cache etc -->
+ <context-param>
+ <param-name>propertyPlaceholder.location</param-name>
+ <param-value>classpath:myproperties.properties</param-value>
+ </context-param>
+ <!-- for example to disable cache on properties component, you do -->
+ <context-param>
+ <param-name>propertyPlaceholder.cache</param-name>
+ <param-value>false</param-value>
+ </context-param>
+------------------------------------------------------------------------------------------------------------------------------------
+
+[[ServletListenerComponent-ConfiguringJMX]]
+Configuring JMX
++++++++++++++++
+
+Here is a snippet of a web.xml configuration for configuring JMX, such
+as disabling JMX.
+
+[source,xml]
+------------------------------------------------------------------
+ <!-- configure JMX by using names that is prefixed with jmx. -->
+ <!-- in this example we disable JMX -->
+ <context-param>
+ <param-name>jmx.disabled</param-name>
+ <param-value>true</param-value>
+ </context-param>
+------------------------------------------------------------------
+
+[[ServletListenerComponent-JNDIorSimpleasCamel]]
+JNDI or Simple as Camel link:registry.html[Registry]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This component uses either JNDI or Simple as the
+link:registry.html[Registry]. +
+ This allows you to lookup link:bean.html[Bean]s and other services in
+JNDI, and as well to bind and unbind your own link:bean.html[Bean]s.
+
+This is done from Java code by implementing the
+`org.apache.camel.component.servletlistener.CamelContextLifecycle`.
+
+[[ServletListenerComponent-UsingcustomCamelContextLifecycle]]
+Using custom CamelContextLifecycle
+++++++++++++++++++++++++++++++++++
+
+In the code below we use the callbacks `beforeStart` and `afterStop` to
+enlist our custom bean in the Simple link:registry.html[Registry], and
+as well to cleanup when we stop.
+
+Then we need to register this class in the web.xml file as shown below,
+using the parameter name "CamelContextLifecycle". The value must be a
+FQN which refers to the class implementing the
+`org.apache.camel.component.servletlistener.CamelContextLifecycle`
+interface.
+
+[source,xml]
+-------------------------------------------------------------------------------------
+ <context-param>
+ <param-name>CamelContextLifecycle</param-name>
+ <param-value>org.apache.camel.component.servletlistener.MyLifecycle</param-value>
+ </context-param>
+-------------------------------------------------------------------------------------
+
+As we enlisted our HelloBean link:bean.html[Bean] using the name
+"myBean" we can refer to this link:bean.html[Bean] in the Camel routes
+as shown below:
+
+[source,java]
+-----------------------------------------------
+public class MyBeanRoute extends RouteBuilder {
+ @Override
+ public void configure() throws Exception {
+ from("seda:foo").routeId("foo")
+ .to("bean:myBean")
+ .to("mock:foo");
+ }
+}
+-----------------------------------------------
+
+*Important:* If you use
+`org.apache.camel.component.servletlistener.JndiCamelServletContextListener`
+then the `CamelContextLifecycle` must use the `JndiRegistry` as well.
+And likewise if the servlet is
+`org.apache.camel.component.servletlistener.SimpleCamelServletContextListener`
+then the `CamelContextLifecycle` must use the `SimpleRegistry`
+
+[[ServletListenerComponent-SeeAlso]]
+See Also
+^^^^^^^^
+
+* link:servlet.html[SERVLET]
+* link:servlet-tomcat-example.html[Servlet Tomcat Example]
+* link:servlet-tomcat-no-spring-example.html[Servlet Tomcat No Spring
+Example]
+
http://git-wip-us.apache.org/repos/asf/camel/blob/b51dc747/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index d8a638c..d9cf18c 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -233,6 +233,7 @@
* [Script](script.adoc)
* [Servicenow](servicenow.adoc)
* [Servlet](servlet.adoc)
+ * [Servlet Listener](servletlistener.adoc)
* [SJMS](sjms.adoc)
* [SJMS Batch](sjms-batch.adoc)
* [Telegram](telegram.adoc)
[2/2] camel git commit: Added camel-shiro docs to Gitbook
Posted by ac...@apache.org.
Added camel-shiro docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/cc1b73c7
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/cc1b73c7
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/cc1b73c7
Branch: refs/heads/master
Commit: cc1b73c784807582c37f85310ae608c29dbc3d8c
Parents: b51dc74
Author: Andrea Cosentino <an...@gmail.com>
Authored: Tue May 24 10:48:24 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Tue May 24 10:48:24 2016 +0200
----------------------------------------------------------------------
.../src/main/docs/shiro-security.adoc | 316 +++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 317 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/cc1b73c7/components/camel-shiro/src/main/docs/shiro-security.adoc
----------------------------------------------------------------------
diff --git a/components/camel-shiro/src/main/docs/shiro-security.adoc b/components/camel-shiro/src/main/docs/shiro-security.adoc
new file mode 100644
index 0000000..a0c0b86
--- /dev/null
+++ b/components/camel-shiro/src/main/docs/shiro-security.adoc
@@ -0,0 +1,316 @@
+[[ShiroSecurity-ShiroSecurityComponent]]
+Shiro Security Component
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Available as of Camel 2.5*
+
+The *shiro-security* component in Camel is a security focused component,
+based on the Apache Shiro security project.
+
+Apache Shiro is a powerful and flexible open-source security framework
+that cleanly handles authentication, authorization, enterprise session
+management and cryptography. The objective of the Apache Shiro project
+is to provide the most robust and comprehensive application security
+framework available while also being very easy to understand and
+extremely simple to use.
+
+This camel shiro-security component allows authentication and
+authorization support to be applied to different segments of a camel
+route.
+
+Shiro security is applied on a route using a Camel Policy. A Policy in
+Camel utilizes a strategy pattern for applying interceptors on Camel
+Processors. It offering the ability to apply cross-cutting concerns (for
+example. security, transactions etc) on sections/segments of a camel
+route.
+
+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-shiro</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel core version -->
+</dependency>
+------------------------------------------------------------
+
+[[ShiroSecurity-ShiroSecurityBasics]]
+Shiro Security Basics
+^^^^^^^^^^^^^^^^^^^^^
+
+To employ Shiro security on a camel route, a ShiroSecurityPolicy object
+must be instantiated with security configuration details (including
+users, passwords, roles etc). This object must then be applied to a
+camel route. This ShiroSecurityPolicy Object may also be registered in
+the Camel registry (JNDI or ApplicationContextRegistry) and then
+utilized on other routes in the Camel Context.
+
+Configuration details are provided to the ShiroSecurityPolicy using an
+Ini file (properties file) or an Ini object. The Ini file is a standard
+Shiro configuration file containing user/role details as shown below
+
+[source,java]
+------------------------------------------------------------------
+[users]
+# user 'ringo' with password 'starr' and the 'sec-level1' role
+ringo = starr, sec-level1
+george = harrison, sec-level2
+john = lennon, sec-level3
+paul = mccartney, sec-level3
+
+[roles]
+# 'sec-level3' role has all permissions, indicated by the
+# wildcard '*'
+sec-level3 = *
+
+# The 'sec-level2' role can do anything with access of permission
+# readonly (*) to help
+sec-level2 = zone1:*
+
+# The 'sec-level1' role can do anything with access of permission
+# readonly
+sec-level1 = zone1:readonly:*
+------------------------------------------------------------------
+
+[[ShiroSecurity-InstantiatingaShiroSecurityPolicyObject]]
+Instantiating a ShiroSecurityPolicy Object
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ShiroSecurityPolicy object is instantiated as follows
+
+[source,java]
+----------------------------------------------------------------------------------------
+ private final String iniResourcePath = "classpath:shiro.ini";
+ private final byte[] passPhrase = {
+ (byte) 0x08, (byte) 0x09, (byte) 0x0A, (byte) 0x0B,
+ (byte) 0x0C, (byte) 0x0D, (byte) 0x0E, (byte) 0x0F,
+ (byte) 0x10, (byte) 0x11, (byte) 0x12, (byte) 0x13,
+ (byte) 0x14, (byte) 0x15, (byte) 0x16, (byte) 0x17};
+ List<permission> permissionsList = new ArrayList<permission>();
+ Permission permission = new WildcardPermission("zone1:readwrite:*");
+ permissionsList.add(permission);
+
+ final ShiroSecurityPolicy securityPolicy =
+ new ShiroSecurityPolicy(iniResourcePath, passPhrase, true, permissionsList);
+----------------------------------------------------------------------------------------
+
+[[ShiroSecurity-ShiroSecurityPolicyOptions]]
+ShiroSecurityPolicy Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[width="100%",cols="10%,10%,10%,90%",options="header",]
+|=======================================================================
+|Name |Default Value |Type |Description
+
+|`iniResourcePath or ini` |`none` |Resource String or Ini Object |A mandatory Resource String for the iniResourcePath or an instance of an
+Ini object must be passed to the security policy. Resources can be
+acquired from the file system, classpath, or URLs when prefixed with
+"file:, classpath:, or url:" respectively. For e.g "classpath:shiro.ini"
+
+|`passPhrase` |`An AES 128 based key` |byte[] |A passPhrase to decrypt ShiroSecurityToken(s) sent along with Message
+Exchanges
+
+|`alwaysReauthenticate` |`true` |boolean |Setting to ensure re-authentication on every individual request. If set
+to false, the user is authenticated and locked such than only requests
+from the same user going forward are authenticated.
+
+|`permissionsList` |`none` |List<Permission> |A List of permissions required in order for an authenticated user to be
+authorized to perform further action i.e continue further on the route.
+If no Permissions list or Roles List (see below) is provided to the
+ShiroSecurityPolicy object, then authorization is deemed as not
+required. Note that the default is that authorization is granted if any
+of the Permission Objects in the list are applicable.
+
+|`rolesList` |`none` |List<String> |*Camel 2.13:* A List of roles required in order for an authenticated
+user to be authorized to perform further action i.e continue further on
+the route. If no roles list or permissions list (see above) is provided
+to the ShiroSecurityPolicy object, then authorization is deemed as not
+required. Note that the default is that authorization is granted if any
+of the roles in the list are applicable.
+
+|`cipherService` |`AES` |org.apache.shiro.crypto.CipherService |Shiro ships with AES & Blowfish based CipherServices. You may use one
+these or pass in your own Cipher implementation
+
+|`base64` |`false` |`boolean` |*Camel 2.12:* To use base64 encoding for the security token header,
+which allows transferring the header over link:jms.html[JMS] etc. This
+option must also be set on `ShiroSecurityTokenInjector` as well.
+
+|`allPermissionsRequired` |`false` |`boolean` |*Camel 2.13:* The default is that authorization is granted if any of the
+Permission Objects in the permissionsList parameter are applicable. Set
+this to true to require all of the Permissions to be met.
+
+|`allRolesRequired` |`false` |`boolean` |*Camel 2.13:* The default is that authorization is granted if any of the
+roles in the rolesList parameter are applicable. Set this to true to
+require all of the roles to be met.
+|=======================================================================
+
+[[ShiroSecurity-ApplyingShiroAuthenticationonaCamelRoute]]
+Applying Shiro Authentication on a Camel Route
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ShiroSecurityPolicy, tests and permits incoming message exchanges
+containing a encrypted SecurityToken in the Message Header to proceed
+further following proper authentication. The SecurityToken object
+contains a Username/Password details that are used to determine where
+the user is a valid user.
+
+[source,java]
+-----------------------------------------------------------------------
+ protected RouteBuilder createRouteBuilder() throws Exception {
+ final ShiroSecurityPolicy securityPolicy =
+ new ShiroSecurityPolicy("classpath:shiro.ini", passPhrase);
+
+ return new RouteBuilder() {
+ public void configure() {
+ onException(UnknownAccountException.class).
+ to("mock:authenticationException");
+ onException(IncorrectCredentialsException.class).
+ to("mock:authenticationException");
+ onException(LockedAccountException.class).
+ to("mock:authenticationException");
+ onException(AuthenticationException.class).
+ to("mock:authenticationException");
+
+ from("direct:secureEndpoint").
+ to("log:incoming payload").
+ policy(securityPolicy).
+ to("mock:success");
+ }
+ };
+ }
+-----------------------------------------------------------------------
+
+[[ShiroSecurity-ApplyingShiroAuthorizationonaCamelRoute]]
+Applying Shiro Authorization on a Camel Route
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Authorization can be applied on a camel route by associating a
+Permissions List with the ShiroSecurityPolicy. The Permissions List
+specifies the permissions necessary for the user to proceed with the
+execution of the route segment. If the user does not have the proper
+permission set, the request is not authorized to continue any further.
+
+[source,java]
+-------------------------------------------------------------------------------------------
+ protected RouteBuilder createRouteBuilder() throws Exception {
+ final ShiroSecurityPolicy securityPolicy =
+ new ShiroSecurityPolicy("./src/test/resources/securityconfig.ini", passPhrase);
+
+ return new RouteBuilder() {
+ public void configure() {
+ onException(UnknownAccountException.class).
+ to("mock:authenticationException");
+ onException(IncorrectCredentialsException.class).
+ to("mock:authenticationException");
+ onException(LockedAccountException.class).
+ to("mock:authenticationException");
+ onException(AuthenticationException.class).
+ to("mock:authenticationException");
+
+ from("direct:secureEndpoint").
+ to("log:incoming payload").
+ policy(securityPolicy).
+ to("mock:success");
+ }
+ };
+ }
+-------------------------------------------------------------------------------------------
+
+[[ShiroSecurity-CreatingaShiroSecurityTokenandinjectingitintoaMessageExchange]]
+Creating a ShiroSecurityToken and injecting it into a Message Exchange
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ShiroSecurityToken object may be created and injected into a Message
+Exchange using a Shiro Processor called ShiroSecurityTokenInjector. An
+example of injecting a ShiroSecurityToken using a
+ShiroSecurityTokenInjector in the client is shown below
+
+[source,java]
+-------------------------------------------------------------------------------------
+ ShiroSecurityToken shiroSecurityToken = new ShiroSecurityToken("ringo", "starr");
+ ShiroSecurityTokenInjector shiroSecurityTokenInjector =
+ new ShiroSecurityTokenInjector(shiroSecurityToken, passPhrase);
+
+ from("direct:client").
+ process(shiroSecurityTokenInjector).
+ to("direct:secureEndpoint");
+-------------------------------------------------------------------------------------
+
+[[ShiroSecurity-SendingMessagestoroutessecuredbyaShiroSecurityPolicy]]
+Sending Messages to routes secured by a ShiroSecurityPolicy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Messages and Message Exchanges sent along the camel route where the
+security policy is applied need to be accompanied by a SecurityToken in
+the Exchange Header. The SecurityToken is an encrypted object that holds
+a Username and Password. The SecurityToken is encrypted using AES 128
+bit security by default and can be changed to any cipher of your choice.
+
+Given below is an example of how a request may be sent using a
+ProducerTemplate in Camel along with a SecurityToken
+
+[source,java]
+-------------------------------------------------------------------------------------------------
+
+ @Test
+ public void testSuccessfulShiroAuthenticationWithNoAuthorization() throws Exception {
+ //Incorrect password
+ ShiroSecurityToken shiroSecurityToken = new ShiroSecurityToken("ringo", "stirr");
+
+ // TestShiroSecurityTokenInjector extends ShiroSecurityTokenInjector
+ TestShiroSecurityTokenInjector shiroSecurityTokenInjector =
+ new TestShiroSecurityTokenInjector(shiroSecurityToken, passPhrase);
+
+ successEndpoint.expectedMessageCount(1);
+ failureEndpoint.expectedMessageCount(0);
+
+ template.send("direct:secureEndpoint", shiroSecurityTokenInjector);
+
+ successEndpoint.assertIsSatisfied();
+ failureEndpoint.assertIsSatisfied();
+ }
+-------------------------------------------------------------------------------------------------
+
+[[ShiroSecurity-SendingMessagestoroutessecuredbyaShiroSecurityPolicymucheasierfromCamel2.12onwards]]
+Sending Messages to routes secured by a ShiroSecurityPolicy (much easier from Camel 2.12 onwards)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+From *Camel 2.12* onwards its even easier as you can provide the subject
+in two different ways.
+
+[[ShiroSecurity-UsingShiroSecurityToken]]
+Using ShiroSecurityToken
+++++++++++++++++++++++++
+
+You can send a message to a Camel route with a header of key
+`ShiroSecurityConstants.SHIRO_SECURITY_TOKEN` of the type
+`org.apache.camel.component.shiro.security.ShiroSecurityToken` that
+contains the username and password. For example:
+
+[source,java]
+---------------------------------------------------------------------------------------------------------------------------------------------
+ ShiroSecurityToken shiroSecurityToken = new ShiroSecurityToken("ringo", "starr");
+
+ template.sendBodyAndHeader("direct:secureEndpoint", "Beatle Mania", ShiroSecurityConstants.SHIRO_SECURITY_TOKEN, shiroSecurityToken);
+---------------------------------------------------------------------------------------------------------------------------------------------
+
+You can also provide the username and password in two different headers
+as shown below:
+
+[source,java]
+--------------------------------------------------------------------------------------
+ Map<String, Object> headers = new HashMap<String, Object>();
+ headers.put(ShiroSecurityConstants.SHIRO_SECURITY_USERNAME, "ringo");
+ headers.put(ShiroSecurityConstants.SHIRO_SECURITY_PASSWORD, "starr");
+ template.sendBodyAndHeaders("direct:secureEndpoint", "Beatle Mania", headers);
+--------------------------------------------------------------------------------------
+
+When you use the username and password headers, then the
+ShiroSecurityPolicy in the Camel route will automatic transform those
+into a single header with key
+ShiroSecurityConstants.SHIRO_SECURITY_TOKEN with the token. Then token
+is either a `ShiroSecurityToken` instance, or a base64 representation as
+a String (the latter is when you have set base64=true).
http://git-wip-us.apache.org/repos/asf/camel/blob/cc1b73c7/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index d9cf18c..d1f0fdd 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -234,6 +234,7 @@
* [Servicenow](servicenow.adoc)
* [Servlet](servlet.adoc)
* [Servlet Listener](servletlistener.adoc)
+ * [Shiro](shiro-security.adoc)
* [SJMS](sjms.adoc)
* [SJMS Batch](sjms-batch.adoc)
* [Telegram](telegram.adoc)