Return-Path: X-Original-To: apmail-deltaspike-commits-archive@www.apache.org Delivered-To: apmail-deltaspike-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id AAA60102E7 for ; Wed, 26 Nov 2014 20:24:24 +0000 (UTC) Received: (qmail 82436 invoked by uid 500); 26 Nov 2014 20:24:24 -0000 Delivered-To: apmail-deltaspike-commits-archive@deltaspike.apache.org Received: (qmail 82405 invoked by uid 500); 26 Nov 2014 20:24:24 -0000 Mailing-List: contact commits-help@deltaspike.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@deltaspike.apache.org Delivered-To: mailing list commits@deltaspike.apache.org Received: (qmail 82396 invoked by uid 99); 26 Nov 2014 20:24:24 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 26 Nov 2014 20:24:24 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 26 Nov 2014 20:24:18 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id A10BB2388B75; Wed, 26 Nov 2014 20:21:56 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r1641921 [8/10] - in /deltaspike/site/trunk/content/staging/documentation: ./ releasenotes/ Date: Wed, 26 Nov 2014 20:21:54 -0000 To: commits@deltaspike.apache.org From: rafabene@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20141126202156.A10BB2388B75@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: deltaspike/site/trunk/content/staging/documentation/overview.html URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/staging/documentation/overview.html?rev=1641921&view=auto ============================================================================== --- deltaspike/site/trunk/content/staging/documentation/overview.html (added) +++ deltaspike/site/trunk/content/staging/documentation/overview.html Wed Nov 26 20:21:53 2014 @@ -0,0 +1,365 @@ + + + + + + + + +Overview of DeltaSpike + + + + + + + + + + + + + + + + +

Overview of DeltaSpike

+ +

Background +
- CDI
- Portable CDI Extensions
+
About Apache DeltaSpike
Features of DeltaSpike +
+
Next

+ +

Background

CDI

Java Contexts and Dependency Injection for the Java EE platform (JSR 299), abbreviated to CDI, was introduced as part of Java EE6. The core features of CDI are as follows:

+
improved stateful object lifecycles with an additional context named Conversation that encompasses a series of requests within one session and lifecycle management by the container according to well-defined contexts
+
+
dependency injection conducted in a type-safe manner, with type checking conducted at compilation time so errors are exposed earlier and debugging is easier
+
+
event notification facility for object interaction
+
+
a better approach for interceptors with annotations binding interceptors to objects and with a new interceptor named decorator that knows about individual bean attributes through inheritence and is more appropriate for use in solving business problems
+
+
a Service Provider Interface (SPI) for developing portable extensions to the CDI container
+

CDI is a Java Community Process (JCP) standard. All Java EE6 compliant application servers must provide support for CDI. JBoss Weld is a reference implementation of the CDI specification and other spec-compliant implementations exist such as Apache OpenWebBeans (OWB). While CDI is a Java EE6 essential, CDI can also be used in Java SE environments with the aid of standalone CDI implementations.

Portable CDI Extensions

The CDI Service Provider Interface (SPI) is exposed to enable extension of the CDI feature set by third-parties. Portable CDI extensions extend CDI implementations and improve existing Java EE APIs by enabling integration of different technologies.

As set out in the CDI specification, a portable CDI extenstion may integrate with a CDI container as follows:

+
providing its own beans, interceptors and decorators to the container
+
+
injecting dependencies into its own objects using the dependency injection service
+
+
providing a context implementation for a custom scope
+
+
augmenting or overriding the annotation-based metadata with metadata from some other source
+

As indicated by the name, portable CDI extensions can be used with any spec-compliant CDI implementation.

About Apache DeltaSpike

Apache DeltaSpike is a collection of portable CDI extensions. These ready-to-use modules enable you to integrate tested API extensions into your Java projects.

DeltaSpike consists of a core module and a number of optional modules for providing additional enterprise functionality to your applications. The modules include features for enhanced security with type-safe control over method invocations, integration with schedulers, injection of CDI objects into validators, and a transactional context and scope. DeltaSpike also provides boot and shutdown control over CDI containers in Java SE applications.

