You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by ra...@apache.org on 2014/12/15 23:25:46 UTC
[4/9] deltaspike git commit: DELTASPIKE-690: More edits to existing
adoc
DELTASPIKE-690: More edits to existing adoc
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/9f897b75
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/9f897b75
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/9f897b75
Branch: refs/heads/master
Commit: 9f897b757bb6a95182e389234647ce00c3a0ce2b
Parents: 427897c
Author: michellemurray <mm...@redhat.com>
Authored: Wed Dec 3 16:44:53 2014 +1000
Committer: Rafael Benevides <ra...@gmail.com>
Committed: Mon Dec 15 20:24:45 2014 -0200
----------------------------------------------------------------------
documentation/src/main/asciidoc/addons.adoc | 25 ++----
documentation/src/main/asciidoc/build.adoc | 9 +--
documentation/src/main/asciidoc/cdiimp.adoc | 4 +-
documentation/src/main/asciidoc/configure.adoc | 2 +-
documentation/src/main/asciidoc/examples.adoc | 6 +-
documentation/src/main/asciidoc/external.adoc | 49 ++++--------
documentation/src/main/asciidoc/index.adoc | 8 +-
documentation/src/main/asciidoc/modules.adoc | 23 ++++++
documentation/src/main/asciidoc/overview.adoc | 2 +-
documentation/src/main/asciidoc/snapshots.adoc | 6 +-
documentation/src/main/asciidoc/source.adoc | 89 +++++++++------------
documentation/src/main/asciidoc/spi.adoc | 73 +++++------------
12 files changed, 126 insertions(+), 170 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/addons.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/addons.adoc b/documentation/src/main/asciidoc/addons.adoc
index 94d0716..05ad2bc 100644
--- a/documentation/src/main/asciidoc/addons.adoc
+++ b/documentation/src/main/asciidoc/addons.adoc
@@ -7,29 +7,16 @@
Add-ons extend the functionality of DeltaSpike and several have been developed external to the DeltaSpike project. Brief information is given here about each of the add-ons, with details of where they can be obtained from.
== Monitoring
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+`ds-monitoring-addon` provides simple monitoring for several common use-cases (exceptions, performance, audits), collecting information about the monitored method-invocations during a request and enabling you to process the entries based on your requirements. For more information about its use and implementation, see http://os890.blogspot.com.au/2014/04/add-on-monitoring-lite-with-deltaspike.html[os890: [add-on\] monitoring lite with deltaspike].
-* What is the purpose of the add-on (e.g., A two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible.)?
-* When would the user use this add-on?
-* Where can the user get the add-on from (https://github.com/os890/ds-monitoring-addon )?
-* Any special instructions for using the add-on correctly?
+**Source code:** https://github.com/os890/ds-monitoring-addon
== Spring Bridge
-`ds-spring-bridge-addon` is a two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible. You can obtain this add-on from https://github.com/os890/ds-spring-bridge-addon.
+`ds-spring-bridge-addon` is a two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible. For more information about its use and implementation, see http://os890.blogspot.com.au/2013/12/add-on-spring-bridge-with-deltaspike.html[os890: [add-on\] spring-bridge with deltaspike].
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
-
-* What is the purpose of the add-on (e.g., A two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible.)?
-* When would the user use this add-on?
-* Where can the user get the add-on from (https://github.com/os890/ds-spring-bridge-addon )?
-* Any special instructions for using the add-on correctly?
+**Source code:** https://github.com/os890/ds-spring-bridge-addon.
== Disruptor
-This add-on creates a disruptor process for every observer method. It currently works with Apache TomEE and JBoss AS 7.
-
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+`ds-disruptor-addon` improves CDI synchronous event-processing performance by creating a disruptor process for every observer method, enabling CDI synchronous events in conjunction with asynchronous observers. This add-on currently works with Apache TomEE and JBoss AS 7. For more information about its use and implementation, see http://os890.blogspot.com.au/2014/05/faster-cdi-like-events.html[os890: [add-on\] fast event processing with disruptor + deltaspike].
-* What is the purpose of the add-on (e.g., A two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible.)?
-* When would the user use this add-on?
-* Where can the user get the add-on from (https://github.com/os890/ds-disruptor-addon )?
-* Any special instructions for using the add-on correctly?
+**Source code:** https://github.com/os890/ds-disruptor-addon
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/build.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/build.adoc b/documentation/src/main/asciidoc/build.adoc
index 9ebca70..8d08f5c 100644
--- a/documentation/src/main/asciidoc/build.adoc
+++ b/documentation/src/main/asciidoc/build.adoc
@@ -4,11 +4,11 @@
:toc:
-The DeltaSpike source (modules and examples) is provided for inspection, contribution and testing purposes. The source must be built with Maven, which has been used to automate the compilation, testing and packaging processes. Arquillian tests are automatically conducted when DeltaSpike is built and CDI implementations or containers with which to carry out the tests can be specified.
+The DeltaSpike source (modules and examples) is provided for inspection, contribution and testing purposes. The source must be built with Maven, which has been used to automate the compilation, testing and packaging processes. Arquillian tests are included with the source and a CDI implementation or container can be specified with which to carry out the tests.
-In all cases, to obtain the DeltaSpike source, link:https://deltaspike.apache.org/download.html[download `deltaspike-project-<version>-source-release.zip`] and extract the contents.
+In all cases, to obtain the DeltaSpike source, link:https://deltaspike.apache.org/download.html[download] `deltaspike-project-<version>-source-release.zip` and extract the contents.
-**Note:** You can also obtain the DeltaSpike source from the project Git repository. The repository is subject to change and it can be used for contributing but should not be used in production environments. For more information, see <<source#,Get Source and compile it>>.
+**Note:** You can also obtain the DeltaSpike source from the project Git repository. The repository is subject to change and it can be used for contributing but should not be used in production environments. For more information, see <<source#,Contribute to the DeltaSpike Source>>.
== Build without CDI Implementation Tests
DeltaSpike can be built without executing tests against a CDI implementation, with the following commands:
@@ -42,8 +42,7 @@ $ mvn clean install -POWB
----
|===
-
-== Build and Test with CDI Containers
+== Build and Test with a CDI Container
Tests can be executed with JBoss Weld and Apache OpenWebBeans through Java EE 6+ application servers and containers. Configurations are currently provided as details in the table here.
[cols="2,3a", options="header"]
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/cdiimp.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/cdiimp.adoc b/documentation/src/main/asciidoc/cdiimp.adoc
index 9b63d6f..103ea8a 100644
--- a/documentation/src/main/asciidoc/cdiimp.adoc
+++ b/documentation/src/main/asciidoc/cdiimp.adoc
@@ -186,4 +186,6 @@ EchoService echoService = BeanProvider.getContextualReference(EchoService.class,
----
== Next
-* For more information about the Container Control module, see <<container-control#,Container Control Module>>.
\ No newline at end of file
+* For more information about the Container Control module, see <<container-control#,Container Control Module>>.
+* To understand how the various DeltaSpike modules can enhance and extend your applications, see <<modules#,Overview of DeltaSpike Modules>> and the individual module pages.
+* To see ready-to-deploy example DeltaSpike applications, see <<examples#,See DeltaSpike in Action>>.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/configure.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/configure.adoc b/documentation/src/main/asciidoc/configure.adoc
index 3c8b4ff..bb6db2e 100644
--- a/documentation/src/main/asciidoc/configure.adoc
+++ b/documentation/src/main/asciidoc/configure.adoc
@@ -82,4 +82,4 @@ b. For .ear projects, copy the .jar files to the `EAR/lib directory` and add the
== Next
* To check whether your Java environment needs any additional CDI-specific configuration, see <<cdiimp#,Enable CDI For Your Java Environment>>.
* To see ready-to-deploy example DeltaSpike applications, see <<examples#,See DeltaSpike in Action>>.
-* To understand how the various DeltaSpike modules can enhance and extend your applications, see the individual module pages.
+* To understand how the various DeltaSpike modules can enhance and extend your applications, see <<modules#,Overview of DeltaSpike Modules>> and the individual module pages.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/examples.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/examples.adoc b/documentation/src/main/asciidoc/examples.adoc
index aaeb557..57c5c5e 100644
--- a/documentation/src/main/asciidoc/examples.adoc
+++ b/documentation/src/main/asciidoc/examples.adoc
@@ -22,4 +22,8 @@ $ unzip deltaspike-project-<version>-source-release.zip
----
$ cd /path/to/deltaspike-project-<version>/examples
$ mvn clean package
-----
\ No newline at end of file
+----
+
+== Next
+* To see more ready-to-deploy DeltaSpike examples and templates, see <<external#,External Examples>>.
+* To read how DeltaSpike is being used by developers, see <<articles#,Articles and Blogs>>.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/external.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/external.adoc b/documentation/src/main/asciidoc/external.adoc
index 8a2a1f8..3420d27 100644
--- a/documentation/src/main/asciidoc/external.adoc
+++ b/documentation/src/main/asciidoc/external.adoc
@@ -4,19 +4,21 @@
:toc:
-A number of DeltaSpike examples and templates have been developed external to the DeltaSpike project. These extend the DeltaSpike resources from which you can see DeltaSpike in action. Brief information is given here about each of the examples and templates, with details of where they can be obtained from.
+A number of DeltaSpike examples and templates have been developed external to the DeltaSpike project. These extend the DeltaSpike resources from which you can see DeltaSpike in action. Brief information is given here about the examples and templates, with details of where they can be obtained from.
-== Example: Confess 2012 Workshop Demo
+== Examples
+
+=== Confess 2012 Workshop Demo
This example was prepared for the Confess workshop and demonstrates how to use DeltaSpike instead of and side-by-side with MyFaces CODI. The secured web application demonstrates presenting users with differentiating content based on their account status.
**Source code:** https://github.com/confess/confess2012_deltaspike
-== Example: Fullstack EE6+ with DeltaSpike
+=== Fullstack EE6+ with DeltaSpike
Simple example based on Java EE6+ and DeltaSpike (tested with EE6 and EE7).
**Source code:** https://github.com/os890/ee6-ds-demo
-== Example: Fullstack CODI to DeltaSpike
+=== Fullstack CODI to DeltaSpike
This pair of examples show how to achieve the most important MyFaces CODI features with DeltaSpike and also how to migrate a CODI project to DeltaSpike. The examples are basic, compacting core CODI features into just a few JSF pages, and are intended for deployment with TomEE.
**Source code:** https://github.com/os890/tomee_mf_stack_001
@@ -24,40 +26,21 @@ This pair of examples show how to achieve the most important MyFaces CODI featur
* CODI version in master branch
* Migrated DeltaSpike version in codi2ds branch
-== Examples: JBoss Web Framework Kit Quickstarts
+=== JBoss Quickstarts
The JBoss quickstarts are small working examples that demonstrate recommended practices for specific Java EE technology use cases. A subset of these quickstarts are dedicated to demonstrating DeltaSpike, including custom authorization restrictions using annotations, constructing and modifying beans, extending the influence of CDI using BeanManager, and deactivating DeltaSpike features.
**Source code:** https://github.com/jboss-developer/jboss-wfk-quickstarts
-== Template: Java SE + CDI + DS
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
-
-* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Where can the user get the template from (https://github.com/os890/javase-cdi-ds-project-template )?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
-
-== Template: JSF + CDI + DS (Servlet-Container)
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+== Templates
+=== Java SE + CDI + DS
+**Source code:** https://github.com/os890/javase-cdi-ds-project-template
-* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Where can the user get the template from (https://github.com/os890/javaweb-cdi-ds-project-template )?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+=== JSF + CDI + DS (Servlet-Container)
+**Source code:** https://github.com/os890/javaweb-cdi-ds-project-template
-== Template: EJB + CDI + DS (Module)
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
-
-* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Where can the user get the template from (https://github.com/os890/javaee_cdi_ejb_ds_project_template )?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
-
-== Template: JSF + EJB + CDI + DS (EE-Server)
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+=== EJB + CDI + DS (Module)
+**Source code:** https://github.com/os890/javaee_cdi_ejb_ds_project_template
-* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Where can the user get the template from (https://github.com/os890/javaee_jsf_cdi_ejb_ds_project_template )?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+=== JSF + EJB + CDI + DS (EE-Server)
+**Source code:** https://github.com/os890/javaee_jsf_cdi_ejb_ds_project_template
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/index.adoc b/documentation/src/main/asciidoc/index.adoc
index c83cfc9..5ad6044 100644
--- a/documentation/src/main/asciidoc/index.adoc
+++ b/documentation/src/main/asciidoc/index.adoc
@@ -8,6 +8,7 @@
** <<cdiimp#,Enable CDI For Your Java Environment>>
** <<examples#,See DeltaSpike in Action>>
* Use Individual Modules
+** <<modules#,Overview of DeltaSpike Modules>>
** <<core#,Core>>
** <<bean-validation#,Bean Validation>>
** <<container-control#,Container Control>>
@@ -20,11 +21,12 @@
** <<servlet#,Servlet>>
** <<test-control#,Test-Control>>
* Advanced Information
-** <<build#,Build DeltaSpike from Source>>
+** <<build#,Build and Test DeltaSpike from Source>>
** <<snapshots#,Use DeltaSpike Snapshots>>
** link:https://deltaspike.apache.org/migration-guide.html[Migrate to DeltaSpike]
+** <<source#,Contribute to the DeltaSpike Source>>
** <<spi#,DeltaSpike Service Provider Interface (SPI)>>
-* More Resources
+* Access More DeltaSpike Resources
** <<articles#,Articles and Blogs>>
** <<addons#,Add-ons>>
-** <<external#,External Examples>>
\ No newline at end of file
+** <<external#,External Examples>>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/modules.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/modules.adoc b/documentation/src/main/asciidoc/modules.adoc
new file mode 100644
index 0000000..a7a74fd
--- /dev/null
+++ b/documentation/src/main/asciidoc/modules.adoc
@@ -0,0 +1,23 @@
+= Overview of DeltaSpike Modules
+
+: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:
+
+DeltaSpike consists of ready-to-use modules. These include a core module and a number of optional modules for providing additional enterprise functionality to your applications. An overview of each module is provided here and for more information see the linked individual module pages.
+
+[cols="1,1,2a"]
+.DeltaSpike Modules
+|===
+|<<core#,Core>> | Required | For the essential API and util classes
+|<<bean-validation#,Bean Validation>> | Optional | For adding CDI support in Bean Validation, enabling creation of CDI aware `ConstraintValidator` methods that can use business objects (EJBs, ManagedBeans) to support validation needs
+|<<container-control#,Container Control>> | Optional |
+|<<data#,Data>> | Optional | For an enhanced JPA experience with declarative queries, reducing boilerplate to a minimum
+|<<jpa#,JPA>> | Optional |
+|<<jsf#,JSF>> | Optional |
+|<<partial-bean#,Partial-Bean>> | Optional |
+|<<scheduler#,Scheduler>> | Optional | For simple integration with Quartz v2 (per default) or any other scheduler which supports cron-expressions for job-classes
+|<<security#,Security>> | Optional | For intercept and check security
+|<<servlet#,Servlet>> | Optional | For integration with the Java Servlet API, enabling injection of common servlet objects and propagation of servlet events to the CDI event bus
+|<<test-control#,Test-Control>> | Optional | For easily writing CDI based tests
+|===
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/overview.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/overview.adoc b/documentation/src/main/asciidoc/overview.adoc
index dd92304..01d2724 100644
--- a/documentation/src/main/asciidoc/overview.adoc
+++ b/documentation/src/main/asciidoc/overview.adoc
@@ -89,4 +89,4 @@ In addition to the portable CDI extension modules, DeltaSpike provides a number
*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.
== Next
-For instructions on how to start using DeltaSpike, see <<configure#,Configure DeltaSpike in Your Projects>>.
+For instructions on how to start using DeltaSpike, see <<configure#,Configure DeltaSpike in Your Projects>> and <<cdiimp#,Enable CDI For Your Java Environment>>.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/snapshots.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/snapshots.adoc b/documentation/src/main/asciidoc/snapshots.adoc
index df99e68..4ee98ed 100644
--- a/documentation/src/main/asciidoc/snapshots.adoc
+++ b/documentation/src/main/asciidoc/snapshots.adoc
@@ -8,10 +8,10 @@ If you want to be at the bleeding edge, you can work with DeltaSpike snapshots.
**Warning:** Snapshots provide previews of DeltaSpike during development. Snapshots are subject to change and may not yet include all expected features of the final release. Snapshots should not be used in production environments.
-== Configure Maven to Use the Apache Snapshot Repository
+== 1. Configure Maven to Use the Apache Snapshot Repository
You must add the Apache Snapshot Repository to your Maven configuration `settings.xml` file. This ensures Maven can find the repository when it searches for your project DeltaSpike dependencies.
-. Open Maven configuration `settings.xml` file for editing
+. Open your Maven configuration `settings.xml` file for editing
. Add the Apache Snapshot Repository to the list of repositories
+
[source,xml]
@@ -33,7 +33,7 @@ You must add the Apache Snapshot Repository to your Maven configuration `setting
. Save the `settings.xml` file changes
-== Configure Your Project with the Snapshot Version
+== 2. Configure Your Project with the Snapshot Version
With Maven configured for the Apache Snapshot Repository, you can specify DeltaSpike snapshot versions in your Maven-based projects.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/source.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/source.adoc b/documentation/src/main/asciidoc/source.adoc
index aa80103..ad63f9e 100644
--- a/documentation/src/main/asciidoc/source.adoc
+++ b/documentation/src/main/asciidoc/source.adoc
@@ -1,74 +1,65 @@
-= Get Source and compile it
+= Contribute to the DeltaSpike Source
: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
+If you are looking to contribute to the DeltaSpike source, you must start with the latest version of the code base. DeltaSpike source is stored in the Apache Git repository at https://git-wip-us.apache.org/repos/asf/deltaspike.git
-== SCM / Repository
+It is also important that you follow the git workflows we have established for the project to ensure efficient and clean collaboration as detailed here.
-We are using GIT as a Version Control System. The official GIT
-repository of the project is available
-https://git-wip-us.apache.org/repos/asf/deltaspike.git[here].
+== 1. Get the Source
-
-=== Initial 'checkout'
-
-----------------------------------------------------------------
+. Checkout the source
++
+[source]
+----
git clone https://git-wip-us.apache.org/repos/asf/deltaspike.git
-----------------------------------------------------------------
-
-=== Update existing clone
-
------------------
-git pull --rebase
------------------
-
-
-=== Read-only Mirrors
-
-==== GitHub-Mirror
-
-----------------------------------------------
+----
++
+or for a read-only mirror version
++
+[source]
+----
git clone https://github.com/apache/deltaspike
-----------------------------------------------
-
-More information can be found https://help.github.com/articles/which-remote-url-should-i-use[here].
-
-=== GIT Workflow
-
-We follow an link:../suggested-git-workflows.html[unified GIT workflow] to
-keep the commit history straight and therefore simple and clean. General
-details about GIT at Apache are available
-http://wiki.apache.org/couchdb/Git_At_Apache_Guide[here] and at
-http://git-wip-us.apache.org.
-
-*Hint:*
-
-If you are new to Git you might like to try the
-http://git.or.cz/course/svn.html[Git guide for subversion users] or have
-a look at the http://git-scm.com/book[Git community book].
-
-== Build
-
-So now you probably want to **`build the code`**. So follow the
-instructions <<build.adoc#,here>>
+----
++
+. Update the repository clone
++
+[source]
+----
+git pull --rebase
+----
-== Tools / IDE
+== 2. Make Additions and Changes to the Source
Commits (and in the best case also patches), have to follow our
"formatting rules". The following section provides settings for IDEs
used by us.
-
=== IntelliJ
link:http://deltaspike.apache.org/resources/files/settings.jar[Attached] you can find the settings
for formatting the source code. Import them via File | Import
-Settings...
+Settings
=== Eclipse
For Eclipse you can use this
link:http://deltaspike.apache.org/resources/files/deltaspike-code-conventions.xml[Code Formatter Profile]. Import it via Window | Preferences | Java | Code Style | Formatter
+
+== 3. Build the Source
+Always build and test your changes before you make pull requests to the DeltaSpike repository. For instructions on building the source and running Arquillian tests, see <<build#,Build and Test DeltaSpike from Source>>.
+
+
+== 4. Make a Pull Request
+Ensure your commits and pull requests follow the our established https://deltaspike.apache.org/suggested-git-workflows.html[DeltaSpike GIT workflow].
+
+== Git Resources
+For general information about Git and using Git, see the following:
+
+* http://wiki.apache.org/couchdb/Git_At_Apache_Guide[Git At Apache Guide]
+* http://git-wip-us.apache.org[Git at The ASF]
+* http://git.or.cz/course/svn.html[Git - SVN Crash Course]
+* http://git-scm.com/book[Pro Git]
+* https://help.github.com/articles/which-remote-url-should-i-use[GitHub: Which remote URL should I use?]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/spi.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/spi.adoc b/documentation/src/main/asciidoc/spi.adoc
index 3b8f63c..5a1c705 100644
--- a/documentation/src/main/asciidoc/spi.adoc
+++ b/documentation/src/main/asciidoc/spi.adoc
@@ -4,42 +4,20 @@
:toc:
-== Introduction
+DeltaSpike provides an Service Provider Interface (SPI) to enable you to extend it.
== Deactivatable
-This mechanism is only used for artifacts *like* implementations of
-(`javax.enterprise.inject.spi.Extension`) which *can't* be deactivated
-with std. CDI mechanisms.
-
-This interface is just a marker interface which is implemented by all
-pre-configured DeltaSpike artifacts which can be deactivated manually
-(e.g. to improve the performance if a part isn't needed, to provide a
-custom implementation if the default implementation isn't pluggable by
-default or to bypass an implementation which causes an issue (in this
-case please also *contact us* and we will fix it)).
-
-To deactivate a class it's required to implement `ClassDeactivator`.
-Returning 'false' or 'true' allows to de-/activate the class in
-question. Retuning null means that the current class-deactivator doesn't
-have information about the class in question and can't provide a result.
-Since `ClassDeactivator` implementations are configured with the
-low-level config of DeltaSpike, the class-deactivator with the highest
-ordinal has the final decision. DeltaSpike itself doesn't deactivate an
-implementation, however, an add-on or a 3rd party portable CDI extension
-based on DeltaSpike (Core+) can use the concept to deactivate a default
-implementation of DeltaSpike in favour of its own implementation.
-
-**Attention**: due to the ordinal feature of the low-level config
-approach it's possible that a class-deactivator with a higher ordinal,
-e.g. used in a concrete project, can re-activate a deactivated
-implementation. +
-*Please note* that you might have to deactivate the parts of the add-on
-or 3rd party CDI extension which relies on its own implementation.
-Therefore, you should **be really careful with re-activation**.) The
-implementation should be stateless because the result will be cached and
-as soon as everything is initialized the class-deactivators won't be
-used any longer.
+This mechanism is only used for artifacts *like* implementations of (`javax.enterprise.inject.spi.Extension`) which *can't* be deactivated with std. CDI mechanisms.
+
+This interface is just a marker interface which is implemented by all pre-configured DeltaSpike artifacts which can be deactivated manually (e.g. to improve the performance if a part isn't needed, to provide a custom implementation if the default implementation isn't pluggable by default or to bypass an implementation which causes an issue (in this case please also *contact us* and we will fix it)).
+
+To deactivate a class it's required to implement `ClassDeactivator`. Returning 'false' or 'true' allows to de-/activate the class in question. Retuning null means that the current class-deactivator doesn't have information about the class in question and can't provide a result. Since `ClassDeactivator` implementations are configured with the low-level config of DeltaSpike, the class-deactivator with the highest ordinal has the final decision. DeltaSpike itself doesn't deactivate an implementation, however, an add-on or a 3rd party portable CDI extension based on DeltaSpike (Core+) can use the concept to deactivate a default implementation of DeltaSpike in favour of its own implementation.
+
+**Attention**: due to the ordinal feature of the low-level config approach it's possible that a class-deactivator with a higher ordinal, e.g. used in a concrete project, can re-activate a deactivated implementation.
+
+*Please note* that you might have to deactivate the parts of the add-on or 3rd party CDI extension which relies on its own implementation. Therefore, you should **be really careful with re-activation**.) The implementation should be stateless because the result will be cached and
+as soon as everything is initialized the class-deactivators won't be used any longer.
=== ClassDeactivator
@@ -62,12 +40,7 @@ public class CustomClassDeactivator implements ClassDeactivator
}
----------------------------------------------------------------------------
-A class-deactivator will be resolved from the environment via the
-default resolvers or via a custom resolver which allows to use any type
-of configuration-format. (see
-`org.apache.deltaspike.core.api.config.ConfigResolver`). The key is the
-fully qualified name of the interface
-(`org.apache.deltaspike.core.spi.activation.ClassDeactivator`).
+A class-deactivator will be resolved from the environment via the default resolvers or via a custom resolver which allows to use any type of configuration-format. (see `org.apache.deltaspike.core.api.config.ConfigResolver`). The key is the fully qualified name of the interface (`org.apache.deltaspike.core.spi.activation.ClassDeactivator`).
== ConfigSource
@@ -89,17 +62,12 @@ fully qualified name of the interface
== Global Alternative
-There are several application servers (using CDI 1.0) which can't handle
-alternative CDI beans correctly (e.g. due to a too strict interpretation
-or a broken implementation). Therefore, DeltaSpike allows to use the
-std. `@Alternative` annotation and an additional config entry for
-DeltaSpike which allows to use the alternative implementation as a
-global alternative.
+There are several application servers (using CDI 1.0) which can't handle alternative CDI beans correctly (e.g. due to a too strict interpretation or a broken implementation). Therefore, DeltaSpike allows to use the std. `@Alternative` annotation and an additional config entry for DeltaSpike which allows to use the alternative implementation as a global alternative.
*Std. CDI alternative implementation (without the required XML config)*
[source,java]
------------------------------------------------------
+----
public class CustomBean
{
}
@@ -109,14 +77,11 @@ public class CustomBean
public class AlternativeCustomBean extends CustomBean
{
}
------------------------------------------------------
+----
-Instead of configuring the alternative in the beans.xml, a global
-alternative needs to be configured in
-/META-INF/apache-deltaspike.properties. CDI 1.1 should fix this issue
-and migrating to it means to remove the config entry for DeltaSpike
-again and move to the std. CDI config approach.
+Instead of configuring the alternative in the beans.xml, a global alternative needs to be configured in /META-INF/apache-deltaspike.properties. CDI 1.1 should fix this issue and migrating to it means to remove the config entry for DeltaSpike again and move to the std. CDI config approach.
-----------------------------------------------
+[source]
+----
custom.CustomBean=custom.AlternativeCustomBean
-----------------------------------------------
+----