You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by rs...@apache.org on 2015/05/12 20:42:24 UTC
[1/2] deltaspike git commit: DELTASPIKE-898 Make documentation
structure more comprehensible
Repository: deltaspike
Updated Branches:
refs/heads/master 1c828f3fd -> e67d64a24
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/jsf.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/jsf.adoc b/documentation/src/main/asciidoc/jsf.adoc
index 865877b..88a830c 100644
--- a/documentation/src/main/asciidoc/jsf.adoc
+++ b/documentation/src/main/asciidoc/jsf.adoc
@@ -8,7 +8,7 @@
== Overview
The JSF module provides CDI integration with JSF, with type-safe view config, multi-window handling, new scopes (WindowScoped, ViewScope, ViewAccessScoped, GroupedConversationScoped) and integration with DeltaSpike “core” messages and exception handling.
-== Configure Your Projects
+== Project Setup
The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
=== Declare JSF Module Dependencies
@@ -43,15 +43,13 @@ Some EE6 servers cannot handle optional classes. From DeltaSpike 1.0.1, if you d
</dependency>
----
-== Use the Module Features
-
.Support of EAR deployments
IMPORTANT: Before using features described by this page, please ensure that you are
aware of
https://issues.apache.org/jira/browse/DELTASPIKE-335[DELTASPIKE-335] and
the corresponding impact.
-=== JSF Messages
+== JSF Messages
DeltaSpike provides an injectable component for typesafe FacesMessages.
@@ -85,11 +83,11 @@ In case of a String we use it for both the summary and detail information on the
If a Message is returned, we lookup the 'detail' and 'summary' categories (see `org.apache.deltaspike.core.api.message.Message#toString(String)` for creating the FacesMessage.
-=== Multi-Window Handling
+== Multi-Window Handling
-==== Background
+=== Background
-===== Historic Considerations
+==== Historic Considerations
Until the end of the 1990s web browsers are usually single threaded and
only had one window. But in the last years browsers supporting multiple
@@ -99,7 +97,7 @@ server side. Sadly browser windows still lack of a native windowId, thus
maintaining web application data in @SessionScoped backing beans is
still used in most of the cases.
-===== How JSF-2 Changed the World
+==== How JSF-2 Changed the World
The MyFaces Orchestra community did a good summary about the various
ways to handle multiple window support in JSF Applications. Those
@@ -110,7 +108,7 @@ requests. Due to the new JSF-2 ability to use bookmarkable URLs and deep
links, a typical JSF-2 application contains much more GET links than we
used to see in JSF-1, thus we have far more href links to cope with.
-===== Standard windowId Handling
+==== Standard windowId Handling
With a classical approach we would not be able to simply add a windowId
parameter to such links because if the user would open the link in a new
@@ -127,9 +125,9 @@ destroy their information) while rendering the page, which means this is
not feasible as general solution.
-==== Available Modes
+=== Available Modes
-===== CLIENTWINDOW
+==== CLIENTWINDOW
Each GET request results in an intermediate small html page which checks
if the browser tab fits the requested windowId. When the windowId is
@@ -139,12 +137,12 @@ dsRid/windowId will be added. On the server side, the verified windowId
will be extracted from the cookie. For POST request detection, the
windowId will be added as hidden input to all forms.
-====== Advantage
+===== Advantage
* Covers all edge cases
-====== Disadvantage
+===== Disadvantage
* Having the windowhandler.html site rendered between requests sometimes
leads to some 'flickering' if the destination page takes some time to
@@ -161,7 +159,7 @@ parse a request and decide upon the UserAgent or any other information
if a client will get an intermediate page or if he gets the result page
directly.
-====== Change windowhandler.html
+===== Change windowhandler.html
To customize the look and feel of the windowhandler.html, you can simply
provide a own via:
@@ -179,7 +177,7 @@ public class MyClientWindowConfig extends DefaultClientWindowConfig
}
-------------------------------------------------------------------
-===== LAZY
+==== LAZY
Always appends the windowId to all, from JSF generated, URLs. On the
first GET request without a windowId, it will generate a new windowId
@@ -191,11 +189,11 @@ it is not matching, the view will be refreshed with the right windowId in
the URL.
-====== Advantage
+===== Advantage
* No windowhandler.html / loading screen required
-====== Disadvantage
+===== Disadvantage
* It could happen that 2 tabs will share the same windowId for 1 request
because the `LAZY` mode will check lazily, after rendering the view, if
@@ -203,7 +201,7 @@ the windowId matches the `window.name`. Therefore it could happen that
@ViewAccessScoped or other scopes will unintentionally be destroyed.
-====== Workflow Example
+===== Workflow Example
First GET request with windowId
@@ -234,7 +232,7 @@ Further GET request without windowId
from `window.name`
-===== NONE
+==== NONE
Any window or browser tab detection will be disabled for the current
request. Scopes like @WindowScoped, @GroupedConversationScoped or
@@ -243,22 +241,22 @@ current request does not support Javascript or if the user agent is a
bot/crawler.
-===== DELEGATED
+==== DELEGATED
Delegates the complete window handling to the new JSF 2.2 ClientWindow
(if not disabled).
-===== CUSTOM
+==== CUSTOM
Enables to use an complete own
`org.apache.deltaspike.jsf.spi.scope.window.ClientWindow`
implementation.
-==== Configuration
+=== Configuration
-===== ds:windowId
+==== ds:windowId
The component `ds:windowId`
(`xmlns:ds="http://deltaspike.apache.org/jsf"`) is required to enable
@@ -268,7 +266,7 @@ mode. The best way, to apply it for all views, is to add this component
to all of your templates.
-===== ds:disableClientWindow
+==== ds:disableClientWindow
Similiar to JSF 2.2' `disableClientWindow` attribute,
`ds:disableClientWindow` provides the ability to disable the rendering
@@ -282,7 +280,7 @@ of the windowId to all links of all child components:
<h:link value="Link with windowId" outcome="target.xhtml"/>
-------------------------------------------------------------------
-===== Number of Active Windows
+==== Number of Active Windows
By default, DeltaSpike allows `1024` active windows per session. Anyway, this number is reduced inside this JSF module to `64` for JSF applications. Once that the limit number of active windows is reached, DeltaSpike will drop the oldest active window.
@@ -304,7 +302,7 @@ public class MyClientWindowConfig extends DefaultClientWindowConfig
}
-----------------------------------------------------------------------------------
-===== Switch Mode
+==== Switch Mode
To switch the mode, just provide a
`org.apache.deltaspike.jsf.api.config.JsfModuleConfig` and overwrite
@@ -324,7 +322,7 @@ public class MyJsfModuleConfig extends JsfModuleConfig
---------------------------------------------------------------------------
-===== Provide a Custom ClientWindow
+==== Provide a Custom ClientWindow
If you would like to provide an custom
`org.apache.deltaspike.jsf.spi.scope.window.ClientWindow`
@@ -355,16 +353,16 @@ public class MyJsfModuleConfig extends JsfModuleConfig
}
---------------------------------------------------------------------------
-==== Based Scopes
+=== Based Scopes
* @WindowScoped
* @ViewAccessScoped
* @GroupedConversationScoped
-=== Scopes
+== Scopes
-==== @WindowScoped
+=== @WindowScoped
The window-scope is like a session per window. That means that the data
is bound to a window/tab and it not shared between windows (like the
@@ -382,7 +380,7 @@ public class PreferencesBean implements Serializable
----------------------------------------------------
-==== @ViewAccessScoped
+=== @ViewAccessScoped
In case of conversations you have to un-scope beans manually (or they
will be terminated automatically after a timeout). However, sometimes
@@ -411,17 +409,17 @@ separation without touching the old windowId. Otherwise a 'open in new
tab' on a page with a @ViewAccessScoped bean might cause the termination
(and re-initialization) of that bean.
-==== @GroupedConversationScoped (From DeltaSpike 0.6)
+=== @GroupedConversationScoped
See (Grouped-)Conversations
-==== @ViewScoped
+=== @ViewScoped
DeltaSpike provides an CDI context for the JSF 2.0/2.1
@javax.faces.bean.ViewScoped. You can simply annotate your bean with
@javax.faces.bean.ViewScoped and @Named.
-==== JSF 2.0 Scopes
+=== JSF 2.0 Scopes
JSF 2.0 introduced new annotations as well as a new scope - the View
Scope. CODI allows to use all the CDI mechanisms in beans annotated
@@ -439,7 +437,7 @@ All these annotations are mapped automatically. So you will not face
issues, if you import a JSF 2 annotation instead of the corresponding
CDI annotation.
-=== Integration with DeltaSpike Type-safe Messages
+== Integration with DeltaSpike Type-safe Messages
You can use <<core.adoc#_messages_i18n,DeltaSpike type-safe messages>>
with JSF to provide i18n messages and test to an JSF appplicaton.
@@ -505,9 +503,9 @@ javax.faces.component.UIInput.REQUIRED = {0}: Please enter a value
</faces-config>
--------------------------------------------------------------------------------------------
-=== Type-safe View-Configs
+== Type-safe View-Configs
-==== Intro
+=== Intro
Type-safe view-configs are static configs which can be used in
combination with every view-technology which is based on Java. Currently
@@ -529,7 +527,7 @@ Even the concepts provided by modules (of DeltaSpike itself) are based
on the basic API provided by the Core. So it is possible to introduce
custom concepts the same way DeltaSpike itself does.
-==== Motivation
+=== Motivation
Instead of learning the concepts and rules of view-configs provided by
DeltaSpike, it might be easier for simple demos to just type some
@@ -559,13 +557,13 @@ Advantages which are planned for later (= currently not supported):
If you are still not convinced, you just have to try it. You will see how your daily workflow benefits from it pretty soon.
-==== Bean-discovery-mode Annotated
+=== Bean-discovery-mode Annotated
CDI 1.1 introduced a concept called bean-discovery-mode. If you would
like to use the mode `annotated`, please have a look at the tip at
@ViewConfigRoot
-==== Basic API Usages
+=== Basic API Usages
While reading this section keep the following simple rules in mind:
Meta-data gets inherited along the path of Java inheritance
@@ -693,7 +691,7 @@ public Class<? extends Pages.Admin> toNextPage()
}
------------------------------------------------
-===== File (@View) and Folder (@Folder) Paths
+==== File (@View) and Folder (@Folder) Paths
`@View` as well as `@Folder` are optional annotations. `@Folder` is only
needed for using a different folder-name or for marking folder configs
@@ -746,7 +744,7 @@ To customize it you can use `@Folder#name`, `@View#basePath`,
`@View#name` and `@View#extension` (or you register custom
`NameBuilder`s inline or globally).
-====== @Folder#name
+===== @Folder#name
The rules are pretty simple. You will get what you write. There are only
two additional features:
@@ -781,7 +779,7 @@ leads to the following paths:
* /w1/step1.xhtml
* /pages/w2/step1.xhtml
-====== @View
+===== @View
The same naming rules apply to `@View#basePath`. However, it is only
valid to be used at view-config nodes which represent pages (-> classes
@@ -853,7 +851,7 @@ interface Pages extends ViewConfig
It leads to the same paths, but in addition `@View#navigation` gets
inherited along the inheritance path.
-===== Navigation Parameters
+==== Navigation Parameters
Since the view-config is static, an approach to add parameters is
needed. The following part shows different possibilities to add
@@ -865,7 +863,7 @@ that way. Some get added automatically based on special meta-data (e.g.
using `@View(navigation = REDIRECT)`. The same goes for
`"includeViewParams=true"` and `@View(viewParams = INCLUDE)`.
-===== Static Configuration via @NavigationParameter
+==== Static Configuration via @NavigationParameter
In some cases, it is needed to add an information in any case. So you can
annotate the view-config class with `@NavigationParameter`. Supported
@@ -911,7 +909,7 @@ public class PageBean
}
-----------------------------------------------------------------------
-====== Dynamic Configuration via NavigationParameterContext
+===== Dynamic Configuration via NavigationParameterContext
Instead of using parameters in a static fashion (as shown above), it is
also possible to add them dynamically (e.g. in case of special
@@ -941,7 +939,7 @@ public class PageBean
}
--------------------------------------------------------------------------------------
-===== Security Integration via @Secured
+==== Security Integration via @Secured
This annotation is a custom view-meta-data provided by the
Security-module which allows to integrate third-party frameworks (or
@@ -1022,7 +1020,7 @@ public interface Pages extends ViewConfig
-------------------------------------------------
-===== View-Controller Callbacks via @ViewControllerRef
+==== View-Controller Callbacks via @ViewControllerRef
This annotation is a custom view-meta-data provided by the JSF-module
which allows to configure beans which should act as view-controllers.
@@ -1073,7 +1071,7 @@ public class ErrorViewAwareExceptionHandler {
}
--------------------------------------------------------------------------------------------------------------
-===== Referencing Views via @ViewRef
+==== Referencing Views via @ViewRef
With `@ViewControllerRef#value` you can annotate a view-config class to
bind (/reference) a controller to it. `@ViewRef#config` allows the same
@@ -1106,7 +1104,7 @@ The above example leads to the invocation of the pre-render-view logic before
/pages/page1.xhtml gets rendered (and it will not be called for other
pages).
-===== Using the (Optional) ViewNavigationHandler
+==== Using the (Optional) ViewNavigationHandler
With JSF you typically navigate with the action-method bound to a
command-component. However, also JSF supports manual navigation via
@@ -1140,7 +1138,7 @@ Also in this case (optional) meta-data will be used for the navigation
process, since `ViewNavigationHandler` just delegates to the active
navigation-handler (of JSF).
-===== Configuring a Default Error-View
+==== Configuring a Default Error-View
It is possible to mark one view-config class as default error-view. That
means in case of errors it will be used as navigation target
@@ -1202,7 +1200,7 @@ However, in case of JSF you have to ensure that you are at a valid point
in the JSF request-lifecycle for a navigation, because invocation gets
transformed to a standard (implicit) JSF navigation.
-===== Using ViewConfigResolver
+==== Using ViewConfigResolver
If you would like to query view-meta-data yourself (for whatever
reason), you can do that with `ViewConfigResolver`.
@@ -1257,9 +1255,9 @@ pages (which have to implement the `ViewConfig` interface).
page, it is possible to get the implicitly as well as explicitly
configured (view-)meta-data and get and/or execute configured callbacks.
-==== Advanced API Usages
+=== Advanced API Usages
-===== Creating Custom Meta-Data via @ViewMetaData
+==== Creating Custom Meta-Data via @ViewMetaData
This meta-annotation allows to create custom view-meta-data which can be
used for view-configs. By default meta-data of a lower level overrides
@@ -1287,7 +1285,7 @@ ViewConfigDescriptor viewConfigDescriptor = viewConfigResolver.getViewConfigDesc
List<InfoPage> metaDataList = viewConfigDescriptor.getMetaData(InfoPage.class)
----------------------------------------------------------------------------------------------------------
-===== Creating Custom Meta-Data via @Stereotype
+==== Creating Custom Meta-Data via @Stereotype
Like with CDI itself you can encapsulate multiple view meta-data
annotation in one annotation.
@@ -1315,7 +1313,7 @@ From DeltaSpike 1.0.1, it is possible to access such stereotype annotations as
well, once you annotate them with `@ViewMetaData`.
-===== Creating Custom Callbacks via @ViewMetaData
+==== Creating Custom Callbacks via @ViewMetaData
Via a custom ConfigPreProcessor it is possible to register custom
callbacks dynamically. The following listing shows a view-config which
@@ -1378,7 +1376,7 @@ the type of the callback (= class of the annotation) as additional
parameter for `#getExecutableCallbackDescriptor`.
-===== Creating Custom inline Meta-Data via @InlineViewMetaData
+==== Creating Custom inline Meta-Data via @InlineViewMetaData
This annotation can be used for view-meta-data which can be placed on
other classes than view-config-classes. It is used, for example, for `@ViewRef`.
@@ -1390,7 +1388,7 @@ support one side since the inline-meta-data was converted to the same
meta-data representation which is used for the normal view-meta-data).
-==== Path-Validation
+=== Path-Validation
DeltaSpike (after v0.5) validates your configs out-of-the-box. The
application will fail to start, if there is an invalid config (e.g. a
@@ -1403,26 +1401,26 @@ To disable the view-config (path) validation, add a `ClassDeactivator`
which restricts
`org.apache.deltaspike.jsf.impl.config.view.ViewConfigPathValidator`.
-==== View-Config SPI
+=== View-Config SPI
-===== ConfigDescriptorValidator
+==== ConfigDescriptorValidator
Allows to validate the final view-config descriptors before they get
deployed. Since the config-descriptor contains, for example, the final path, it is
also possible to validate if the corresponding file exists. Use
`@ViewConfigRoot` to configure 1-n validators.
-===== ConfigNodeConverter
+==== ConfigNodeConverter
Allows to provide custom strategies to process the nodes of the built
config-tree. Use `@ViewConfigRoot` to configure a custom converter.
-===== ConfigPreProcessor
+==== ConfigPreProcessor
Allows to change the found meta-data (e.g. replace default values,
callbacks,...) or the `ViewConfigNode` itself.
-===== InlineMetaDataTransformer
+==== InlineMetaDataTransformer
Allows to transform an annotation annotated with `@InlineViewMetaData`
to an annotation annotated with `@ViewMetaData`. This transformer is
@@ -1431,24 +1429,24 @@ the inline-meta-data needs a different syntax via a different annotation
(compared to the view-config meta-data). See for example `@ViewRef` vs.
`@ViewControllerRef`.
-===== TargetViewConfigProvider
+==== TargetViewConfigProvider
Allows to provide a custom reference to `ViewConfig` classes (see for example
`@InlineViewMetaData` and `@ViewRef`)
-===== ViewConfigInheritanceStrategy
+==== ViewConfigInheritanceStrategy
Allows to customize the inheritance-strategy for meta-data. For example,
inheritance via standard java inheritance vs. inheritance via nested
interfaces. Use `@ViewConfigRoot` to configure a custom
inheritance-strategy.
-===== ViewConfigNode
+==== ViewConfigNode
Node-type used for building the meta-data-tree during the bootstrapping
process.
-===== @ViewConfigRoot
+==== @ViewConfigRoot
Optional annotation which allows to provide custom implementations. Only
annotate one `ViewConfig` class which represents the root node.
@@ -1470,7 +1468,7 @@ public interface Pages extends ViewConfig
}
-----------------------------------------
-==== Activation of Custom Naming Conventions
+=== Activation of Custom Naming Conventions
DeltaSpike allows to customize the default naming convention via
`View.DefaultBasePathBuilder` and/or `View.DefaultFileNameBuilder`
@@ -1481,9 +1479,7 @@ provided by DeltaSpike. The same is supported for folders via
`Folder.DefaultFolderNameBuilder`. In this case changing only one usage
is possible via `Folder.folderNameBuilder`.
-=== (Grouped-)Conversations
-
-Available from DeltaSpike 0.6.
+== (Grouped-)Conversations
DeltaSpike conversations are based on the window-scope. Therefore, do not
forget to add the `ds:windowId`
@@ -1618,7 +1614,7 @@ public class CustomBean2
}
------------------------------------------------
-==== Terminating Conversations
+=== Terminating Conversations
You can inject the conversation via `@Inject` and use it to terminate
the conversation immediately or you inject the
@@ -1736,7 +1732,7 @@ because the behaviour of standard conversations breaks a lot of use-cases.
However, if you really need to keep them until the end of the request,
you can close them in a `@PostRenderView` callback.
-==== Sub-Conversation-Groups
+=== Sub-Conversation-Groups
Due to the parallel conversation concept of DeltaSpike there is no need
of something like nested conversations. Just use them in parallel and
@@ -1818,16 +1814,16 @@ In the listing above all beans which implement the Wizard interface will
be closed as soon as you close the ImplicitSubGroup.
-=== Injection in JSF Artifacts
+== Injection in JSF Artifacts
-==== Converter and Validator
+=== Converter and Validator
Per default the JSF module of DeltaSpike handles JSF converters and validators as std. CDI beans and
therefore it's possible to use injection, lifecycle-callbacks, scope-annotations,...
the same way as with any other CDI bean.
The usage is the same as for `PhaseListener` s.
-==== PhaseListener
+=== PhaseListener
Once a std. JSF-`PhaseListener` is annotated with `@org.apache.deltaspike.jsf.api.listener.phase.JsfPhaseListener`,
that `PhaseListener` gets active without additional config in `faces-config.xml`.
@@ -1867,9 +1863,9 @@ public class DoubleSubmitAwarePhaseListener implements PhaseListener, Deactivata
------------------------------------------------------------------------
-=== Event broadcasting
+== Event broadcasting
-==== Observe Faces-Requests
+=== Observe Faces-Requests
It is possible to observe JSF-Requests via `@Observes` in combination with
`@org.apache.deltaspike.core.api.lifecycle.Initialized` or
@@ -1889,7 +1885,7 @@ public void onAfterFacesRequest(@Observes @Destroyed FacesContext facesContext)
}
------------------------------------------------------------------------
-==== BeforePhase / AfterPhase
+=== BeforePhase / AfterPhase
It is possible to observe JSF request-lifecycle phase-events via `@Observes` in combination with
`@org.apache.deltaspike.jsf.api.listener.phase.BeforePhase` or
@@ -1909,7 +1905,7 @@ public void onPhaseEnd(@Observes @AfterPhase(JsfPhaseId.ANY_PHASE) PhaseEvent ev
}
------------------------------------------------------------------------
-==== JSF SystemEvents
+=== JSF SystemEvents
Following JSF SystemEvents can be observed via CDI:
@@ -1930,15 +1926,15 @@ public class ApplicationConfig
}
-------------------------------------------------------------------
-=== Intergration with Exception Control (from DeltaSpike 0.6)
+== Integration with Exception Control
Whenever a unhandled exception occurs within the JSF lifecycle, our JSF
ExceptionHandler provides a integration to the DeltaSpike Exception
Control.
-==== Examples
+=== Examples
-===== Basic
+==== Basic
-----------------------------------------------------------------------------
@ExceptionHandler
@@ -1954,7 +1950,7 @@ public class ApplicationExceptionHandler
}
-----------------------------------------------------------------------------
-===== Redirect
+==== Redirect
[source,java]
-----------------------------------------------------------------------------------------------------------------------------------
@@ -1974,7 +1970,7 @@ public class ApplicationExceptionHandler
}
-----------------------------------------------------------------------------------------------------------------------------------
-==== Using a Custom Qualifier for JSF Exceptions
+=== Using a Custom Qualifier for JSF Exceptions
In some cases, it is required to differentiate exceptions from JSF and
normal exceptions. This is possible via a CDI qualifier:
@@ -2014,7 +2010,7 @@ public class ApplicationExceptionHandler
}
-----------------------------------------------------------------------------------------------------------------------------------
-=== Double-Submit Prevention
+== Double-Submit Prevention
To avoid that the same content of a form gets submitted and therefore
processed multiple times, it is possible to use the tag
@@ -2039,7 +2035,7 @@ within every JSF form-tag, you would like to safeguard.
</html>
--------------------------------------------------
-=== Tips
+== Tips
Using errorView, DefaultErrorView or ViewNavigationHandler will fail
with Weld versions older than 1.1.10 due to
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/partial-bean.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/partial-bean.adoc b/documentation/src/main/asciidoc/partial-bean.adoc
index b5a1c69..991598a 100644
--- a/documentation/src/main/asciidoc/partial-bean.adoc
+++ b/documentation/src/main/asciidoc/partial-bean.adoc
@@ -7,7 +7,7 @@
== Overview
The Partial-Bean module provides means for implementing a generic handler to replace manual implementations of interfaces (or abstract classes).
-== Configure Your Projects
+== Project Setup
The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
=== Declare Partial-Bean Module Dependencies
@@ -30,12 +30,10 @@ Add the Partial-Bean module to the list of dependencies in the project `pom.xml`
</dependency>
----
-== Use the Module Features
-
IMPORTANT: Currently CDI Interceptors applied via @Interceptors and @Decorator are not supported by partial beans!
-=== @PartialBeanBinding
+== @PartialBeanBinding
Partial beans allow you to implement a generic handler to replace manual
implementations of interfaces (or abstract classes).
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/scheduler.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/scheduler.adoc b/documentation/src/main/asciidoc/scheduler.adoc
index 70fe4ba..d8ae424 100644
--- a/documentation/src/main/asciidoc/scheduler.adoc
+++ b/documentation/src/main/asciidoc/scheduler.adoc
@@ -8,7 +8,7 @@
== Overview
The Scheduler module provides simple integration with Quartz v2 (default) or any other scheduler that supports cron-expressions for job-classes.
-== Configure Your Projects
+== Project Setup
The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
=== 1. Declare Scheduler Module Dependencies
@@ -65,9 +65,7 @@ Scheduled jobs can have built-in CDI contexts started for the duration of their
</dependency>
----
-== Use the Module Features
-
-=== @Scheduled
+== @Scheduled
Just annotate your Quartz-Jobs with `@Scheduled` and they will get
picked up and passed to the scheduler automatically (during the
@@ -135,7 +133,7 @@ public class ProjectStageAwareSchedulerController
}
-------------------------------------------------------------------------------------
-=== Manual Scheduler Control
+== Manual Scheduler Control
Th SPI allows to control the scheduler (or integrate any other
compatible scheduler as an alternative to Quartz2)
@@ -176,7 +174,7 @@ or
</alternatives>
-----------------------------------------------------------------------------
-=== Custom Scheduler
+== Custom Scheduler
It is possible to replace the default integration with Quartz. Any scheduler that supports cron-expressions for job-classes can be used.
For more information, see link:https://deltaspike.apache.org/javadoc/{latestStable}/org/apache/deltaspike/scheduler/spi/Scheduler.html[Scheduler javadoc].
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/security.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/security.adoc b/documentation/src/main/asciidoc/security.adoc
index 362a37a..3282002 100644
--- a/documentation/src/main/asciidoc/security.adoc
+++ b/documentation/src/main/asciidoc/security.adoc
@@ -5,9 +5,19 @@
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
== Overview
-The Security module provides intercept and security checking on method calls. This module also enables integration of third-party security frameworks and custom security concepts.
-== Configure Your Projects
+The Security module provides APIs for authorization of method invocations.
+
+There are two different APIs provided for two different approaches -- one simple interceptor-style API and another for more complex scenarios.
+
+* *<<_simple_interceptor_style_authorization, Simple interceptor-style API>>:* the method that is to be secured is loosely coupled to a predicate method
+(called _authorizer_ method) which decides whether the secured method invocation should proceed. Similarly to CDI
+interceptors, the secured method and the authorizer are tied together using a binding annotation --
+`@SecurityBindingType` in this case.
+
+* *<<_advanced_authorization, Advanced API>>:* this API offers fine-grained control over the authorization process. Multiple independent _voters_ can participate in making the authorization decision and possibly return _security violations_ and thus prevent the method invocation. The voters share a common context. This API is suitable for integration with third-party security frameworks. Also, this API can be used to <<jsf.adoc#_security_integration_via_secured, secure JSF view access>> when using the DeltaSpike JSF module.
+
+== Project Setup
The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
=== 1. Declare Security Module Dependencies
@@ -30,7 +40,7 @@ Add the Security module to the list of dependencies in the project `pom.xml` fil
</dependency>
----
-=== 2. Enable the Security Interceptor
+=== 2. Enable the SecurityInterceptor
For CDI 1.0 (or DeltaSpike v1.1.0 and earlier together with CDI 1.1+), you must enable the security interceptor in the project `beans.xml` file:
[source,xml]
@@ -43,46 +53,39 @@ For CDI 1.0 (or DeltaSpike v1.1.0 and earlier together with CDI 1.1+), you must
</beans>
----
-== Use the Module Features
-
-=== SecurityBinding for Class and Method Invocations
+== Simple interceptor-style authorization
This feature of the Security module intercepts method calls and performs a security check before invocation is allowed to proceed.
-In order to use the DeltaSpike security module, you must first have
-installed the proper dependencies into the `pom.xml` file. Once this is
-complete, you may proceed to create a security parameter binding
-annotation. This is what we will use to add security behavior to our
-business classes and methods.
+The first piece of code required to use this API is a _security binding_ annotation. This is what we will use to add security behavior to our business classes and methods.
-.Create the SecurityBinding
+.Create the security binding annotation
[source,java]
----
@Retention(value = RUNTIME)
@Target({TYPE, METHOD})
@Documented
@SecurityBindingType
-public @interface CustomSecurityBinding {
-}
+public @interface UserLoggedIn {}
----
-Next, we must define an Authorizer class to implement behavior for our
-custom SecurityBindingType. This class is simply a CDI bean which
-declares a @Secures method, qualified with the security binding
+Next, we must define an _authorizer_ class to implement behavior for our
+custom security binding type. This class is simply a CDI bean which
+declares a method annotated `@Secures`, qualified with the security binding
annotation we created in the first step.
-This method has access to the InvocationContext of the method call, so
+This method has access to the `InvocationContext` of the method call, so
if we need to access parameter arguments, we can do so using the given
context. Note that we may also inject other beans into the parameter
-list of our @Secures method.
+list of our authorizer method.
-.Create the Authorizer
+.Create the authorizer
[source,java]
---------------------------------------------------------------------------------------------------------------------------------
@ApplicationScoped
-public class CustomAuthorizer
+public class LoggedInAuthorizer
{
@Secures
- @CustomSecurityBinding
+ @UserLoggedIn
public boolean doSecuredCheck(InvocationContext invocationContext, BeanManager manager, Identity identity) throws Exception
{
return identity.isLoggedIn(); // perform security check
@@ -92,15 +95,15 @@ public class CustomAuthorizer
We can then use our new annotation to secure business or bean methods.
This binding annotation may be placed on the entire class (securing all
-methods,) or on individual methods that you wish to secure.
+methods) or on individual methods that you wish to secure.
-.Secure a Bean Method
+.Secure a bean method
[source,java]
----------------------------------------
@ApplicationScoped
public class SecuredBean1
{
- @CustomSecurityBinding
+ @UserLoggedIn
public void doSomething(Thing thing)
{
thing.doSomething();
@@ -109,10 +112,10 @@ public class SecuredBean1
----------------------------------------
Next, we may access parameter values from the method invocation directly
-in our authorizer bean by creating custom @SecurityParameterBinding
+in our authorizer bean by creating custom `@SecurityParameterBinding`
types; this is a simple step once we have completed the work above:
-.Create a Parameter Binding Annotation
+.Create a parameter binding annotation
[source,java]
--------------------------------
@Retention(value = RUNTIME)
@@ -127,14 +130,14 @@ Now, when a secured method is invoked, we can inject actual parameter
values as arguments into our authorizer method, providing domain-level
security in our applications:
-.Update the Authorizer to use Parameter Binding
+.Update the authorizer to use parameter binding
[source,java]
------------------------------------------------------------------------------------------------------------------------------------------------------------
@ApplicationScoped
public class CustomAuthorizer
{
@Secures
- @CustomSecurityBinding
+ @UserLoggedIn
public boolean doSecuredCheck(InvocationContext invocationContext, BeanManager manager, Identity identity, @CurrentThing Thing thing) throws Exception
{
return thing.hasMember(identity); // perform security check against our method parameter
@@ -150,7 +153,7 @@ Note that our business method must also be annotated.
@ApplicationScoped
public class SecuredBean1
{
- @CustomSecurityBinding
+ @UserLoggedIn
public void doSomething(@CurrentThing Thing thing)
{
thing.doSomething();
@@ -171,7 +174,7 @@ case:
@ApplicationScoped
public class SecuredBean1
{
- @CustomSecurityBinding
+ @UserLoggedIn
public Thing loadSomething()
{
return thingLoader.load();
@@ -180,7 +183,7 @@ public class SecuredBean1
----------------------------------
Now you need to access the return value in the authorizer method. You
-can inject it using the @SecuredReturn annotation. Update the Authorizer
+can inject it using the `@SecuredReturn` annotation. Update the authorizer
to use a secured return value:
[source,java]
@@ -189,7 +192,7 @@ to use a secured return value:
public class CustomAuthorizer
{
@Secures
- @CustomSecurityBinding
+ @UserLoggedIn
public boolean doSecuredCheck(@SecuredReturn Thing thing, Identity identity) throws Exception
{
return thing.hasMember(identity); // perform security check against the return value
@@ -199,36 +202,9 @@ public class CustomAuthorizer
Now the authorization will take place after the method invocation using
the return value of the business method.
-.Complete the Parameter Binding
-[source,java]
-------------------------------------------------------
-@ApplicationScoped
-public class SecuredBean1
-{
- @CustomSecurityBinding
- public void doSomething(@CurrentThing Thing thing)
- {
- thing.doSomething();
- }
-}
-------------------------------------------------------
-
-Our method is now secured, and we are able to use given parameter values
-as part of our security authorizer!
-
-
-=== Integrating Third-party Security Frameworks
+== Advanced authorization
-==== @Secured
-
-`@Secured` is build on `@SecurityBindingType` and a very simple
-alternative to the rest of the security module. It is a basic hook to
-integrate a custom security concept, third-party frameworks, etc. It
-does not provide a full blown security concept like the rest of the
-security module, but other DeltaSpike modules ensure that the security
-concepts are integrated properly (e.g. correct behaviour within custom
-scope implementations,...). It just allows to integrate other security
-frameworks easily.
+This is an alternative to the simple annotation-based interceptor-style API. This API uses the annotation `@Secured` and is mainly a hook for integration of custom security concepts and third-party frameworks. The DeltaSpike Security module is _not_ a full application security solution, but some of the other DeltaSpike modules are security-enabled and use this API (e.g. correct behaviour within custom scope implementations,...). Internally, this `@Secured` API uses the `@Secures`/`@SecurityBindingType` API.
(In MyFaces CODI it was originally a CDI interceptor. This part changed
a bit, because between the interceptor and `@Secured` is the
@@ -236,6 +212,8 @@ a bit, because between the interceptor and `@Secured` is the
approach. Therefore the basic behaviour remains the same and you can
think about it like an interceptor.)
+The entry point to this API is the `@Secured` annotation placed either on the whole class -- enabling security for all methods -- or on individual methods. The only other prerequisite is at least one `AccessDecisionVoter` implementation, explained in the next section.
+
.Securing All Intercepted Methods of a CDI Bean
[source,java]
-----------------------------------------
@@ -261,9 +239,9 @@ public class SecuredBean
}
---------------------------------------------
-==== AccessDecisionVoter
+=== AccessDecisionVoter
-This interface is (besides the `Secured` annotation) the most important
+This interface is (besides the `@Secured` annotation) the most important
part of the concept. Both artifact types are also the only required
parts:
@@ -281,9 +259,11 @@ public class CustomAccessDecisionVoter implements AccessDecisionVoter
}
--------------------------------------------------------------------------------------------------------
+////
[TODO] tip about the changed parameter/s
+////
-==== SecurityViolation
+=== SecurityViolation
In case of a detected violation a `SecurityViolation` has to be added to
the result returned by the `AccessDecisionVoter`.
@@ -309,7 +289,7 @@ public class CustomAccessDecisionVoter extends AbstractAccessDecisionVoter
-----------------------------------------------------------------------------------------
-==== @Secured and Stereotypes with Custom Meta-data
+=== @Secured and stereotypes with custom metadata
If there are multiple `AccessDecisionVoter` and maybe in different
constellations, it is easier to provide an expressive CDI stereotypes for
@@ -334,9 +314,9 @@ public @interface Admin
}
-------------------------------------------
-Furthermore, it is possible to provide custom meta-data easily.
+Furthermore, it is possible to provide custom metadata easily.
-.Stereotype of @Secured with Custom Meta-data
+.Stereotype of @Secured with custom metadata
[source,java]
------------------------------------------------------------------------------------------
@Named
@@ -368,146 +348,6 @@ public class RoleAccessDecisionVoter implements AccessDecisionVoter
}
------------------------------------------------------------------------------------------
-=== Making Intitially Requested and Secured Page available for Redirect after Login
-
-DeltaSpike can be combined with pure CDI or with any other security
-frameworks (like PicketLink) to track the denied page and make it
-available after user logs in.
-
-
-==== CDI Implementation to Redirect the Login to the First Denied Page
-
-Your LoginService will fire a custom `UserLoggedInEvent`
-
-[source,java]
-------------------------------------------------------------
-public class LoginService implements Serializable {
-
- @Inject
- private Event<UserLoggedInEvent> userLoggedInEvent;
-
- public Usuario login(String username, char[] password) {
- //do the loggin process
- userLoggedInEvent.fire(new UserLoggedInEvent());
- }
-
-}
-------------------------------------------------------------
-
-Use @SessionScoped or @WindowScoped for AdminAccessDecisionVoter and
-store the denied page on your own.
-
-[source,java]
---------------------------------------------------------------------------------------------------------------------------------------------------
-@SessionScoped //or @WindowScoped
-public class AdminAccessDecisionVoter extends AbstractAccessDecisionVoter {
-
- @Inject
- private ViewConfigResolver viewConfigResolver;
-
- private Class<? extends ViewConfig> deniedPage = Pages.Home.class;
-
- @Override
- protected void checkPermission(AccessDecisionVoterContext context, Set<SecurityViolation> violations) {
- if(loggedIn) {
- //...
- } else {
- violations.add(/*...*/);
- deniedPage = viewConfigResolver.getViewConfigDescriptor(FacesContext.getCurrentInstance().getViewRoot().getViewId()).getConfigClass();
- }
- }
-
- public Class<? extends ViewConfig> getDeniedPage() {
- try {
- return deniedPage;
- } finally {
- deniedPage = Pages.Home.class;
- }
- }
-}
---------------------------------------------------------------------------------------------------------------------------------------------------
-
-And in AuthenticationListener you inject AdminAccessDecisionVoter
-
-[source,java]
-----------------------------------------------------------------------------------------
-public class AuthenticationListener {
-
- @Inject
- private ViewNavigationHandler viewNavigationHandler;
-
- @Inject
- private AdminAccessDecisionVoter adminAccessDecisionVoter;
-
- public void handleLoggedIn(@Observes UserLoggedInEvent event) {
- this.viewNavigationHandler.navigateTo(adminAccessDecisionVoter.getDeniedPage());
- }
-
-}
-----------------------------------------------------------------------------------------
-
-==== PicketLink Implementation to Redirect the Login to the First Denied Page
-
-Once that PicketLink handles the authentication for you, you only need
-to store the denied page and observe PicketLink `LoggedInEvent` to
-redirect you back to the denied page.
-
-Use @SessionScoped or @WindowScoped for AdminAccessDecisionVoter and
-store the denied page on your own.
-
-[source,java]
---------------------------------------------------------------------------------------------------------------------------------------------------
-@SessionScoped //or @WindowScoped
-public class AdminAccessDecisionVoter extends AbstractAccessDecisionVoter {
-
- @Inject
- private ViewConfigResolver viewConfigResolver;
-
- private Class<? extends ViewConfig> deniedPage = Pages.Home.class;
-
- @Override
- protected void checkPermission(AccessDecisionVoterContext context, Set<SecurityViolation> violations) {
-
- AuthorizationChecker authorizationChecker = BeanProvider.getContextualReference(AuthorizationChecker.class);
- boolean loggedIn = authorizationChecker.isLoggedIn();
-
- if(loggedIn) {
- //...
- } else {
- violations.add(/*...*/);
- deniedPage = viewConfigResolver.getViewConfigDescriptor(FacesContext.getCurrentInstance().getViewRoot().getViewId()).getConfigClass();
- }
- }
-
- public Class<? extends ViewConfig> getDeniedPage() {
- try {
- return deniedPage;
- } finally {
- deniedPage = Pages.Home.class;
- }
- }
-}
---------------------------------------------------------------------------------------------------------------------------------------------------
-
-And in AuthenticationListener you inject AdminAccessDecisionVoter
-
-[source,java]
-----------------------------------------------------------------------------------------
-public class AuthenticationListener {
-
- @Inject
- private ViewNavigationHandler viewNavigationHandler;
-
- @Inject
- private AdminAccessDecisionVoter adminAccessDecisionVoter;
-
- public void handleLoggedIn(@Observes LoggedInEvent event) {
- this.viewNavigationHandler.navigateTo(adminAccessDecisionVoter.getDeniedPage());
- }
-
-}
-----------------------------------------------------------------------------------------
-
=== AccessDecisionVoterContext
Because the `AccessDecisionVoter` can be chained,
@@ -522,7 +362,7 @@ There are several methods that can be useful
* `getMetaData()` - Exposes the found meta-data, for example the view-config-class if `@Secured` is used in combination with type-safe view-configs
* `getMetaDataFor(String, Class<T>)` - Exposes meta-data for the given key
-==== SecurityStrategy SPI
+=== SecurityStrategy SPI
The `SecurityStrategy` interface allows to provide a custom
implementation which should be used for `@Secured`. Provide a custom
@@ -537,5 +377,21 @@ In case of global-alternatives an additional configuration needs to be added to
globalAlternatives.org.apache.deltaspike.security.spi.authorization.SecurityStrategy=mypackage.CustomSecurityStrategy
----
-TIP: The configuration for global-alternatives is following the pattern:
-globalAlternatives.`<interface-name>`=`<implementation-class-name>`
+TIP: The configuration for global alternatives is following the pattern:
+`globalAlternatives._<interface-name>_=_<implementation-class-name>_`
+
+
+=== Examples
+
+==== Redirect to requested page after login
+DeltaSpike can be combined with pure CDI or with any other security
+frameworks (like PicketLink) to track the denied page and make it
+available after user logs in.
+
+An example of this use case is available in the examples module in the DeltaSpike repository:
+
+* link:https://github.com/apache/deltaspike/tree/master/deltaspike/examples/security-requested-page-after-login-cdi[Making initially requested secured page available for redirect after login with CDI]
+
+* link:https://github.com/apache/deltaspike/tree/master/deltaspike/examples/security-requested-page-after-login-picketlink[Making initially requested secured page available for redirect after login with PicketLink]
+
+The relevant classes are `AuthenticationListener` and `LoggedInAccessDecisionVoter`.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/servlet.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/servlet.adoc b/documentation/src/main/asciidoc/servlet.adoc
index 4466a0c..8701db6 100644
--- a/documentation/src/main/asciidoc/servlet.adoc
+++ b/documentation/src/main/asciidoc/servlet.adoc
@@ -7,7 +7,7 @@
== Overview
The Servlet module provides CDI integration with the Java Servlet API. It enables injection of common servlet objects and propagation of servlet events to the CDI event bus.
-== Configure Your Projects
+== Project Setup
The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
=== 1. Declare Servlet Module Dependencies
@@ -30,7 +30,7 @@ Add the Servlet module to the list of dependencies in the project `pom.xml` file
</dependency>
----
-== 2. Configure Listeners and Filters
+=== 2. Configure Listeners and Filters
In most cases there is no need for any additional configuration beside
adding the required dependencies to your project, because all required
@@ -88,9 +88,7 @@ In these cases you will have to add the following section manually to the projec
</filter-mapping>
-------------------------------------------------------------------------------------------------------------
-== Use the Module Features
-
-=== Injectable Servlet Objects
+== Injectable Servlet Objects
The DeltaSpike Servlet module contains producers for many objects of a
Servlet environment. All produces are using the special qualifier
@@ -105,7 +103,7 @@ The following code shows the general injection pattern to use for all objects.
private ServletObject servletObject;
------------------------------------
-==== ServletContext
+=== ServletContext
The `ServletContext` is made available in the application scope. It can
be injected into any CDI bean like this:
@@ -116,7 +114,7 @@ be injected into any CDI bean like this:
private ServletContext servletContext;
--------------------------------------
-==== ServletRequest / HttpServletRequest
+=== ServletRequest / HttpServletRequest
The `ServletRequest` is made available in the request scope. The current
request can be injected into a CDI bean like this:
@@ -136,7 +134,7 @@ private HttpServletRequest request;
-----------------------------------
-==== ServletResponse / HttpServletResponse
+=== ServletResponse / HttpServletResponse
The `ServletResponse` is made available in the request scope. The
current response can be injected into a CDI bean like this:
@@ -155,7 +153,7 @@ In case of HTTP requests you can also inject the `HttpServletResponse`:
private HttpServletResponse response;
-------------------------------------
-==== HttpSession
+=== HttpSession
The `HttpSession` is made available in the session scope. You can inject
the current session of a user into a CDI bean like this:
@@ -169,7 +167,7 @@ private HttpSession session;
Please note that injecting the session this way will force the creation
of a session.
-==== Principal
+=== Principal
The `Principal` is made available in the request scope. The current
principal can be injected into a CDI bean like this:
@@ -183,7 +181,7 @@ private Principal principal;
The `Principal` is obtained by calling `getUserPrincipal()` on the
`HttpServletRequest`.
-=== Servlet Event Propagation
+== Servlet Event Propagation
The DeltaSpike Servlet module propagates a number of Servlet object
lifecycle events to the CDI event bus. This allows regular CDI beans to
@@ -196,7 +194,7 @@ object, DeltaSpike uses the qualifiers `@Initialized` and `@Destroyed`.
The following sections shows which concrete Servlet objects are
supported and how their lifecycle can be observed.
-==== Servlet Context Lifecycle Events
+=== Servlet Context Lifecycle Events
The Servlet module supports initialization and destruction events for
the `ServletContext`. These events can for example be used to detect
@@ -227,7 +225,7 @@ If you manually registered the required filters and listeners, you can
also simply remove the entry for the `EventBridgeContextListener` from
your `web.xml` to disable the events.
-==== Request and Response Lifecycle Events
+=== Request and Response Lifecycle Events
The Servlet module also supports initialization and destruction events
for the `HttpServletRequest` and `HttpServletResponse`. These events can
@@ -275,7 +273,7 @@ If you manually registered the required filters and listeners you can
also simply remove the entry for the `EventBridgeFilter` from your
`web.xml` to disable the events.
-==== Session Lifecycle Events
+=== Session Lifecycle Events
The last category of events supported by the DeltaSpike Servlet module
are the lifecycle events for the user's HTTP session. The following
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/test-control.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/test-control.adoc b/documentation/src/main/asciidoc/test-control.adoc
index 0ce28dd..6a9ccc2 100644
--- a/documentation/src/main/asciidoc/test-control.adoc
+++ b/documentation/src/main/asciidoc/test-control.adoc
@@ -8,7 +8,7 @@
== Overview
The Test-Control module enables you to write CDI-based tests easily. Calls to stop and start the CDI container are built into the Test-Control API, with simplified commands for customizing the management of contexts and other aspects during testing.
-== Configure Your Projects
+== Project Setup
The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
=== 1. Declare Test-Control Module Dependencies
@@ -104,11 +104,9 @@ of dependencies instead of the OpenWebBeans-specific Container Control module:
Add a `beans.xml` file in the project test module (e.g. src/test/resources/META-INF/beans.xml).
-== Use the Module Features
+== Automated Container Booting and Shutdown
-=== Automated Container Booting and Shutdown
-
-==== CdiTestRunner
+=== CdiTestRunner
Start and stop the CDI container automatically per test class with CdiTestRunner, a JUnit Test-Runner.
This also starts and stops one request and session per test-method.
@@ -132,7 +130,7 @@ public class ContainerAndInjectionControl
}
--------------------------------------------------------
-==== CdiTestSuiteRunner
+=== CdiTestSuiteRunner
Extend automated CDI container start and stop actions to whole test suites with CdiTestSuiteRunner, a JUnit Test-Suite-Runner.
@@ -149,13 +147,13 @@ public class SuiteLevelContainerControl
}
---------------------------------------
-==== Optional Shutdown Configuration
+=== Optional Shutdown Configuration
You can set `deltaspike.testcontrol.stop_container` to `false` (via the standard DeltaSpike config), resulting in the CDI Container being started just once for all tests.
-=== Test Customization
+== Test Customization
-==== @TestControl
+=== @TestControl
Customize the default behavior of CdiTestRunner with @TestControl. In the following
case only one session for all test-methods (of the test-class) will be
@@ -172,7 +170,7 @@ public class CustomizedScopeHandling
}
-----------------------------------------------
-==== ProjectStage Control
+=== ProjectStage Control
Override the default ProjectStage for unit tests with `ProjectStage.UnitTest.class`.
@@ -195,7 +193,7 @@ public class TestStageControl
}
---------------------------------------------------------------
-=== Optional Configuration
+== Optional Configuration
From DeltaSpike 1.2, it is possible to provide a configuration for the underlying test-container.
However, currently only the adapter for OpenEJB embedded (available in CDI-Control) supports it out-of-the-box.
@@ -206,7 +204,7 @@ The content of the file are key/value pairs which get passed to the container.
Therefore, it is a configuration which is not used by DeltaSpike itself
(it is just forwarded (as it is) to the underlying test-container).
-==== Reconfigure the config-file Name or Location
+=== Reconfigure the config-file Name or Location
If you would like to point to an existing config-file, you have to add for example:
@@ -225,9 +223,9 @@ deltaspike.testcontrol.test-container.config-file.UnitTest=META-INF/unit-test/ex
---------------------------------------------------------------
-=== Optional Integrations
+== Optional Integrations
-==== Mock Frameworks
+=== Mock Frameworks
From DeltaSpike 1.0, it is possible to mock CDI-Beans. Usually @Exclude (+
ProjectStage) is enough, however, for some cases mocked beans might be
@@ -419,7 +417,7 @@ Mocking such typed beans can result in an
mocked implementation via `@Exclude` or `@Typed()` (or a parametrized
constructor) and specify the target-type via `@TypedMock`.
-==== JSF (via MyFaces-Test)
+=== JSF (via MyFaces-Test)
add on of
@@ -434,7 +432,7 @@ as content to
(in your config-folder for tests, e.g. test/resources)
-=== Using jersey-test with test-control
+== Using jersey-test with test-control
Jersey-test starts jetty which answers requests in a separated thread. Since ds test-control just handles the thread of the test itself, it's needed to integrate jetty and jersey with the cdi-container. Usually that's done via a ServletRequestListener - the following part describes an alternative approach for jersey-test:
@@ -509,7 +507,7 @@ public class CdiAwareHandlerWrapper extends HandlerWrapper
}
-------------------------------------------------------------------------------------------
-=== Mixed Tests
+== Mixed Tests
Usually you should have one kind of tests per test-module. However, if
you need to add, for example, a test without an external-container to your
@@ -527,9 +525,9 @@ public class JsfContainerTest
---------------------------------------------
-=== Known Restrictions
+== Known Restrictions
-==== Liquibase
+=== Liquibase
Liquibase invokes `#toString` in a `AfterDeploymentValidation` observer.
*that is not portable* and therefore you have to deactivate the
@@ -553,7 +551,7 @@ org.apache.deltaspike.core.spi.activation.ClassDeactivator=myPackage.LiquibaseAw
Further details are available at deactivatable.
-==== Gradle
+=== Gradle
Gradle by default does not put resources and compiled sources in to the same directory.
When running a test using Gradle, this means your classes will not be in bean archives as
@@ -574,9 +572,9 @@ sourceSets {
}
----------------------------------------------------------------------------------------------------------
-=== SPI
+== SPI
-==== ExternalContainer
+=== ExternalContainer
org.apache.deltaspike.testcontrol.spi.ExternalContainer allows to
integrate containers which get started after the CDI container.
[2/2] deltaspike git commit: DELTASPIKE-898 Make documentation
structure more comprehensible
Posted by rs...@apache.org.
DELTASPIKE-898 Make documentation structure more comprehensible
* restructured security doc page
* also moved long code examples from security doc to actual examples projects
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/e67d64a2
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/e67d64a2
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/e67d64a2
Branch: refs/heads/master
Commit: e67d64a247d110db8e4f51ba8eb403e28c05710f
Parents: 1c828f3
Author: Ron Smeral <rs...@apache.org>
Authored: Tue May 12 20:38:53 2015 +0200
Committer: Ron Smeral <rs...@apache.org>
Committed: Tue May 12 20:41:18 2015 +0200
----------------------------------------------------------------------
deltaspike/examples/pom.xml | 2 +
.../README.md | 10 +
.../pom.xml | 73 +++++
.../cdi/AuthenticationListener.java | 45 +++
.../cdi/LoggedInAccessDecisionVoter.java | 73 +++++
.../requestedpage/cdi/LoginController.java | 97 +++++++
.../security/requestedpage/cdi/Pages.java | 43 +++
.../security/requestedpage/cdi/UserEvent.java | 30 ++
.../src/main/webapp/WEB-INF/beans.xml | 26 ++
.../src/main/webapp/WEB-INF/faces-config.xml | 8 +
.../src/main/webapp/WEB-INF/web.xml | 41 +++
.../src/main/webapp/index.html | 15 +
.../src/main/webapp/login.xhtml | 26 ++
.../src/main/webapp/secured/home.xhtml | 14 +
.../README.md | 10 +
.../pom.xml | 93 +++++++
.../picketlink/AuthenticationListener.java | 47 ++++
.../requestedpage/picketlink/Initializer.java | 57 ++++
.../picketlink/LoggedInAccessDecisionVoter.java | 76 +++++
.../requestedpage/picketlink/Pages.java | 44 +++
.../src/main/webapp/WEB-INF/beans.xml | 26 ++
.../src/main/webapp/WEB-INF/faces-config.xml | 8 +
.../src/main/webapp/WEB-INF/web.xml | 41 +++
.../src/main/webapp/index.html | 15 +
.../src/main/webapp/login.xhtml | 26 ++
.../src/main/webapp/secured/home.xhtml | 14 +
.../src/main/asciidoc/bean-validation.adoc | 8 +-
.../src/main/asciidoc/container-control.adoc | 24 +-
documentation/src/main/asciidoc/data.adoc | 78 +++---
documentation/src/main/asciidoc/jpa.adoc | 12 +-
documentation/src/main/asciidoc/jsf.adoc | 170 ++++++------
.../src/main/asciidoc/partial-bean.adoc | 6 +-
documentation/src/main/asciidoc/scheduler.adoc | 10 +-
documentation/src/main/asciidoc/security.adoc | 278 +++++--------------
documentation/src/main/asciidoc/servlet.adoc | 26 +-
.../src/main/asciidoc/test-control.adoc | 42 ++-
36 files changed, 1205 insertions(+), 409 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/pom.xml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/pom.xml b/deltaspike/examples/pom.xml
index f8dbfc3..3f61532 100644
--- a/deltaspike/examples/pom.xml
+++ b/deltaspike/examples/pom.xml
@@ -37,6 +37,8 @@
<module>jse-examples</module>
<module>jsf-examples</module>
<module>jsf-playground</module>
+ <module>security-requested-page-after-login-cdi</module>
+ <module>security-requested-page-after-login-picketlink</module>
<module>scheduler-playground</module>
</modules>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/README.md
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/README.md b/deltaspike/examples/security-requested-page-after-login-cdi/README.md
new file mode 100644
index 0000000..eced607
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/README.md
@@ -0,0 +1,10 @@
+Making initially requested secured page available for redirect after login with CDI
+===================================================================================
+
+The following scenario is commonly seen in web applications:
+
+1. User requests a web page
+2. The web page is restricted to logged in users so the browser is redirected to login page
+3. After successful login, the user is redirected back to the originally requested page
+
+This example shows pure CDI implementation of this technique.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/pom.xml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/pom.xml b/deltaspike/examples/security-requested-page-after-login-cdi/pom.xml
new file mode 100644
index 0000000..2bf42e8
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/pom.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.deltaspike.examples</groupId>
+ <artifactId>examples-project</artifactId>
+ <version>1.3.1-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>deltaspike-security-requested-page-after-login-cdi</artifactId>
+ <packaging>war</packaging>
+ <name>DeltaSpike Example: Show requested page after login with CDI</name>
+
+ <properties>
+ <deploy.skip>true</deploy.skip>
+ <picketlink.version>2.7.0.Final</picketlink.version>
+ </properties>
+
+ <dependencies>
+
+ <dependency>
+ <groupId>org.apache.myfaces.core</groupId>
+ <artifactId>myfaces-api</artifactId>
+ <version>${myfaces2.version}</version>
+ <scope>provided</scope>
+ </dependency>
+
+ <!-- DeltaSpike modules -->
+ <dependency>
+ <groupId>org.apache.deltaspike.core</groupId>
+ <artifactId>deltaspike-core-api</artifactId>
+ <scope>compile</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.deltaspike.core</groupId>
+ <artifactId>deltaspike-core-impl</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-jsf-module-api</artifactId>
+ <scope>compile</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-jsf-module-impl</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-security-module-api</artifactId>
+ <scope>compile</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-security-module-impl</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+
+ </dependencies>
+
+ <build>
+ <finalName>${project.artifactId}</finalName>
+ </build>
+
+</project>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/AuthenticationListener.java
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/AuthenticationListener.java b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/AuthenticationListener.java
new file mode 100644
index 0000000..77df254
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/AuthenticationListener.java
@@ -0,0 +1,45 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.deltaspike.example.security.requestedpage.cdi;
+
+import org.apache.deltaspike.core.api.config.view.navigation.ViewNavigationHandler;
+
+import javax.enterprise.event.Observes;
+import javax.inject.Inject;
+
+public class AuthenticationListener {
+
+ @Inject
+ private ViewNavigationHandler viewNavigationHandler;
+
+ @Inject
+ private LoggedInAccessDecisionVoter loggedInAccessDecisionVoter;
+
+ public void handleLoggedIn(@Observes UserEvent.LoggedIn event) {
+ this.viewNavigationHandler.navigateTo(loggedInAccessDecisionVoter.getDeniedPage());
+ System.err.println("handling loggedin");
+ }
+
+ public void handleFailed(@Observes UserEvent.LoginFailed event)
+ {
+ this.viewNavigationHandler.navigateTo(Pages.Login.class);
+ System.err.println("handling failed");
+ }
+
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/LoggedInAccessDecisionVoter.java
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/LoggedInAccessDecisionVoter.java b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/LoggedInAccessDecisionVoter.java
new file mode 100644
index 0000000..c613af9
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/LoggedInAccessDecisionVoter.java
@@ -0,0 +1,73 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.deltaspike.example.security.requestedpage.cdi;
+
+import org.apache.deltaspike.core.api.config.view.ViewConfig;
+import org.apache.deltaspike.core.api.config.view.metadata.ViewConfigResolver;
+import org.apache.deltaspike.security.api.authorization.AbstractAccessDecisionVoter;
+import org.apache.deltaspike.security.api.authorization.AccessDecisionVoterContext;
+import org.apache.deltaspike.security.api.authorization.SecurityViolation;
+
+import javax.enterprise.context.SessionScoped;
+import javax.faces.context.FacesContext;
+import javax.inject.Inject;
+import java.util.Set;
+
+@SessionScoped //or @WindowScoped
+public class LoggedInAccessDecisionVoter extends AbstractAccessDecisionVoter
+{
+
+ @Inject
+ private ViewConfigResolver viewConfigResolver;
+
+ @Inject
+ LoginController loginController;
+
+ private Class<? extends ViewConfig> deniedPage = Pages.Secure.Home.class;
+
+ @Override
+ protected void checkPermission(AccessDecisionVoterContext context, Set<SecurityViolation> violations)
+ {
+ if (loginController.isLoggedIn())
+ {
+ // no violations, pass
+ }
+ else
+ {
+ violations.add(new SecurityViolation()
+ {
+ @Override
+ public String getReason()
+ {
+ return "User must be logged in to access this resource";
+ }
+ });
+
+ // remember the requested page
+ deniedPage = viewConfigResolver
+ .getViewConfigDescriptor(FacesContext.getCurrentInstance().getViewRoot().getViewId())
+ .getConfigClass();
+ }
+ }
+
+ public Class<? extends ViewConfig> getDeniedPage()
+ {
+ return deniedPage;
+ }
+}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/LoginController.java
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/LoginController.java b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/LoginController.java
new file mode 100644
index 0000000..7b6c5f9
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/LoginController.java
@@ -0,0 +1,97 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.deltaspike.example.security.requestedpage.cdi;
+
+import javax.enterprise.context.RequestScoped;
+import javax.enterprise.event.Event;
+import javax.inject.Inject;
+import javax.inject.Named;
+
+@Named
+@RequestScoped
+public class LoginController
+{
+ public static final String DEFAULT_USER = "john";
+
+ public static final String DEFAULT_PASSWORD = "123456";
+
+ public static final String DEFAULT_NAME = "John User";
+
+ private String username;
+
+ private String password;
+
+ private boolean loggedIn = false;
+
+ @Inject
+ private Event<UserEvent.LoggedIn> evtLoggedIn;
+
+ @Inject
+ private Event<UserEvent.LoginFailed> evtLoginFailed;
+
+ public void login()
+ {
+ if (DEFAULT_USER.equals(username) && DEFAULT_PASSWORD.equals(password))
+ {
+ loggedIn = true;
+ evtLoggedIn.fire(new UserEvent.LoggedIn());
+ System.err.println("logged in");
+ }
+ else
+ {
+ evtLoginFailed.fire(new UserEvent.LoginFailed());
+ System.err.println("failed");
+ }
+ }
+
+ public void logout()
+ {
+ loggedIn = false;
+ }
+
+ public String getPassword()
+ {
+ return password;
+ }
+
+ public void setPassword(String password)
+ {
+ this.password = password;
+ }
+
+ public String getUsername()
+ {
+ return username;
+ }
+
+ public void setUsername(String username)
+ {
+ this.username = username;
+ }
+
+ public String getName()
+ {
+ return DEFAULT_NAME;
+ }
+
+ public boolean isLoggedIn()
+ {
+ return loggedIn;
+ }
+}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/Pages.java
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/Pages.java b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/Pages.java
new file mode 100644
index 0000000..ce46fc0
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/Pages.java
@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.deltaspike.example.security.requestedpage.cdi;
+
+import org.apache.deltaspike.core.api.config.view.DefaultErrorView;
+import org.apache.deltaspike.core.api.config.view.ViewConfig;
+import org.apache.deltaspike.jsf.api.config.view.Folder;
+import org.apache.deltaspike.security.api.authorization.Secured;
+
+@Folder(name = "/")
+public interface Pages
+{
+ class Login extends DefaultErrorView
+ {
+ }
+
+ @Folder(name = "/secured")
+ interface Secure extends ViewConfig
+ {
+
+ @Secured(LoggedInAccessDecisionVoter.class)
+ class Home implements Secure
+ {
+ }
+ }
+
+}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/UserEvent.java
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/UserEvent.java b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/UserEvent.java
new file mode 100644
index 0000000..fb035b8
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/java/org/apache/deltaspike/example/security/requestedpage/cdi/UserEvent.java
@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.deltaspike.example.security.requestedpage.cdi;
+
+public class UserEvent
+{
+ public static class LoggedIn
+ {
+ }
+
+ public static class LoginFailed
+ {
+ }
+}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/beans.xml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/beans.xml b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/beans.xml
new file mode 100644
index 0000000..d2acfab
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/beans.xml
@@ -0,0 +1,26 @@
+<!--
+ JBoss, Home of Professional Open Source
+ Copyright 2014, Red Hat, Inc. and/or its affiliates, and individual
+ contributors by the @authors tag. See the copyright.txt in the
+ distribution for a full listing of individual contributors.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<beans xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
+
+ <interceptors>
+ <class>org.apache.deltaspike.security.impl.extension.SecurityInterceptor</class>
+ </interceptors>
+
+</beans>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/faces-config.xml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/faces-config.xml b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/faces-config.xml
new file mode 100644
index 0000000..cce0e2f
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/faces-config.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<faces-config
+ xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_1.xsd"
+ version="2.1">
+
+</faces-config>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/web.xml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/web.xml b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/web.xml
new file mode 100644
index 0000000..23eddbc
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/WEB-INF/web.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version
+ 2.0 (the "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+ applicable law or agreed to in writing, software distributed under the
+ License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ CONDITIONS OF ANY KIND, either express or implied. See the License for
+ the specific language governing permissions and limitations under the
+ License.
+-->
+<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
+ version="3.0">
+
+ <context-param>
+ <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
+ <param-value>.xhtml</param-value>
+ </context-param>
+
+ <servlet>
+ <servlet-name>Faces Servlet</servlet-name>
+ <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>Faces Servlet</servlet-name>
+ <url-pattern>*.xhtml</url-pattern>
+ </servlet-mapping>
+
+ <welcome-file-list>
+ <welcome-file>index.html</welcome-file>
+ </welcome-file-list>
+</web-app>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/index.html
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/index.html b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/index.html
new file mode 100644
index 0000000..d252a75
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/index.html
@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+ <title>Index</title>
+</head>
+<body>
+<h1>Index</h1>
+
+<p>
+ This link points to a secured page and should redirect to login page:
+ <br>
+ <a href="secured/home.xhtml">Go Home</a>
+</p>
+</body>
+</html>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/login.xhtml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/login.xhtml b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/login.xhtml
new file mode 100644
index 0000000..5874598
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/login.xhtml
@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:h="http://java.sun.com/jsf/html">
+<head>
+ <title>Login</title>
+</head>
+
+<body>
+<h1>Log in</h1>
+<h:messages globalOnly="true"></h:messages>
+<h:form id="loginForm">
+ <h:outputLabel value="Username:" for="username"/><br/>
+ <h:inputText value="#{loginController.username}" id="username"/><br/><br/>
+ <h:outputLabel value="Password:" for="password"/><br/>
+ <h:inputSecret value="#{loginController.password}" id="password"/><br/>
+ <h:commandButton value="Log in" action="#{loginController.login()}" id="loginBtn"/>
+</h:form>
+
+<p>
+ <b>Hint:</b> log in as john / 123456
+</p>
+<br/>
+
+</body>
+
+</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/secured/home.xhtml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/secured/home.xhtml b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/secured/home.xhtml
new file mode 100644
index 0000000..f2fe303
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-cdi/src/main/webapp/secured/home.xhtml
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <title>Home Page</title>
+</head>
+
+<body>
+<h1>Hello, #{loginController.name}!</h1>
+
+<p>Welcome Home</p>
+
+</body>
+
+</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/README.md
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/README.md b/deltaspike/examples/security-requested-page-after-login-picketlink/README.md
new file mode 100644
index 0000000..ff6cff9
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/README.md
@@ -0,0 +1,10 @@
+Making initially requested secured page available for redirect after login with PicketLink
+==========================================================================================
+
+The following scenario is commonly seen in web applications:
+
+1. User requests a web page
+2. The web page is restricted to logged in users so the browser is redirected to login page
+3. After successful login, the user is redirected back to the originally requested page
+
+This example shows an implementation of this technique using PicketLink.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/pom.xml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/pom.xml b/deltaspike/examples/security-requested-page-after-login-picketlink/pom.xml
new file mode 100644
index 0000000..9b15373
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/pom.xml
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.deltaspike.examples</groupId>
+ <artifactId>examples-project</artifactId>
+ <version>1.3.1-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>deltaspike-security-requested-page-after-login-picketlink</artifactId>
+ <packaging>war</packaging>
+ <name>DeltaSpike Example: Show requested page after login with PicketLink</name>
+
+ <properties>
+ <deploy.skip>true</deploy.skip>
+ <picketlink.version>2.7.0.Final</picketlink.version>
+ </properties>
+
+ <dependencies>
+
+ <dependency>
+ <groupId>org.apache.myfaces.core</groupId>
+ <artifactId>myfaces-api</artifactId>
+ <version>${myfaces2.version}</version>
+ <scope>provided</scope>
+ </dependency>
+
+ <!-- DeltaSpike modules -->
+ <dependency>
+ <groupId>org.apache.deltaspike.core</groupId>
+ <artifactId>deltaspike-core-api</artifactId>
+ <scope>compile</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.deltaspike.core</groupId>
+ <artifactId>deltaspike-core-impl</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-jsf-module-api</artifactId>
+ <scope>compile</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-jsf-module-impl</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-security-module-api</artifactId>
+ <scope>compile</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-security-module-impl</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.picketlink</groupId>
+ <artifactId>picketlink-api</artifactId>
+ <scope>compile</scope>
+ <version>${picketlink.version}</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.picketlink</groupId>
+ <artifactId>picketlink-impl</artifactId>
+ <scope>compile</scope>
+ <version>${picketlink.version}</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>javaee-api</artifactId>
+ <version>6.0-6</version>
+ </dependency>
+
+ </dependencies>
+
+ <build>
+ <finalName>${project.artifactId}</finalName>
+ </build>
+
+</project>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/AuthenticationListener.java
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/AuthenticationListener.java b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/AuthenticationListener.java
new file mode 100644
index 0000000..5a048df
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/AuthenticationListener.java
@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.deltaspike.example.security.requestedpage.picketlink;
+
+import org.apache.deltaspike.core.api.config.view.navigation.ViewNavigationHandler;
+import org.picketlink.authentication.event.LoggedInEvent;
+import org.picketlink.authentication.event.LoginFailedEvent;
+
+import javax.enterprise.event.Observes;
+import javax.inject.Inject;
+
+public class AuthenticationListener
+{
+
+ @Inject
+ private ViewNavigationHandler viewNavigationHandler;
+
+ @Inject
+ private LoggedInAccessDecisionVoter loggedInAccessDecisionVoter;
+
+ public void handleLoggedIn(@Observes LoggedInEvent event)
+ {
+ this.viewNavigationHandler.navigateTo(loggedInAccessDecisionVoter.getDeniedPage());
+ }
+
+ public void handleFailed(@Observes LoginFailedEvent event)
+ {
+ this.viewNavigationHandler.navigateTo(Pages.Login.class);
+ }
+
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/Initializer.java
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/Initializer.java b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/Initializer.java
new file mode 100644
index 0000000..4498ab8
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/Initializer.java
@@ -0,0 +1,57 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.deltaspike.example.security.requestedpage.picketlink;
+
+import org.picketlink.idm.IdentityManager;
+import org.picketlink.idm.PartitionManager;
+import org.picketlink.idm.credential.Password;
+import org.picketlink.idm.model.basic.User;
+
+import javax.annotation.PostConstruct;
+import javax.ejb.Singleton;
+import javax.ejb.Startup;
+import javax.inject.Inject;
+
+/**
+ * This startup bean creates the default users, groups and roles when the application is started.
+ */
+@Singleton
+@Startup
+public class Initializer
+{
+
+ @Inject
+ private PartitionManager partitionManager;
+
+ @PostConstruct
+ public void create() {
+
+ // Create user john
+ User john = new User("john");
+ john.setEmail("john@acme.com");
+ john.setFirstName("John");
+ john.setLastName("User");
+
+ IdentityManager identityManager = this.partitionManager.createIdentityManager();
+
+ identityManager.add(john);
+ identityManager.updateCredential(john, new Password("123456"));
+
+ }
+}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/LoggedInAccessDecisionVoter.java
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/LoggedInAccessDecisionVoter.java b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/LoggedInAccessDecisionVoter.java
new file mode 100644
index 0000000..2abfeef
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/LoggedInAccessDecisionVoter.java
@@ -0,0 +1,76 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.deltaspike.example.security.requestedpage.picketlink;
+
+import org.apache.deltaspike.core.api.config.view.ViewConfig;
+import org.apache.deltaspike.core.api.config.view.metadata.ViewConfigResolver;
+import org.apache.deltaspike.security.api.authorization.AbstractAccessDecisionVoter;
+import org.apache.deltaspike.security.api.authorization.AccessDecisionVoterContext;
+import org.apache.deltaspike.security.api.authorization.SecurityViolation;
+import org.picketlink.Identity;
+
+import javax.enterprise.context.SessionScoped;
+import javax.faces.context.FacesContext;
+import javax.inject.Inject;
+import java.util.Set;
+
+@SessionScoped //or @WindowScoped
+public class LoggedInAccessDecisionVoter extends AbstractAccessDecisionVoter
+{
+
+ @Inject
+ private ViewConfigResolver viewConfigResolver;
+
+ @Inject
+ private Identity identity;
+
+ // set a default
+ private Class<? extends ViewConfig> deniedPage = Pages.Secure.Home.class;
+
+ @Override
+ protected void checkPermission(AccessDecisionVoterContext context, Set<SecurityViolation> violations)
+ {
+
+ if (identity.isLoggedIn())
+ {
+ // no violations, pass
+ }
+ else
+ {
+ violations.add(new SecurityViolation()
+ {
+ @Override
+ public String getReason()
+ {
+ return "User must be logged in to access this resource";
+ }
+ });
+
+ // remember the requested page
+ deniedPage = viewConfigResolver
+ .getViewConfigDescriptor(FacesContext.getCurrentInstance().getViewRoot().getViewId())
+ .getConfigClass();
+ }
+ }
+
+ public Class<? extends ViewConfig> getDeniedPage()
+ {
+ return deniedPage;
+ }
+}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/Pages.java
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/Pages.java b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/Pages.java
new file mode 100644
index 0000000..973968f
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/java/org/apache/deltaspike/example/security/requestedpage/picketlink/Pages.java
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.deltaspike.example.security.requestedpage.picketlink;
+
+import org.apache.deltaspike.core.api.config.view.DefaultErrorView;
+import org.apache.deltaspike.core.api.config.view.ViewConfig;
+import org.apache.deltaspike.jsf.api.config.view.Folder;
+import org.apache.deltaspike.security.api.authorization.Secured;
+
+@Folder(name = "/")
+public interface Pages
+{
+ class Login extends DefaultErrorView
+ {
+ }
+
+ @Folder(name = "/secured")
+ interface Secure
+ {
+
+ @Secured(LoggedInAccessDecisionVoter.class)
+ class Home implements ViewConfig
+ {
+ }
+
+ }
+
+}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/beans.xml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/beans.xml b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/beans.xml
new file mode 100644
index 0000000..d2acfab
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/beans.xml
@@ -0,0 +1,26 @@
+<!--
+ JBoss, Home of Professional Open Source
+ Copyright 2014, Red Hat, Inc. and/or its affiliates, and individual
+ contributors by the @authors tag. See the copyright.txt in the
+ distribution for a full listing of individual contributors.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<beans xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
+
+ <interceptors>
+ <class>org.apache.deltaspike.security.impl.extension.SecurityInterceptor</class>
+ </interceptors>
+
+</beans>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/faces-config.xml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/faces-config.xml b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/faces-config.xml
new file mode 100644
index 0000000..cce0e2f
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/faces-config.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<faces-config
+ xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_1.xsd"
+ version="2.1">
+
+</faces-config>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/web.xml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/web.xml b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/web.xml
new file mode 100644
index 0000000..23eddbc
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/WEB-INF/web.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version
+ 2.0 (the "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+ applicable law or agreed to in writing, software distributed under the
+ License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ CONDITIONS OF ANY KIND, either express or implied. See the License for
+ the specific language governing permissions and limitations under the
+ License.
+-->
+<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
+ version="3.0">
+
+ <context-param>
+ <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
+ <param-value>.xhtml</param-value>
+ </context-param>
+
+ <servlet>
+ <servlet-name>Faces Servlet</servlet-name>
+ <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>Faces Servlet</servlet-name>
+ <url-pattern>*.xhtml</url-pattern>
+ </servlet-mapping>
+
+ <welcome-file-list>
+ <welcome-file>index.html</welcome-file>
+ </welcome-file-list>
+</web-app>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/index.html
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/index.html b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/index.html
new file mode 100644
index 0000000..d252a75
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/index.html
@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+ <title>Index</title>
+</head>
+<body>
+<h1>Index</h1>
+
+<p>
+ This link points to a secured page and should redirect to login page:
+ <br>
+ <a href="secured/home.xhtml">Go Home</a>
+</p>
+</body>
+</html>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/login.xhtml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/login.xhtml b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/login.xhtml
new file mode 100644
index 0000000..ee692ee
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/login.xhtml
@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:h="http://java.sun.com/jsf/html">
+<head>
+ <title>Login</title>
+</head>
+
+<body>
+<h1>Log in</h1>
+<h:messages globalOnly="true"></h:messages>
+<h:form id="loginForm">
+ <h:outputLabel value="Username:" for="username"/><br/>
+ <h:inputText value="#{loginCredentials.userId}" id="username"/><br/><br/>
+ <h:outputLabel value="Password:" for="password"/><br/>
+ <h:inputSecret value="#{loginCredentials.password}" id="password"/><br/>
+ <h:commandButton value="Log in" action="#{identity.login()}" id="loginBtn"/>
+</h:form>
+
+<p>
+ <b>Hint:</b> log in as john / 123456
+</p>
+<br/>
+
+</body>
+
+</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/secured/home.xhtml
----------------------------------------------------------------------
diff --git a/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/secured/home.xhtml b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/secured/home.xhtml
new file mode 100644
index 0000000..29a101f
--- /dev/null
+++ b/deltaspike/examples/security-requested-page-after-login-picketlink/src/main/webapp/secured/home.xhtml
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <title>Home Page</title>
+</head>
+
+<body>
+<h1>Hello!</h1>
+
+<p>Welcome Home</p>
+
+</body>
+
+</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/bean-validation.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/bean-validation.adoc b/documentation/src/main/asciidoc/bean-validation.adoc
index f471dbe..1ffccc6 100644
--- a/documentation/src/main/asciidoc/bean-validation.adoc
+++ b/documentation/src/main/asciidoc/bean-validation.adoc
@@ -8,7 +8,7 @@
== Overview
The Bean Validation module provides CDI integration for bean validation. It enables the creation of CDI-aware `ConstraintValidator` methods that can use business objects (EJBs, ManagedBeans) to support validation needs.
-== Configure Your Projects
+== Project Setup
The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
=== Declare Bean Validation Module Dependencies
@@ -24,15 +24,13 @@ Add the Bean Validation module to the list of dependencies in the project `pom.x
</dependency>
----
-== Use the Module Features
-
-=== Scoping
+== Scoping
A `ConstraintValidator` inherits the scope defined in the bean class.
NOTE: A `ConstraintValidator` may be invoked by multiple threads. For this reason, you should consider using at least `RequestScoped` validators.
-=== Code Requirements
+== Code Requirements
There are no compile dependencies to use the Bean Validation module. You
simply need to override the factory. Then you can build your `ConstraintValidator` based on CDI programming rules.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/container-control.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/container-control.adoc b/documentation/src/main/asciidoc/container-control.adoc
index 3b31c21..fa5ac18 100644
--- a/documentation/src/main/asciidoc/container-control.adoc
+++ b/documentation/src/main/asciidoc/container-control.adoc
@@ -5,7 +5,7 @@
== Overview
The Container Control module provides CDI container booting and shutdown, crucial for CDI use in Java SE6+ environments, and associated context lifecycle management. The module abstracts individual CDI container implementations, ensuring projects are container-independent.
-== Configure Your Projects
+== Project Setup
The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
=== Enable CDI For Your Java Environment
@@ -24,9 +24,7 @@ Add the Container Control module to the list of dependencies in the project `pom
</dependency>
----
-== Use the Module Features
-
-=== Start the CDI Container from Your Project
+== Start the CDI Container from Your Project
To start a CDI container in your application, you must instantiate a `CdiContainer` object and call the `#boot` method. When `#boot` is called, the `CdiContainer` scans CDI-enabled
archives for beans and CDI extensions. Before the application exits, `#shutdown` must be called to correctly destroy all beans. An example is given in the code snippet here.
@@ -81,17 +79,17 @@ To resolve project beans, you can use the DeltaSpike `BeanProvider` class. Wheth
EchoService echoService = BeanProvider.getContextualReference(EchoService.class, false);
----
-=== CdiContainer
+== CdiContainer
The `CdiContainer` interface provides booting and shutdown of the CDI containers from deployed applications, with `CdiContainerLoader` a simple factory providing access to the underlying `CdiContainer` implementation.
This is useful to Java SE6+ applications in which a standalone CDI implementation must be provided and booted and shutdown by the application. Booting and shutdown of the CDI container for Java EE and servlet containers is managed by the servlet container integration.
For instructions and examples on using this feature in your projects, see <<cdiimp#javase6,Enable CDI For Your Java Environment: Java SE6+>>.
-=== ContextControl Usage
+== ContextControl Usage
The `ContextControl` interface provides life-cycle control of the CDI container built-in contexts. This includes starting and stoping built-in standard contexts like `@RequestScoped`, `@ConversationScoped`, and `@SessionScoped`. It is provided as an `@Dependent` bean and can be injected in the classic CDI way. This feature can be used and is helpful in all Java environments, including Java SE, as illustrated here.
-=== Procedure for builing Uber jar
+== Procedure for building an uber jar
Uber jar or executable jar can created by using the maven shade plugin. Some things you needs to be aware of when you use it.
* Multiple `beans.xml` and `javax.enterprise.inject.spi.Extension` files needs to be merged into the final jar using a transformer.
@@ -102,7 +100,7 @@ Uber jar or executable jar can created by using the maven shade plugin. Some thi
* The _asm:asm:3.3.1_ transitive dependency of OpenWebBeans isn't properly included in the Uber jar. Add it as a project dependency if you use OWB. (Only needed for OWB 1.1.8 !)
* Some frameworks, like logging frameworks, aren't CDI compatible. So you need to exclude them from scanning. Use for example the `scan` feature of Weld to define which packages needs to be excluded.
-==== Restart the RequestContext in Unit Tests
+=== Restart the RequestContext in Unit Tests
In unit testing it can be necessary to test with attached and also with
detached JPA entities. A very common approach for JPA is the
http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Server/1.0/html/Hibernate_Entity_Manager_Reference_Guide/transactions.html[entitymanager-per-request
@@ -132,7 +130,7 @@ public void testMyBusinessLogic()
}
---------------------------------------------------------------------------------------
-==== Attach a RequestContext to a New Thread in EE
+=== Attach a RequestContext to a New Thread in EE
Accessing the `@RequestScoped` bean in a new thread will result in a
`ContextNotActiveException`. The RequestContext usually gets started
for a particular thread via a simple `ServletRequestListener`. So "no
@@ -165,7 +163,7 @@ public class CdiJob implements org.quartz.Job
}
---------------------------------------------------------------------------------------------
-=== Embedded Servlet Support
+== Embedded Servlet Support
From DeltaSpike 1.0.2, you can use DeltaSpike to power embedded Servlet
runtimes. This work is done via Servlet Listeners. The configuration is
specific to each container, below are some examples.
@@ -188,7 +186,7 @@ cdiContainer.boot();
cdiContainer.getContextControl().startContexts();
-----------------------------------------------------------------
-==== Jetty
+=== Jetty
For Jetty, you need to add an `EventListener` which will be your
`CdiServletRequestListener`. The object must be instantiated. This must
@@ -207,7 +205,7 @@ context.addServlet(new ServletHolder(new YourServlet()),"/*");
server.start();
------------------------------------------------------------------------------------------
-==== Undertow
+=== Undertow
For Undertow, you register the `CdiServletRequestListener` via
`ListenerInfo` by passing in the class to their builders. Then you add
@@ -232,7 +230,7 @@ Undertow server = Undertow.builder()
server.start();
--------------------------------------------------------------------------------------------------------
-==== Tomcat
+=== Tomcat
For Tomcat, you need to register the `CdiServletContextListener` instead
of the `CdiServletRequestListener`. It is added as an
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/data.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/data.adoc b/documentation/src/main/asciidoc/data.adoc
index 4786dab..e0f3ec4 100644
--- a/documentation/src/main/asciidoc/data.adoc
+++ b/documentation/src/main/asciidoc/data.adoc
@@ -42,7 +42,7 @@ extension. A client can declare a dependency to the interface only. The
details on how to use those features are outlines in the following
chapters.
-== Configure Your Projects
+== Project Setup
The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
@@ -126,14 +126,12 @@ configure the `TransactionStrategy` your repositories use. Adapt your
</beans>
----
-== Use the Module Features
-
IMPORTANT: Using the DeltaSpike Data module in an EAR deployment is currently restricted to
annotation-based entities.
-=== Core Concepts
+== Core Concepts
-==== Repositories
+=== Repositories
With the DeltaSpike Data module, it is possible to make a repository out
of basically any abstract class or interface (using a concrete class
@@ -162,7 +160,7 @@ classes or interfaces this is the only way to tell the framework what
entity the repository relates to. In order to simplify this, DeltaSpike
Data provides several base types.
-===== The `EntityRepository` Interface
+==== The `EntityRepository` Interface
Although mainly intended to hold complex query logic, working with both
a repository and an `EntityManager` in the service layer might
@@ -245,7 +243,7 @@ public abstract class PersonRepository extends AbstractEntityRepository<Person,
}
-------------------------------------------------------------------------------------
-==== Deactivating Repositories
+=== Deactivating Repositories
Repositories can be deactivated creating a <<spi.adoc#_classdeactivator,ClassDeactivator>>.
@@ -266,7 +264,7 @@ public interface PersonRepository implements Deactivatable{
}
----------------------------------------
-==== Using Multiple `EntityManager`
+=== Using Multiple `EntityManager`
While most applications will run just fine with a single
`EntityManager`, there might be setups where multiple data sources are
@@ -299,7 +297,7 @@ possible to create something like a base `CrmRepository` interface with
the `@EntityManagerConfig` and then extending / implementing this
interface.
-==== Other `EntityManager` Methods
+=== Other `EntityManager` Methods
While the `EntityRepository` methods should cover most interactions
normally done with an `EntityManager`, for some specific cases it might
@@ -317,14 +315,14 @@ public interface PersonRepository extends EntityRepository<Person, Long>, Entity
}
-------------------------------------------------------------------------------------------------------
-=== Query Method Expressions
+== Query Method Expressions
Good naming is a difficult aspects in software engineering. A good
method name usually makes comments unnecessary and states exactly what
the method does. And with method expressions, the method name is
actually the implementation!
-==== Using Method Expressions
+=== Using Method Expressions
Let's start by looking at a (simplified for readability) example:
@@ -395,7 +393,7 @@ Note that DeltaSpike will validate those expressions during startup, so
you will notice early in case you have a typo in those expressions.
-==== Query Ordering
+=== Query Ordering
Beside comparators it is also possible to sort queries by using the
`OrderBy` keyword, followed by the attribute name and the direction
@@ -412,7 +410,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
------------------------------------------------------------------------------
-==== Nested Properties
+=== Nested Properties
To create a comparison on a nested property, the traversal parts can be
separated by a `_`:
@@ -428,7 +426,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
------------------------------------------------------------------------
-==== Query Options
+=== Query Options
DeltaSpike supports query options on method expressions. If you want to
@@ -446,7 +444,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
-----------------------------------------------------------------------------------------------
-==== Method Prefix
+=== Method Prefix
In case the `findBy` prefix does not comply with your team conventions,
this can be adapted:
@@ -462,7 +460,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
--------------------------------------------------------------------------------------------------
-=== Query Annotations
+== Query Annotations
While method expressions are fine for simple queries, they will often
reach their limit once things get slightly more complex. Another aspect
@@ -472,7 +470,7 @@ cases, the DeltaSpike Data module supports also annotating methods for
more control on the generated query.
-==== Using Query Annotations
+=== Using Query Annotations
The simples way to define a specific query is by annotating a method and
providing the JPQL query string which has to be executed. In code, this
@@ -569,7 +567,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
------------------------------------------------------------------------------------
-==== Annotation Options
+=== Annotation Options
Beside providing a query string or reference, the `@Query` annotation
provides also two more attributes:
@@ -595,7 +593,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
Note that these options can also be applied to method expressions.
-==== Query Options
+=== Query Options
All the query options you have seen so far are more or less static. But
sometimes you might want to apply certain query options dynamically. For
@@ -635,7 +633,7 @@ supported for Hibernate, EclipseLink and OpenJPA.
Note that the `QueryResult` return type can also be used with method
expressions.
-==== Pagination
+=== Pagination
We introduced the `QueryResult` type in the last chapter, which can also
be used for pagination:
@@ -655,7 +653,7 @@ QueryResult<Person> paged = personRepository.findByAge(age)
int totalPages = paged.countPages();
-----------------------------------------------------------
-==== Bulk Operations
+=== Bulk Operations
While reading entities and updating them one by one might be fine for
many use cases, applying bulk updates or deletes is also a common usage
@@ -678,7 +676,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
Bulk operation query methods can either return void or int, which counts
the number of entities affected by the bulk operation.
-==== Optional Query Results
+=== Optional Query Results
The JPA spec requires to throw exceptions in case the
`getSingleResult()` method does either return no or more than one
@@ -690,7 +688,7 @@ DeltaSpike Data gives the option to change this to the way it makes most
sense for the current usecase. While the default behavior is still fully
aligned with JPA, it is also possible to request optional query results.
-==== Zero or One Result
+=== Zero or One Result
With this option, the query returns `null` instead of throwing a
`NoResultException` when there is no result returned. It is usable with
@@ -717,7 +715,7 @@ with the `SingleResultType.OPTIONAL` enum.
In case the query returns more than one result, a
`NonUniqueResultException` is still thrown.
-==== Any Result
+=== Any Result
If the caller does not really mind what kind if result is returned, it is
also possible to request any result from the query. If there is no
@@ -745,7 +743,7 @@ annotations, the `singleResult` attribute can be overridden with the
This option will not throw an exception.
-=== Transactions
+== Transactions
If you call any method expression, `@Query`-annotated method or a method
from the `EntityRepository`, the repository will figure out if a
@@ -787,9 +785,9 @@ Repositories can then implement the `TxRepository` interface and call
their queries in the `transactional` method (where the callback
implementation can be, for example, in an anonymous class).
-=== Extensions
+== Extensions
-==== Query Delegates
+=== Query Delegates
While repositories defines several base interfaces, there might still be
the odd convenience method that is missing. This is actually intentional
@@ -815,7 +813,7 @@ public interface PersonRepository extends QueryDslSupport
}
---------------------------------------------------------
-==== Implementing the Query Delegate
+=== Implementing the Query Delegate
The first step is to define an interface which contains the extra
methods for your repositories (as shown above):
@@ -858,7 +856,7 @@ Note that, if you define multiple extensions with equivalent method
signatures, there is no specific order in which the implementation is
selected.
-=== Mapping
+== Mapping
While repositories are primarily intended to work with Entities, it
might be preferable in some cases to have an additional mapping layer on
@@ -948,7 +946,7 @@ is mandatory. Also it is up to the mapper to convert parameters
correctly (in this example, a conversion from a `PersonDto` parameter to
`Person` entity and from `PersonId` to `Long` is necessary).
-==== Simple Mappings
+=== Simple Mappings
In many cases it is just required to map a DTO object back and forth. For
this case, the `SimpleQueryInOutMapperBase` class can be subclassed,
@@ -988,7 +986,7 @@ created. In any case, there is no need to map the primary key to the
entity (it either does not exist or is already populated for an existing
entity).
-=== JPA Criteria API Support
+== JPA Criteria API Support
Beside automatic query generation, the DeltaSpike Data module also
provides a DSL-like API to create JPA 2 Criteria queries. It takes
@@ -1006,7 +1004,7 @@ strongest point is certainly its type safety - which comes at the cost
of readability. We're trying to provide a middle way here. A less
powerful API, but still type safe and readable.
-==== API Usage
+=== API Usage
The API is centered around the Criteria class and is targeted to provide
a fluent interface to write criteria queries:
@@ -1065,7 +1063,7 @@ Once all comparators and query options are applied, the `createQuery()`
method is called. This creates a JPA TypedQuery object for the
repository entity. If required, further processing can be applied here.
-==== Joins
+=== Joins
For simple cases, restricting on the repository entity only works out
fine, but once the Data model gets more complicated, the query will have
@@ -1112,7 +1110,7 @@ public abstract class PersonRepository extends AbstractEntityRepository<Person,
}
-------------------------------------------------------------------------------------
-==== Boolean Operators
+=== Boolean Operators
By default, all query operators are concatenated as an and conjunction
to the query. The DeltaSpike criteria API also allows to add groups of
@@ -1140,7 +1138,7 @@ public abstract class PersonRepository extends AbstractEntityRepository<Person,
}
-------------------------------------------------------------------------------------
-==== Selections
+=== Selections
It might not always be appropriate to retrieve full entities - you might
also be interested in scalar values or by modified entity attributes.
@@ -1194,7 +1192,7 @@ selection clause:
|===
-=== Auditing
+== Auditing
A common requirement for entities is tracking what is being done with
them. DeltaSpike provides a convenient way to support this requirement.
@@ -1202,7 +1200,7 @@ them. DeltaSpike provides a convenient way to support this requirement.
NOTE: DeltaSpike does not support creating revisions of entities. If this is a
requirement for your audits, have a look at Hibernate Envers.
-==== Activating Auditing
+=== Activating Auditing
DeltaSpike uses an entity listener to update auditing data before
entities get created or update. The entity listener must be activated
@@ -1244,12 +1242,12 @@ Note that for this variant, you need a compile dependency on the impl
module. Alternatively, also the per entity listener can be configured by
XML.
-==== Using Auditing Annotations
+=== Using Auditing Annotations
All that has to be done now is annotating the entity properties which
are used to audit the entity.
-===== Updating Timestamps
+==== Updating Timestamps
To keep track on creation and modification times, following annotations
can be used:
@@ -1282,7 +1280,7 @@ the annotation can be customized:
@ModifiedOn(setOnCreate=true)
-----------------------------
-===== Who's Changing My Entities?
+==== Who's Changing My Entities?
Beside keeping track of when a change has happened, it is also often
critical to track who's responsible for the change. Annotate a user
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/jpa.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/jpa.adoc b/documentation/src/main/asciidoc/jpa.adoc
index 5ba3f6a..f7d8943 100644
--- a/documentation/src/main/asciidoc/jpa.adoc
+++ b/documentation/src/main/asciidoc/jpa.adoc
@@ -8,7 +8,7 @@
== Overview
The JPA module provides a transactional context and scope, enabling execution of methods within transactions.
-== Configure Your Projects
+== Project Setup
The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
=== 1. Declare JPA Module Dependencies
@@ -44,9 +44,7 @@ For CDI 1.0 (or DeltaSpike v1.1.0 and earlier together with CDI 1.1+), you must
</beans>
----
-== Use the Module Features
-
-=== @Transactional
+== @Transactional
This annotation is an alternative to transactional EJBs which allows to
execute a method within a transaction. Before it is possible to start
@@ -337,7 +335,7 @@ a different `EntityManager`. So it is possible to catch an exception in
`FirstLevelTransactionBean`, for example, to try an optional path instead of an
immediate rollback.
-=== @TransactionScoped
+== @TransactionScoped
`@Transactional` also starts a context which is available as long as the
transaction started by `@Transactional`. Besides other beans you can use
@@ -373,7 +371,7 @@ public class EntityManagerProducer
}
----------------------------------------------------------------------------
-=== Extended Persistence Contexts
+== Extended Persistence Contexts
Frameworks like MyFaces Orchestra provide a feature which allows keeping
an `EntityManager` across multiple requests. That means it is not
@@ -493,7 +491,7 @@ to merge detached entities automatically if those entities get
serialized as well. However, as mentioned before *we do not recommend*
such an approach.
-=== JTA Support
+== JTA Support
By default the transaction-type used by `@Transactional` is
`RESOURCE_LOCAL`. If you configure `transaction-type="JTA"` in the