As a CDI extension, DeltaSpike must be used in conjunction with a CDI implementation and supports both JBoss Weld and Apache OpenWebBeans. DeltaSpike has been tested on a range of application servers and containers that utilize these CDI implementations, such as Apache TomEE, JBoss AS, WildFly, Oracle GlassFish, and Jetty.

In addition to the portable CDI extension modules, DeltaSpike provides a number of examples to show you how to use and get the most from this technology.

Features of DeltaSpike

Java EE 7 without Java EE 7!

Transactional support for non-EJB beans: The Transactional Interceptor in DeltaSpike paved the way for @Transactional in Java EE 7.

Injectable Servlet objects: Allows the developer to inject CDI beans on Servlets on Java EE 6/CDI 1.0 environments

Injectable resources: Configuration, resource bundles,… are easy to inject when using CDI and Apache DeltaSpike.

@Exclude annotation: it’s possible to annotate beans which should be ignored by CDI even if they are in a CDI enabled archive on Java EE 6/CDI 1.0 environment where you can’t use @Vetoed or a veto based on project-stages or expressions is needed.

Scheduling tasks: Async processes in a non Java EE 7 environment.

Bean Validation integration: Allows to inject CDI beans and EJB in to Constraint-Validators.

BeanProvider: Access the BeanManager and CDI beans even in non managed classes like JPA-2.0 EntityListeners or Spring Beans.

JSF Improvements

Multi-window handling: Allows to manage logical windows for batches,… or in case of JSF it offers proper separation of browser-tabs.

Type-safe view-config: It allows to bind meta-data (e.g. for security) to views with a type-safe, but flexible approach. It provides a more solid navigation in case of JSF and helps a lot in the maintenance phase.

View-Controller: Based on type-safe view-configs view-controller annotations provide a type-safe alternative to standard-tags.

Injection on Converters and Validators: Allows to inject CDI beans and EJB in to JSF Converters and Validators.

JSF event broadcasting to CDI: Allows CDI to be notified about JSF events

Productivity Improvements

Security based on annotations: The foundation for building a robust, capable and non invasive security solution.

New CDI scopes: TransactionScoped, WindowScoped, ViewScoped, ViewAccess scope, Grouped conversion scope

Container Control & Test Control: Java SE with CDI, all with a unifying API. Start, stop, add classes to a running CDI container.

Data Module: An out of the box entity framework solution complete with support for container or application managed persistence contexts, as well as JDBC.

Decoupled Exception handling: Allows to do exception handling in one location similar to CDI Observers.

JMX integration: Any CDI bean can be exposed via JMX easily with one annotation.

Type-safe i18n messages: Localized messages are easy to use with an interface and a resource bundle, no more boilerplate and your messages now have context within the code.

Type-safe Project-Stages: Compared to project-stages in JSF, DeltaSpike provides a type-safe, but still extensible approach which can be used in CDI based applications.

For instructions on how to start using DeltaSpike, see Configure DeltaSpike in Your Projects.

+ +

+ + + +

+ + + + \ No newline at end of file Added: deltaspike/site/trunk/content/staging/documentation/partial-bean.html URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/staging/documentation/partial-bean.html?rev=1641921&view=auto ============================================================================== --- deltaspike/site/trunk/content/staging/documentation/partial-bean.html (added) +++ deltaspike/site/trunk/content/staging/documentation/partial-bean.html Wed Nov 26 20:21:53 2014 @@ -0,0 +1,237 @@ + + + + + + + + +Partial-Bean + + + + + + + + + + + + + + + + +

Partial-Bean

+ +

Usage

+ +

Usage

Partial beans allow you to implement a generic handler to replace manual +implementations of interfaces (or abstract classes).

@PartialBeanBinding is the binding-annotation for creating a custom +interface (/abstract class) to generic handler binding.

@PartialBeanBinding
+
+@Retention(RUNTIME)
+@Target(TYPE)
+public @interface MyPartialBeanBinding {}
+
+@MyPartialBeanBinding
+//scope is optional
+public interface PartialBean
+{
+    String getValue();
+}
+
+@MyPartialBeanBinding
+@Dependent
+public class MyPartialBeanHandler implements java.lang.reflect.InvocationHandler
+{
+    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable
+    {
+        //generic handler logic
+    }
+}

