You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by cm...@apache.org on 2013/01/07 19:46:49 UTC
svn commit: r1429950 - in
/incubator/deltaspike/site/trunk/content/deltaspike:
container-control.mdtext core.mdtext documentation.mdtext jpa.mdtext
resources/css/bootstrap.css security.mdtext
Author: cmoulliard
Date: Mon Jan 7 18:46:49 2013
New Revision: 1429950
URL: http://svn.apache.org/viewvc?rev=1429950&view=rev
Log:
Improve documentation web page, add a container-control page and fix code hilite issues
Added:
incubator/deltaspike/site/trunk/content/deltaspike/container-control.mdtext
Modified:
incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext
incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext
incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext
incubator/deltaspike/site/trunk/content/deltaspike/resources/css/bootstrap.css
incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext
Added: incubator/deltaspike/site/trunk/content/deltaspike/container-control.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/container-control.mdtext?rev=1429950&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/container-control.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/container-control.mdtext Mon Jan 7 18:46:49 2013
@@ -0,0 +1,90 @@
+Title: Container & Control
+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.
+
+[TOC]
+
+***
+
+# Introduction
+
+There are basically two parts:
+
+ - The **CdiContainer** interface allows to boot and shutdown the CDI container in SE applications.
+ - The **ContextControl** interface allows to control the life-cycle of the built-in contexts of the CDI container.
+
+## CdiContainer
+
+See the Java SE part [above](#start-a-cdi-container-using-java-se).
+
+## ContextControl usage
+
+The `ContextControl` interface allows you to start and stop built-in standard Contexts like `@RequestScoped`, `@ConversationScoped`, `@SessionScoped`, etc. It is provided as `@Dependent` bean and can get injected in the classic CDI way. This is not only usable in Java SE projects but also very helpful in Servlets and Java EE containers.
+
+**Restarting 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 [entitymanager-per-request approach](http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Server/1.0/html/Hibernate_Entity_Manager_Reference_Guide/transactions.html) and thus have a producer method which creates a @RequestScoped EntityManager. Since a single unit test is usually treated as one ârequestâ a problem arises detaching entities.
+
+Using ContextControl to detach entities:
+
+ :::java
+ @Test
+ public void testMyBusinessLogic()
+ {
+ doSomeJpaStuff()
+ MyEntity me = em.find(...);
+
+ ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
+
+ //stopping the request context will dispose the @RequestScoped EntityManager
+ ctxCtrl.stopContext(RequestScoped.class);
+
+ // and now immediately restart the context again
+ ctxCtrl.startContext(RequestScoped.class);
+
+ // the entity 'em' is now in a detached state!
+ doSomeStuffWithTheDetachedEntity(em);
+ }
+
+Attaching a Request Context to a new thread in EE
+
+Accessing the `@RequestScoped` bean in a new thread will result in a `ContextNotActiveException`. The request-context usually gets started for a particular thread via a simple `ServletRequestListener`. So "no servlet-request" means that there is no Servlet-Context for the current (/new) Thread.
+You might face such issues, if you would like to reuse business services in e.g. a Quartz Job.
+
+Controlling the request-context for a Quartz-Job:
+
+ :::java
+ public class CdiJob implements org.quartz.Job
+ {
+ public void execute(JobExecutionContext context) throws JobExecutionException
+ {
+ ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
+
+ //this will implicitly bind a new RequestContext to the current thread
+ ctxCtrl.startContext(RequestScoped.class);
+
+ try
+ {
+ doYourWork();
+ }
+ finally
+ {
+ //stop the RequestContext to ensure that all request-scoped beans get cleaned up.
+ ctxCtrl.stopContext(RequestScoped.class);
+ }
+ }
+ }
\ No newline at end of file
Modified: incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext?rev=1429950&r1=1429949&r2=1429950&view=diff
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext (original)
+++ incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext Mon Jan 7 18:46:49 2013
@@ -16,6 +16,10 @@ Notice: Licensed to the Apache Softwa
specific language governing permissions and limitations
under the License.
+[TOC]
+
+***
+
# Core - API
## BeanProvider
@@ -26,18 +30,21 @@ The following example shows a simple loo
Resolving a simple contextual instance:
+ :::java
MyBean myBean = BeanProvider.getContextualReference(MyBean.class, false);
Pass `true` as second argument, if you look for an implementation of the given interface and an implementation isn't required or it isn't required that there is an instance with the given qualifier (see the qualifier example for further details).
Resolving an optional contextual instance:
+ :::java
MyServiceInterface optionalService = BeanProvider.getContextualReference(MyServiceInterface.class, true);
Optionally you can provide a qualifier for the contextual instance in question. CDI qualifiers are annotations, therefore you need to implement a corresponding literal for providing an instance.
Literal implementation for '@MyQualifier':
+ :::java
import javax.enterprise.util.AnnotationLiteral;
//...
@@ -49,34 +56,40 @@ The following example will return a cont
Resolving a simple contextual instance with qualifier:
+ :::java
MyBean myBean = BeanProvider.getContextualReference(MyBean.class, false, new MyQualifierLiteral());
The `@Named` qualifier has a special role and allows to specify a string based name (e.g. for referencing CDI beans in EL-expressions). However, the following examples show how to do a manual lookup by name.
Resolving a simple contextual instance by name:
+ :::java
Object myBean = BeanProvider.getContextualReference("myBean", false);
Resolving a simple contextual instance by name and expected type:
+ :::java
MyBean myBean = BeanProvider.getContextualReference("myBean", false, MyBean.class);
Sometimes it's essential to resolve all contextual instances which implement e.g. an interface or all beans with the same type but a different qualifier. The following example shows how to do such a lookup which returns all contextual instances (independent of the scope -> also dependent scoped instances).
Resolving all contextual instances of a given type:
+ :::java
List<MyServiceInterface> myServiceList = BeanProvider.getContextualReferences(MyServiceInterface.class, false);
Since dependent scoped beans have a special role in CDI (you have to destroy them manually - esp. if you get them via a manual lookup), you can also call the previous util method with an additional parameter to filter dependent scoped instances.
Resolving all contextual instances of a given type without dependent scoped instances:
+ :::java
List<MyServiceInterface> myServiceList = BeanProvider.getContextualReferences(MyServiceInterface.class, false, false);
Furthermore, it's possible to trigger the injection of fields of any given instance, if it wasn't done by the container (e.g. because the class is in a jar-file without beans.xml) and `@Inject` is used for 1-n fields.
Manually inject fields:
+ :::java
BeanProvider.injectFields(myObject);
## BeanManagerProvider
@@ -87,13 +100,12 @@ If a simple but manual bean-lookup is ne
Resolving the Bean-Manager:
+ :::java
//in most cases the following works without problems:
-
@Inject
private BeanManager beanManager;
- //use:
-
+ //use
BeanManager beanManager = BeanManagerProvider.getInstance().getBeanManager();
//if CDI based injection is not available.
@@ -115,6 +127,7 @@ The core provides a pluggable and type-s
Resolving and using the Project-Stage:
+ :::java
@Inject
private ProjectStage projectStage;
@@ -131,6 +144,7 @@ It's required to provide a `public stati
ProjectStageHolder for custom project stage implementations:
+ :::java
public class CustomProjectStageHolder implements ProjectStageHolder
{
public static final class CustomProjectStage extends ProjectStage
@@ -145,6 +159,7 @@ Configure your custom `ProjectStageHolde
Usage of a custom project stage:
+ :::java
ProjectStage customProjectStage;
customProjectStage = ProjectStage.valueOf("CustomProjectStage");
//or
@@ -165,6 +180,7 @@ The method `ConfigResolver#getPropertyVa
Simple lookup in the low-level config:
+ :::java
ConfigResolver.getPropertyValue("myKey");
### PropertyFileConfig
@@ -224,6 +240,7 @@ With `@Exclude` it's possible to annotat
Excluding a bean in any case:
+ :::java
@Exclude
public class NoBean
{
@@ -231,6 +248,7 @@ Excluding a bean in any case:
Excluding a bean in case of project-stage development:
+ :::java
@Exclude(ifProjectStage = ProjectStage.Development.class)
public class MyBean
{
@@ -238,6 +256,7 @@ Excluding a bean in case of project-stag
Excluding a bean if the project-stage is different from development:
+ :::java
@Exclude(exceptIfProjectStage = ProjectStage.Development.class)
public class MyDevBean
{
@@ -247,6 +266,7 @@ The following usage allows to exclude a
Excluding a bean based on an expression which eval. to true:
+ :::java
@Exclude(onExpression = "db==prodDB")
public class DevDbBean
{
@@ -256,6 +276,7 @@ By default a simple syntax is supported
Excluding a bean based on a custom expression:
+ :::java
@Exclude(onExpression = "db eq prodDB", interpretedBy = SimpleExpressionInterpreter.class)
public class DevDbBean
{
@@ -281,6 +302,7 @@ This config entry won't be changed e.g.
Excluding an alternative implementation if the project-stage is different from development:
+ :::java
@Exclude(exceptIfProjectStage = ProjectStage.Development.class)
@Alternative
public class MyDevBean
@@ -292,6 +314,7 @@ Excluding an alternative implementation
Per default only a very simple and limited syntax is supported. In real projects there are usually quite concrete requirements. Since it would be very complex to support most of them, it's easier for users to implement an optimized syntax.
For such cases a custom ExpressionInterpreter is needed:
+ :::java
@Alternative
@Exclude(onExpression = "environment!=HSQL", interpretedBy = ConfigAwareExpressionInterpreter.class)
public class DevDbBean implements DbBean
@@ -330,9 +353,123 @@ TODO (Overview)
TODO
-## I18n
+## Messages & I18n
-TODO
+The following implementation is the minimal effort to use type-safe messages (which are hardcoded in this case).
+
+**Simple type-safe message**
+
+ :::java
+ @MessageBundle
+ public interface SimpleMessage
+ {
+ @MessageTemplate("Welcome to DeltaSpike")
+ String welcomeToDeltaSpike();
+ }
+
+The following implementation uses the key `welcome_to_deltaspike` to do a lookup in the default message bundle. The default bundle has the same name as the interface (but .properties instead of .java (/.class) as file extension).
+
+**Internationalized type-safe message**
+
+ :::java
+ @MessageBundle
+ public interface SimpleMessage
+ {
+ @MessageTemplate("{welcome_to_deltaspike}")
+ String welcomeToDeltaSpike();
+ }
+
+ org.apache.deltaspike.example.message.SimpleMessage
+
+ ->
+
+ org/apache/deltaspike/example/message/SimpleMessage.properties
+ org/apache/deltaspike/example/message/SimpleMessage_en.properties
+ org/apache/deltaspike/example/message/SimpleMessage_de.properties
+ ...
+
+ //content (as usual in message bundle files:
+ welcome_to_deltaspike=Welcome to DeltaSpike
+
+The following implementation uses the key `welcome_to_deltaspike` to do a lookup in a custom message bundle known by `CustomMessageResolver`.
+
+**Internationalized type-safe message**
+
+ :::java
+ @MessageBundle
+ @MessageContextConfig(messageResolver = CustomMessageResolver.class)
+ public interface SimpleMessage
+ {
+ @MessageTemplate("{welcome_to_deltaspike}")
+ String welcomeToDeltaSpike();
+ }
+
+`@MessageContextConfig` allows to provide a custom `MessageResolver`, `MessageInterpolator` and `LocaleResolver`.
+
+The following implementation shows the usage of an internationalized simple type-safe message.
+
+**Internationalized type-safe message with parameter/s**
+
+ :::java
+ @MessageBundle
+ @MessageContextConfig(messageInterpolator = CustomMessageInterpolator.class)
+ public interface SimpleMessage
+ {
+ //in the message bundle: welcome_to=Welcome to %s
+
+ @MessageTemplate("{welcome_to}")
+ String welcomeTo(String name);
+ }
+
+ //...
+ public class MyBean
+ {
+ @Inject
+ private SimpleMessage messages;
+
+ public String welcomeToDeltaSpike
+ {
+ return this.messages.welcomeTo("DeltaSpike");
+ }
+ }
+
+## Dynamic Message Builder
+
+### Creating message instances
+
+The following implementation creates an instance of `Message` for the key `hello`. The final text will be resolved and interpolated lazily. Later on it might be supported to provide a different `MessageContext` via `#toString(MessageContext)` like it is in MyFaces CODI right now.
+
+[TODO]
+
+### Customizing the message context
+
+#### MessageResolver
+
+A message-resolver is responsible for creating the message-text based on the message-descriptor (key or inline-text), the current locale (and in some cases the message-payload).
+(The supported format e.g. if it's required to escape a key, if inline-text is supported,... depends on the concrete implementation.)
+In case of a message-key, the message-resolver has to transform it to the message-text by looking it up in a message source like a resource-bundle.
+
+**Configuration of a message-resolver**
+
+[TODO]
+
+The result of a `MessageResolver` is the message-text. The text might contain placeholders which are processed by a `MessageInterpolator`
+
+#### MessageInterpolator
+
+A `MessageInterpolator` replaces the placeholders in a message-text with the arguments of the message.
+
+**Configuration of a message-interpolator**
+
+[TODO]
+
+#### LocaleResolver
+
+A locale resolver provides the current locale. The locale is e.g. used to by a `MessageResolver` to choose the correct language for the message-text.
+
+**Configuration of a locale-resolver**
+
+[TODO]
## Exception Control
@@ -372,6 +509,7 @@ used in your own try/catch blocks. It's
examine a sample that might exist inside of a simple business logic lookup into
an inventory database:
+ :::java
public class InventoryActions {
@PersistenceContext private EntityManager em;
@Inject private Event<ExceptionToCatchEvent> catchEvent;
@@ -442,6 +580,7 @@ handler methods.
Let's designate a CDI bean as an exception handler by annotating it with
`@ExceptionHandler`.
+ :::java
@ExceptionHandler
public class MyHandlers {}
@@ -459,6 +598,7 @@ that DeltaSpike processes and prints the
(`Throwable` is the base exception type in Java and thus represents all
exceptions).
+ :::java
@ExceptionHandler
public class MyHandlers
{
@@ -509,6 +649,7 @@ handlers are called.
Let's take a look at more sophisticated example that uses all the features of
handlers to log all exceptions.
+ :::java
@ExceptionHandler
public class MyHandlers
{
@@ -603,6 +744,7 @@ the same type with the same ordinal, the
Let's define two handlers with different ordinals:
+ :::java
void handleIOExceptionFirst(@Handles(ordinal = 100) ExceptionEvent<IOException> evt)
{
System.out.println("Invoked first");
Modified: incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext?rev=1429950&r1=1429949&r2=1429950&view=diff
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext (original)
+++ incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext Mon Jan 7 18:46:49 2013
@@ -20,18 +20,37 @@ Notice: Licensed to the Apache Softwa
***
-# With Java-EE6+
+# Introduction
-If you are using DeltaSpike in a Java-EE6 environment, you don't need to configure a CDI implementation explicitly because it's shipped with the container.
+Apache DeltaSpike project has been created to support the development of portable CDI extensions that provide useful features for Java applications
+not provided out of the box by the CDI spec (Security, JPA, ...). CDI extensions created by the DeltaSpike community are packaged as modules.
-# With Java-EE5 or Servlet Containers
+The goal of the project is also to provide useful classes to :
-Java-EE5 application servers as well as pure servlet containers like Apache Tomcat don't provide a CDI implementation out-of-the-box. So don't forget to setup the CDI implementation of your choice.
+ * Boot CDI Container (Weld, OpenWebbeans, OpenEJB) for Java SE,
+ * Stage a project,
+ * Provide new scopes (Window Scope, ...),
+ * Manage messages and configurations
+
+The project is currently tested on different CDI implementations like Apache OpenWebBeans and JBoss Weld, and also on different Java Web containers like Apache TomEE or JavaEE, JBoss-AS7, Oracle GlassFish 3.1+, Oracle Weblogic Server 12c.
+
+[TODO] Define what portable means like also CDI extension and refers to documentation links
+
+# Getting Started
+
+A DeltaSpike project can be designed using or not Apache Maven and consists in a collection of jar files. Depending on your needs, you will package DeltaSpike core jar (api and impl) files or extend
+the list with DeltaSpike modules. DeltaSpike Api and Impl are mandatory and provide code required to benefits of portable CDI extensions or useful features
+created.
+
+Remark : For Java SE, an additional step is required as you have to select the CDI implementation of your choice to boot a CDI container.
+
+[TODO] Add a section or remark to explain how to package & deploy DeltaSpike in an OSGI environment (Apache Felix, Apache Karaf, Apache ServiceMix)
+
+## Project Configuration without Maven
-# Project-Configuration - Getting Started (without Maven)
You can manually download all JARs described above from the maven repository or you get [the source-code](source.html) and [build](build.html) DeltaSpike manually.
-# Project-Configuration (with Maven)
+## Project Configuration with Maven
**Hint:**
In the listings below replace the placeholders for the version with the version of your choice or use:
@@ -40,7 +59,7 @@ In the listings below replace the placeh
<deltaspike.version>incubating-0.4-SNAPSHOT</deltaspike.version>
</properties>
-## Configuration of DeltaSpike-Core
+### Configuration of DeltaSpike Core
<dependency>
<groupId>org.apache.deltaspike.core</groupId>
@@ -56,9 +75,9 @@ In the listings below replace the placeh
<scope>runtime</scope>
</dependency>
-## Configuration of DeltaSpike-Modules
+### Configuration of DeltaSpike Modules
-### Security Module
+#### Security Module
<dependency>
<groupId>org.apache.deltaspike.modules</groupId>
@@ -74,7 +93,7 @@ In the listings below replace the placeh
<scope>runtime</scope>
</dependency>
-### JPA Module
+#### JPA Module
<dependency>
<groupId>org.apache.deltaspike.modules</groupId>
@@ -90,7 +109,7 @@ In the listings below replace the placeh
<scope>runtime</scope>
</dependency>
-### JSF Module
+#### JSF Module
<dependency>
<groupId>org.apache.deltaspike.modules</groupId>
@@ -106,10 +125,11 @@ In the listings below replace the placeh
<scope>runtime</scope>
</dependency>
+### With Java SE
-# With Java-SE
-
-Java-SE doesn't provide a CDI implementation out-of-the-box. So don't forget to add the CDI implementation of your choice.
+To use DeltaSpike with Java SE, we must provide additional jars file corresponding to the DeltaSpike CDI Controller API
+and its implementation. The Controller uses Java Services to resolve the CDI container ([JBoss Weld](http://docs.jboss.org/weld/reference/1.1.5.Final/en-US/html/), [Apache OpenWebbeans](http://openwebbeans.apache.org) (and [Apache OpenEJB](http://openejb.apache.org))) and
+implementation contains the code to manage the [CDI container and contexts](#container-control-optional).
**Hint:**
In the listings below replace the placeholders for the version with the version of your choice or use:
@@ -120,7 +140,7 @@ In the listings below replace the placeh
<weld.version>1.1.9.Final</weld.version>
</properties>
-## Add the DeltaSpike Container-Ctrl API
+#### Add the DeltaSpike Container Ctrl API
<dependency>
<groupId>org.apache.deltaspike.cdictrl</groupId>
@@ -129,7 +149,7 @@ In the listings below replace the placeh
<scope>compile</scope>
</dependency>
-## Add a CDI container + Container-Ctrl Impl
+#### Add a CDI container + Container Ctrl Impl
### ... for Apache OpenWebBeans
@@ -170,17 +190,37 @@ In the listings below replace the placeh
<scope>runtime</scope>
</dependency>
-## Start the CDI container
-DeltaSpike allows you to control a CDI container via a generic API and special support modules for
-[JBoss Weld](http://docs.jboss.org/weld/reference/1.1.5.Final/en-US/html/), [Apache OpenWebbeans](http://openwebbeans.apache.org) (and [Apache OpenEJB](http://openejb.apache.org)).
+# Deployment mode
+
+DeltaSpike can be deployed in different Java environments. Depending which Java container and release you are using, the procedure which is different
+is explained here after.
+
+## With Java EE6+
-To bootstrap a CDI container in your Java application, you just need to instantiate the `CdiContainer` and call the `#boot` method.
+If you are using DeltaSpike in a Java EE6 environment, you don't need to configure a CDI implementation explicitly because it's shipped with the container.
+
+## With Java EE5 or Servlet Containers
+
+Java EE5 application servers as well as pure servlet containers like Apache Tomcat / Eclipse Jetty don't provide a CDI implementation out-of-the-box.
+So don't forget to setup the CDI implementation of your choice.
+
+## Standard Java SE6+
+
+If you are only using a JDK and runs Java in a standalone or standard mode (Java SE), then DeltaSpike will allow you to boot a CDI implementation where you can use Dependency Injection with
+a Bean Manager. Such an example will be presented at the next section.
+
+# Start a CDI container using Java SE
+
+This code snippet show you how with a Java MainApplication a CDI container can be started (= boot) by DeltaSpike using Java SE and how you
+ define a CDI scope and resolve beans injected.
+
+**Hint**: To bootstrap a CDI container in your Java application, you just need to instantiate the `CdiContainer` and call the `#boot` method.
:::java
import org.apache.deltaspike.cdise.api.CdiContainer;
import org.apache.deltaspike.cdise.api.CdiContainerLoader;
- public class SimpleApp {
+ public class MainApp {
public static void main(String[] args) {
CdiContainer CdiContainer = CdiContainerLoader.getCdiContainer();
@@ -204,7 +244,7 @@ Example for starting the application-con
import org.apache.deltaspike.cdise.api.ContextControl;
import javax.enterprise.context.ApplicationScoped;
- public class SimpleApp {
+ public class MainApp {
public static void main(String[] args) {
CdiContainer CdiContainer = CdiContainerLoader.getCdiContainer();
@@ -232,87 +272,58 @@ Before the application exits, you have t
# Module Overview
-## Core (required)
+The core features of DeltaSpike project are packaged under the following different modules. Some of them are mandatory while others are optional
-<a class="btn" href="core.html">View details »</a>
+## Core (required)
-## Security (optional)
+Definition : Contain the API and util classes of DeltaSpike project
-<a class="btn" href="security.html">View details »</a>
+Features :
-## JPA (optional)
+* BeanProvider & Manager
+* ProjectStage
+* Config & Property
+* Messages & I18n
+* Exception Handling & Control
-<a class="btn" href="jpa.html">View details »</a>
-
-## JSF (optional)
-
-<a class="btn" href="jsf.html">View details »</a>
+<a class="btn" href="core.html">View details »</a>
-## Container-Control (optional)
+## Security (optional)
-### Usage
+Definition : Intercept and check security
-There are basically two parts:
+Features :
- - The **CdiContainer** interface allows to boot and shutdown the CDI container in SE applications.
- - The **ContextControl** interface allows to control the life-cycle of the built-in contexts of the CDI container.
+*
-### CdiContainer
+<a class="btn" href="security.html">View details »</a>
-See the Java-SE part [above](#start-the-cdi-container).
+## JPA (optional)
-### ContextControl usage
+Definition :
-The `ContextControl` interface allows you to start and stop built-in standard Contexts like `@RequestScoped`, `@ConversationScoped`, `@SessionScoped`, etc. It is provided as `@Dependent` bean and can get injected in the classic CDI way. This is not only usable in Java SE projects but also very helpful in Servlets and Java EE containers.
+Features :
-**Restarting 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 [entitymanager-per-request approach](http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Server/1.0/html/Hibernate_Entity_Manager_Reference_Guide/transactions.html) and thus have a producer method which creates a @RequestScoped EntityManager. Since a single unit test is usually treated as one ârequestâ a problem arises detaching entities.
+<a class="btn" href="jpa.html">View details »</a>
-Using ContextControl to detach entities:
+## JSF (optional)
- @Test
- public void testMyBusinessLogic()
- {
- doSomeJpaStuff()
- MyEntity me = em.find(...);
+Definition :
- ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
+Features :
- //stopping the request context will dispose the @RequestScoped EntityManager
- ctxCtrl.stopContext(RequestScoped.class);
+*
- // and now immediately restart the context again
- ctxCtrl.startContext(RequestScoped.class);
+<a class="btn" href="jsf.html">View details »</a>
- // the entity 'em' is now in a detached state!
- doSomeStuffWithTheDetachedEntity(em);
- }
+## Container Control (optional)
-### Attaching a Request Context to a new thread in EE
+Definition :
-Accessing the `@RequestScoped` bean in a new thread will result in a `ContextNotActiveException`. The request-context usually gets started for a particular thread via a simple `ServletRequestListener`. So "no servlet-request" means that there is no Servlet-Context for the current (/new) Thread.
-You might face such issues, if you would like to reuse business services in e.g. a Quartz Job.
+Features :
-Controlling the request-context for a Quartz-Job:
+*
- public class CdiJob implements org.quartz.Job
- {
- public void execute(JobExecutionContext context) throws JobExecutionException
- {
- ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
-
- //this will implicitly bind a new RequestContext to the current thread
- ctxCtrl.startContext(RequestScoped.class);
-
- try
- {
- doYourWork();
- }
- finally
- {
- //stop the RequestContext to ensure that all request-scoped beans get cleaned up.
- ctxCtrl.stopContext(RequestScoped.class);
- }
- }
- }
\ No newline at end of file
+<a class="btn" href="container-control.html">View details »</a>
\ No newline at end of file
Modified: incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext?rev=1429950&r1=1429949&r2=1429950&view=diff
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext (original)
+++ incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext Mon Jan 7 18:46:49 2013
@@ -16,6 +16,10 @@ Notice: Licensed to the Apache Softwa
specific language governing permissions and limitations
under the License.
+[TOC]
+
+***
+
# @Transactional
This annotation is an alternative to transactional EJBs which allows to execute a method within a transaction.
@@ -27,6 +31,7 @@ As an alternative it's possible to use a
Producer for the default EntityManager:
+ :::java
//...
public class EntityManagerProducer
{
@@ -54,6 +59,7 @@ The following examples show how to use t
Beans with transactional method:
+ :::java
//...
public class TransactionalBean
{
@@ -69,6 +75,7 @@ Beans with transactional method:
Simple transactional bean (all methods transactional):
+ :::java
//...
@Transactional
public class TransactionalBean
@@ -83,6 +90,7 @@ As illustrated in the following example
Stereotype for transactional beans (+ usage):
+ :::java
@Stereotype
@Transactional
@ApplicationScoped
@@ -106,6 +114,7 @@ The example afterwards shows how to chan
Producer for multiple entity managers (+ usage):
+ :::java
//...
public class EntityManagerProducer
{
@@ -182,6 +191,7 @@ The following example shows how to use o
Activating entity managers manually:
+ :::java
public class MultiTransactionBean
{
@Inject
@@ -218,6 +228,7 @@ All examples also work with nested calls
Joining existing transaction in nested call:
+ :::java
//...
public class FirstLevelTransactionBean
{
@@ -256,6 +267,7 @@ So it's possible to catch an exception i
Producer for the default EntityManager which should be used only for one transaction:
+ :::java
//...
public class EntityManagerProducer
{
Modified: incubator/deltaspike/site/trunk/content/deltaspike/resources/css/bootstrap.css
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/resources/css/bootstrap.css?rev=1429950&r1=1429949&r2=1429950&view=diff
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/resources/css/bootstrap.css (original)
+++ incubator/deltaspike/site/trunk/content/deltaspike/resources/css/bootstrap.css Mon Jan 7 18:46:49 2013
@@ -162,7 +162,8 @@ textarea {
body {
margin: 0;
font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
- font-size: 13px;
+ /* font-size: 13px; */
+ font-size: 15px;
line-height: 18px;
color: rgb(51, 51, 51);
background-color: #ffffff;
@@ -426,6 +427,7 @@ a:hover {
p {
margin: 0 0 9px;
+ /*padding-left: 25px; */
}
p small {
@@ -477,6 +479,7 @@ h2 {
font-size: 24px;
/* line-height: 36px; */
line-height: 48px;
+ /*text-indent: 20px; */
}
h2 small {
@@ -486,6 +489,7 @@ h2 small {
h3 {
font-size: 18px;
line-height: 27px;
+ /* text-indent: 40px; */
}
h3 small {
@@ -700,23 +704,6 @@ code {
border: 1px solid #e1e1e8;
}
-/** From OpenEJB Web site
-code, pre {
- padding: 0 3px 2px;
- font-family: Monaco, Andale Mono, Courier New, monospace;
- font-size: 12px;
- -webkit-border-radius: 3px;
- -moz-border-radius: 3px;
- border-radius: 3px;
-}
-
-code {
- color: rgba(0, 0, 0, 0.75);
- padding: 1px 3px;
- //background-color: #fee9cc;
-}
-**/
-
pre {
display: block;
padding: 8.5px;
Modified: incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext?rev=1429950&r1=1429949&r2=1429950&view=diff
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext (original)
+++ incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext Mon Jan 7 18:46:49 2013
@@ -16,7 +16,11 @@ Notice: Licensed to the Apache Softwa
specific language governing permissions and limitations
under the License.
-## SecurityBinding for class and method invocations
+[TOC]
+
+***
+
+# SecurityBinding for class and method invocations
This feature of the security module functions by intercepting method calls, and performing a security check before invocation is allowed to proceed.
@@ -24,6 +28,7 @@ In order to use the DeltaSpike security
Create the SecurityBinding:
+ :::java
@Retention(value = RUNTIME)
@Target({TYPE, METHOD})
@Documented
@@ -37,6 +42,7 @@ This method has access to the Invocation
Create the Authorizer:
+ :::java
@ApplicationScoped
public class CustomAuthorizer
{
@@ -52,6 +58,7 @@ We can then use our new annotation to se
Secure a bean method:
+ :::java
@ApplicationScoped
public class SecuredBean1
{
@@ -66,6 +73,7 @@ Next, we may access parameter values fro
Create a parameter binding annotation:
+ :::java
@Retention(value = RUNTIME)
@Target({PARAMETER})
@Documented
@@ -77,6 +85,7 @@ Now, when a secured method is invoked, w
Update the Authorizer to use parameter binding:
+ :::java
@ApplicationScoped
public class CustomAuthorizer
{
@@ -92,6 +101,7 @@ Note that our business method must also
Complete the parameter binding:
+ :::java
@ApplicationScoped
public class SecuredBean1
{
@@ -107,6 +117,7 @@ Our method is now secured, and we are ab
There may be cases where you may want to base your authorization logic on the result of the secured method and do the security check after the method invocation.
Just use the same security binding type for that case:
+ :::java
@ApplicationScoped
public class SecuredBean1
{
@@ -120,6 +131,7 @@ Just use the same security binding type
Now you need to access the return value in the authorizer method. You can inject it using the @SecuredReturn annotation.
Update the Authorizer to use a secured return value:
+ :::java
@ApplicationScoped
public class CustomAuthorizer
{
@@ -134,6 +146,7 @@ Now the authorization will take place af
Complete the parameter binding:
+ :::java
@ApplicationScoped
public class SecuredBean1
{
@@ -146,9 +159,9 @@ Complete the parameter binding:
Our method is now secured, and we are able to use given parameter values as part of our security authorizer!
-## Integrating 3rd party security frameworks
+# Integrating 3rd party security frameworks
-### @Secured
+## @Secured
`@Secured` is build on `@SecurityBindingType` and a very simple alternative to the rest of the security module.
It's a basic hook to integrate a custom security concept, 3rd party frameworks,... . It doesn't 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.
@@ -157,6 +170,7 @@ It's a basic hook to integrate a custom
Securing all intercepted methods of a CDI bean:
+ :::java
//...
@Secured(CustomAccessDecisionVoter.class)
public class SecuredBean
@@ -168,6 +182,7 @@ or
Securing specific methods:
+ :::java
//...
public class SecuredBean
{
@@ -178,10 +193,11 @@ Securing specific methods:
}
}
-### AccessDecisionVoter
+## AccessDecisionVoter
This interface is (besides the `Secured` annotation) the most important part of the concept. Both artifact types are also the only required parts:
-
+
+ :::java
public class CustomAccessDecisionVoter implements AccessDecisionVoter
{
@Override
@@ -195,18 +211,19 @@ This interface is (besides the `Secured`
[TODO] hint 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`.
[TODO] AbstractAccessDecisionVoter
-### @Secured and Stereotypes with custom Meta-data
+## @Secured and Stereotypes with custom Meta-data
If there are multiple `AccessDecisionVoter` and maybe in different constellations, it's easier to provide an expressive CDI stereotypes for it. Later on that also allows to change the behaviour in a central place.
Stereotype support of @Secured:
+ :::java
@Named
@Admin
public class MyBean implements Serializable
@@ -225,6 +242,7 @@ Furthermore, it's possible to provide cu
Stereotype of @Secured with custom meta-data:
+ :::java
@Named
@Admin(securityLevel=3)
public class MyBean implements Serializable
@@ -253,7 +271,7 @@ Stereotype of @Secured with custom meta-
}
}
-## AccessDecisionVoterContext
+# AccessDecisionVoterContext
[TODO]