deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rafab...@apache.org
Subject [4/9] deltaspike git commit: DELTASPIKE-690: More edits to existing adoc
Date Mon, 15 Dec 2014 22:25:46 GMT
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 <mmurray@redhat.com>
Authored: Wed Dec 3 16:44:53 2014 +1000
Committer: Rafael Benevides <rafabene@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
-----------------------------------------------
+----


Mime
View raw message