Using an abstract class as partial-bean requires javassist as an +additional dependency and allows to implement some methods manually.

Attention: Currently CDI-Interceptors can’t be used for partial-beans.

+ +

+ + + +

+ + + + \ No newline at end of file Added: deltaspike/site/trunk/content/staging/documentation/projectstage.html URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/staging/documentation/projectstage.html?rev=1641921&view=auto ============================================================================== --- deltaspike/site/trunk/content/staging/documentation/projectstage.html (added) +++ deltaspike/site/trunk/content/staging/documentation/projectstage.html Wed Nov 26 20:21:53 2014 @@ -0,0 +1,333 @@ + + + + + + + + +DeltaSpike ProjectStage + + + + + + + + + + + + + + + + +

DeltaSpike ProjectStage

+ +

Introduction +
- Custom Project Stages
- ProjectStageProducer (for 3rd party portable extensions) +
  - Setting the active ProjectStage
  +
+

+ +

Introduction

Project stages allow to use implementations depending on the current +environment. E.g. you can implement a bean which creates sample-data for +system tests which gets activated only in case of project-stage +SystemTest.

Besides custom project-stages it’s possible to use the following +pre-defined project-stages:

+
UnitTest
+
+
Development
+
+
SystemTest
+
+
IntegrationTest
+
+
Staging
+
+
Production
+

The core provides a pluggable and type-safe approach for using project +stages in a project (it’s also used within the framework). Furthermore, +@Exclude allows to use e.g. i mplementations annotated with +javax.enterprise.inject.Alternative for specific project-stages. +Besides the out-of-the-box project-stages it’s possible to implement +custom but type-safe project-stages which will be exposed by +DeltaSpike.

Resolving and using the Project-Stage:

@Inject
+private ProjectStage projectStage;
+
+//...
+
+boolean isDevProjectStage = ProjectStage.Development.equals(this.projectStage);

Custom Project Stages

It’s possible to provide custom project stage implementations. +Therefore, you have to provide an implementation of the +ProjectStageHolder interface. In this class you nest the custom +project-stage implementations which have to be +public static final class and it’s required to extend ProjectStage. +It’s required to provide a public static final instance even though, +you won’t use it directly.

ProjectStageHolder for custom project stage implementations:

public class CustomProjectStageHolder implements ProjectStageHolder
+{
+    public static final class CustomProjectStage extends ProjectStage
+    {
+        private static final long serialVersionUID = 1029094387976167179L;
+    }
+
+    public static final CustomProjectStage CustomProjectStage = new CustomProjectStage();
+}

Configure your custom ProjectStageHolder in +META-INF/services/org.apache.deltaspike.core.api.projectstage.ProjectStageHolder. +The file has to provide the fully qualified class name of the custom +implementation of the ProjectStageHolder interface.

Usage of a custom project stage:

ProjectStage customProjectStage;
+customProjectStage = ProjectStage.valueOf("CustomProjectStage");
+//or
+customProjectStage = CustomProjectStageHolder.CustomProjectStage;
+//or
+@Exclude(ifProjectStage = CustomProjectStageHolder.CustomProjectStage.class)

ProjectStageProducer (for 3rd party portable extensions)

ProjectStageProducer provides the producer method which allows to +inject the current project-stage. However, in some cases it’s needed to +use project-stages also during the bootstrapping process of the CDI +container and you can’t use injection. In such cases you can use +ProjectStageProducer.getInstance().getProjectStage() to resolve the +current project-stage. This helper also contains helpers for unit-tests +- e.g. #setProjectStage. However, those methods shouldn’t be needed +for users (we just need them for testing different project-stage +scenarios).

Setting the active ProjectStage

For setting the ProjectStage which shall get used in your application +you can specify it in a few ways. The underlying mechanism used to +determine the string is the ConfigResolver. E.g.:

-Dorg.apache.deltaspike.ProjectStage=Development

+ +

+ + + +

+ + + + \ No newline at end of file Added: deltaspike/site/trunk/content/staging/documentation/scheduler.html URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/staging/documentation/scheduler.html?rev=1641921&view=auto ============================================================================== --- deltaspike/site/trunk/content/staging/documentation/scheduler.html (added) +++ deltaspike/site/trunk/content/staging/documentation/scheduler.html Wed Nov 26 20:21:53 2014 @@ -0,0 +1,361 @@ + + + + + + + + +Scheduler Module + + + + + + + + + + + + + + + + +

Scheduler Module

+ +

Intro
External Dependencies
@Scheduled
Manual Scheduler Control
Custom Scheduler

+ +

Intro

This module provides a simple integration with Quartz v2 (per default) +or any other scheduler which supports cron-expressions for job-classes.

External Dependencies

If you would like to use the default-integration with quartz (which is +optional), you have to add quartz 2.x.

<dependency>
+    <groupId>org.quartz-scheduler</groupId>
+    <artifactId>quartz</artifactId>
+    <version>2.2.1</version>
+</dependency>

@Scheduled

Just annotate your Quartz-Jobs with @Scheduled and they will get +picked up and passed to the scheduler automatically (during the +bootstrapping process).

@Scheduled(cronExpression = "0 0/10 * * * ?")
+public class CdiAwareQuartzJob implements org.quartz.Job
+{
+    @Inject
+    private MyService service;
+
+    @Override
+    public void execute(JobExecutionContext context) throws JobExecutionException
+    {
+        //...
+    }
+}

In such Quartz-jobs CDI based dependency-injection is enabled. +Furthermore, the request- and session-scope get started (and stopped) +per job-execution. Therefore, the container-control module (of +DeltaSpike) is required. That can be controlled via +@Scheduled#startScopes (possible values: all scopes supported by the +container-control module as well as {} for 'no scopes').

With 'false' for @Scheduled#onStartup it’s even possible to +schedule/install jobs dynamically - e.g.:

@ApplicationScoped
+public class ProjectStageAwareSchedulerController
+{
+    @Inject
+    private Scheduler<Job> jobScheduler;
+
+    @Inject
+    private ProjectStage projectStage;
+
+    public void registerJobs()
+    {
+        if (ProjectStage.Production.equals(this.projectStage))
+        {
+            //see 'false' for @Scheduled#onStartup
+            this.jobScheduler.scheduleJob(ManualCdiAwareQuartzJob.class);
+        }
+    }
+
+    @Scheduled(cronExpression = "0 0/10 * * * ?", onStartup = false)
+    public class ManualCdiAwareQuartzJob implements org.quartz.Job
+    {
+        @Inject
+        private MyService service;
+
+        @Override
+        public void execute(JobExecutionContext context) throws JobExecutionException
+        {
+            //...
+        }
+    }
+}

Manual Scheduler Control

This SPI allows to control the scheduler (or integrate any other +compatible scheduler as an alternative to Quartz2)

Via std. injection like

@Inject
+private Scheduler<Job> jobScheduler;

it’s possible to manually start/stop the scheduler, +pause/resume/interrupt/check scheduled jobs, register jobs manually or +start a job once (without registering it permanently).

Attention:

With some versions of Weld you have to use

public class QuartzSchedulerProducer
+{
+    @Produces
+    @ApplicationScoped
+    protected Scheduler<Job> produceScheduler(Scheduler scheduler)
+    {
+        return scheduler;
+    }
+}

<alternatives>
+  <class>org.apache.deltaspike.scheduler.impl.QuartzSchedulerProducer</class>
+</alternatives>

to use a typed injection-point. Otherwise the deployment will fail.

Custom Scheduler

It’s possible to replace the default integration with Quartz. Any other +scheduler which supports cron-expressions for job-classes can be used. +Please have a look at org.apache.deltaspike.test.scheduler.custom for +further details.

+ +

+ + + +

+ + + + \ No newline at end of file

Overview of DeltaSpike

Background

CDI

Portable CDI Extensions

About Apache DeltaSpike

Features of DeltaSpike

Java EE 7 without Java EE 7!

JSF Improvements

Productivity Improvements

Next

Partial-Bean

Usage

DeltaSpike ProjectStage

Introduction

Custom Project Stages

ProjectStageProducer (for 3rd party portable extensions)

Setting the active ProjectStage

Scheduler Module

Intro

External Dependencies

@Scheduled

Manual Scheduler Control

Custom Scheduler