You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by rs...@apache.org on 2015/05/05 20:33:18 UTC
deltaspike git commit: DELTASPIKE-813 more fixes to core documentation
Repository: deltaspike
Updated Branches:
refs/heads/master f1c440447 -> 0b5c027c6
DELTASPIKE-813 more fixes to core documentation
* TypedResolver javadoc
* fixed multiple occurrences of "cais" "doesis" and "shouldis"
* added docs for ConfigFilter, AbstractResourceProvider, BaseConfigPropertyProducer, DeltaSpikeConfig, DeltaSpikeBaseConfig
* restructured Configuration docs
* restructured Overview docs
* Fixed wrong link on Scheduler docs page
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/0b5c027c
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/0b5c027c
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/0b5c027c
Branch: refs/heads/master
Commit: 0b5c027c6c8696a078e795ca9747ae75a8128b43
Parents: f1c4404
Author: Ron Smeral <rs...@apache.org>
Authored: Tue May 5 20:19:06 2015 +0200
Committer: Ron Smeral <rs...@apache.org>
Committed: Tue May 5 20:29:49 2015 +0200
----------------------------------------------------------------------
.../core/api/config/ConfigResolver.java | 103 ++++++-
.../spi/config/BaseConfigPropertyProducer.java | 6 +-
.../src/main/asciidoc/configuration.adoc | 278 +++++++++++++++----
documentation/src/main/asciidoc/core.adoc | 135 +++++----
documentation/src/main/asciidoc/jsf.adoc | 6 +-
documentation/src/main/asciidoc/overview.adoc | 109 +++++---
.../src/main/asciidoc/projectstage.adoc | 4 +-
documentation/src/main/asciidoc/scheduler.adoc | 2 +-
documentation/src/main/asciidoc/security.adoc | 2 +-
documentation/src/main/asciidoc/servlet.adoc | 2 +-
documentation/src/main/asciidoc/spi.adoc | 11 +-
.../src/main/asciidoc/test-control.adoc | 2 +-
12 files changed, 492 insertions(+), 168 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
index 9cc662e..d350ae7 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
@@ -529,45 +529,143 @@ public final class ConfigResolver
return logValue;
}
+ /**
+ * A very simple interface for conversion of configuration values from String to any Java type.
+ * @param <T> The target type of the configuration entry
+ */
public interface Converter<T>
{
+ /**
+ * Returns the converted value of the configuration entry.
+ * @param value The String property value to convert
+ * @return Converted value
+ */
T convert(String value);
}
+ /**
+ * A builder-based typed resolution mechanism for configuration values.
+ * @param <T> The target type of the configuration entry.
+ */
public interface TypedResolver<T>
{
+ /**
+ * Appends the resolved value of the given property to the key of this builder. This is described in more detail
+ * in {@link ConfigResolver#getPropertyAwarePropertyValue(String, String)}.
+ * @param propertyName The name of the parameter property
+ * @return This builder
+ */
TypedResolver<T> parameterizedBy(String propertyName);
+ /**
+ * Indicates whether to append the name of the current project stage to the key of this builder. This
+ * is described in more detail in {@link ConfigResolver#getProjectStageAwarePropertyValue(String)}. True by
+ * default.
+ * @param with
+ * @return This builder
+ */
TypedResolver<T> withCurrentProjectStage(boolean with);
+ /**
+ * Indicates whether the fallback resolution sequence should be performed, as described in
+ * {@link ConfigResolver#getPropertyAwarePropertyValue(String, String)}. This applies only when
+ * {@link #parameterizedBy(String)} or {@link #withCurrentProjectStage(boolean)} is used.
+ * @param strictly
+ * @return This builder
+ */
TypedResolver<T> strictly(boolean strictly);
+ /**
+ * Sets the default value to use in case the resolution returns null.
+ * @param value the default value
+ * @return This builder
+ */
TypedResolver<T> withDefault(T value);
+ /**
+ * Sets the default value to use in case the resolution returns null. Converts the given String to the type of
+ * this resolver using the same method as used for the configuration entries.
+ * @param value string value to be converted and used as default
+ * @return This builder
+ */
TypedResolver<T> withStringDefault(String value);
+ /**
+ * Returns the converted resolved filtered value.
+ * @return the resolved value
+ */
T getValue();
+ /**
+ * Returns the key given in {@link #resolve(String)}.
+ * @return the original key
+ */
String getKey();
+ /**
+ * Returns the actual key which led to successful resolution and corresponds to the resolved value. This applies
+ * only when {@link #parameterizedBy(String)} or {@link #withCurrentProjectStage(boolean)} is used and
+ * {@link #strictly(boolean)} is not used, otherwise the resolved key should always be equal to the original
+ * key. This method is provided for cases, when projectStage-aware and/or parameterized resolution is
+ * requested but the value for such appended key is not found and some of the fallback keys is used, as
+ * described in {@link ConfigResolver#getPropertyAwarePropertyValue(String, String)}.
+ * This should be called only after calling {@link #getValue()} otherwise the value is undefined (but likely
+ * null).
+ * @return
+ */
String getResolvedKey();
+ /**
+ * Returns the default value provided by {@link #withDefault(Object)} or {@link #withStringDefault(String)}.
+ * Returns null if no default was provided.
+ * @return the default value or null
+ */
T getDefaultValue();
}
+ /**
+ * A builder-based optionally typed resolution mechanism for configuration values.
+ * @param <T> This type variable should always be String for UntypedResolver.
+ */
public interface UntypedResolver<T> extends TypedResolver<T>
{
-
+ /**
+ * Sets the type of the configuration entry to the given class and returns this builder as a TypedResolver.
+ * Only one of the supported types should be used which includes: Boolean, Class, Integer, Long, Float, Double.
+ * For custom types, see {@link #as(Class, Converter)}.
+ * @param clazz The target type
+ * @param <N> The target type
+ * @return This builder as a TypedResolver
+ */
<N> TypedResolver<N> as(Class<N> clazz);
+ /**
+ * Sets the type of the configuration entry to the given class, sets the converter to the one given and
+ * returns this builder as a TypedResolver. If a converter is provided for one of the types supported by
+ * default (see {@link #as(Class)} then the provided converter is used instead of the built-in one.
+ * @param clazz The target type
+ * @param converter The converter for the target type
+ * @param <N> The target type
+ * @return This builder as a TypedResolver
+ */
<N> TypedResolver<N> as(Class<N> clazz, Converter<N> converter);
}
+ /**
+ * The entry point to the builder-based optionally typed configuration resolution mechanism.
+ *
+ * String is the default type for configuration entries and is not considered a 'type' by this resolver. Therefore
+ * an UntypedResolver is returned by this method. To convert the configuration value to another type, call
+ * {@link UntypedResolver#as(Class)}.
+ *
+ * @param name The property key to resolve
+ * @return A builder for configuration resolution.
+ */
public static UntypedResolver<String> resolve(String name)
{
return new PropertyBuilder<String>(name);
@@ -785,6 +883,9 @@ public final class ConfigResolver
return value;
}
+ /**
+ * If a converter was provided for this builder, it takes precedence over the built-in converters.
+ */
private T convert(String value)
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/spi/config/BaseConfigPropertyProducer.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/spi/config/BaseConfigPropertyProducer.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/spi/config/BaseConfigPropertyProducer.java
index 4526a3c..e325aff 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/spi/config/BaseConfigPropertyProducer.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/spi/config/BaseConfigPropertyProducer.java
@@ -31,8 +31,8 @@ import org.apache.deltaspike.core.util.BeanUtils;
* ConfigProperty producers.</p>
*
* <h2>Providing own Converters and Type injection</h2>
- * <p>DeltaSpikes own configuration system only natively only supports Strings.
- * If you like to apply own Converters or extract other types from those Strings,
+ * <p>DeltaSpikes own configuration system natively supports only Strings.
+ * If you'd like to apply own Converters or extract other types from those Strings,
* you can simply do this by providing an own Qualifier and a simple
* CDI producer method for it.</p>
*
@@ -78,7 +78,7 @@ import org.apache.deltaspike.core.util.BeanUtils;
*
* // format according to the given pattern
* DecimalFormat df = new DecimalFormat(metaData.pattern(), new DecimalFormatSymbols(Locale.US));
- * return df.parse(configuredValue).floatValue(); *
+ * return df.parse(configuredValue).floatValue();
* }
* }
* </pre>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/documentation/src/main/asciidoc/configuration.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/configuration.adoc b/documentation/src/main/asciidoc/configuration.adoc
index 2bada1b..dd75ae7 100644
--- a/documentation/src/main/asciidoc/configuration.adoc
+++ b/documentation/src/main/asciidoc/configuration.adoc
@@ -2,20 +2,17 @@
: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.
-== Configuration Basics
-
+== Introduction
The goal of the DeltaSpike configuration mechanism is to make it
obsolete to touch released binaries for changing the configuration of
your project. All values which are needed in your code (but should not
be hardcoded as static final constants) can be maintained via
-DeltaSpikes own configuration mechanism in a very flexible and powerful
+DeltaSpike's own configuration mechanism in a very flexible and powerful
way.
-
=== Benefits for Production
-
Once a binary like a WAR file or an EAR got created and tested, it must
_not_ get changed anymore. The exact same binary which got created by
the release manager will get moved to the Test system, then further
@@ -55,23 +52,26 @@ users can utilize it for their own needs as well. This is done by using
the `ConfigResolver` which resolves and caches `ConfigSource`s per
application.
-=== Userland Configuration
-DeltaSpike also provides a mechanism to inject those configured values
-using the `@ConfigProperty` CDI Qualifier.
+== Accessing configured values using ConfigResolver
+
+The `ConfigResolver` is the central point to access configuration in DeltaSpike. There are several different APIs
+ and ways to access the individual configured values, each suitable for a different purpose:
+ * `ConfigResolver` methods for easy programmatic access to values
+ * `TypedResolver` API for typed configuration values and precise control over resolution
+ * `@ConfigProperty` for injection of configured values into beans
-== ConfigResolver
+All three mechanisms are described in the following sections.
+=== ConfigResolver methods
-The `ConfigResolver` is the central point to pick up configured values
-in DeltaSpike.
+ConfigResolver offers several methods for easy access to String values of configured properties.
-=== getPropertyValue()
+==== getPropertyValue()
-The method `ConfigResolver#getPropertyValue(String key)` allows to
-provide a string based key and returns the configured value as `String`,
-or `null` if no value has been found.
+The method `ConfigResolver#getPropertyValue(String key)` returns the value configured for a given key
+as `String`, or `null` if no value has been found.
`ConfigResolver#getAllPropertyValues(String key)` has a similar contract
but it returns a list which might be empty if there are no configured
@@ -85,14 +85,12 @@ configuration:
String dbUserName = ConfigResolver.getPropertyValue("databaseconfig.username");
-------------------------------------------------------------------------------
-
-=== getProjectStageAwarePropertyValue()
+==== getProjectStageAwarePropertyValue()
The method
`ConfigResolver#getProjectStageAwarePropertyValue(String key)` utilizes
the <<projectstage.adoc#,DeltaSpike ProjectStage>> mechanism to allow
-configured values to depend on the current `ProjectStage` of the system
-we run on.
+configured values to depend on the current `ProjectStage` of the running system.
This is done by first looking up the ProjectStage (this internally
happens with the DeltaSpike ConfigResolver as well) and then go down the
@@ -101,7 +99,7 @@ following lookup chain until we found a configured value.
* key + '.' + projectStage , e.g. "databaseconfig.username.Production"
* key alone , e.g. "databaseconfig.username"
-=== getPropertyAwarePropertyValue()
+==== getPropertyAwarePropertyValue()
The method
`ConfigResolver#getProjectStageAwarePropertyValue(String key, String property)`
@@ -109,15 +107,15 @@ first looks up the configured value of the given property and uses this
value to determine the final lookup path. All those lookups take the
<<projectstage.adoc#,DeltaSpike ProjectStage>> mechanism into account.
-Given we have the following code in our program:
-
[source,java]
--------------------------------------------------------------------------------------------------------
String dbUserName = ConfigResolver.getPropertyAwarePropertyValue("databaseconfig.username", "dbvendor");
--------------------------------------------------------------------------------------------------------
-This will end up in the following lookup sequences. First we need to
-resolve the value of the property:
+===== Property value resolution sequence
+
+The following lookup sequence will be performed until a value is found:
+First, the value of the _parameter_ property is resolved:
* propertyValue = property + '.' + projectStage, e.g. "dbvendor.Production"
* if nothing found: propertyValue = property, e.g. "dbvendor"
@@ -125,13 +123,12 @@ resolve the value of the property:
Let's assume we found the value 'mysql' for our dbvendor. In this case
the following lookup chain is used until a value got found:
-* key + '.' + property + projectstage, e.g. "databaseconfig.username.mysql.Production"
-* key + '.' + property, e.g. "databaseconfig.username.mysql"
-* key + '.' + projectstage, e.g. "databaseconfig.username.Production"
+* key + '.' + propertyValue + '.' + projectstage, e.g. "databaseconfig.username.mysql.Production"
+* key + '.' + propertyValue, e.g. "databaseconfig.username.mysql"
+* key + '.' + projectStage, e.g. "databaseconfig.username.Production"
* key, e.g. "databaseconfig.username"
-
-=== Handling of Default Values
+==== Handling of Default Values
There is a 2nd variant of all those methods where it is possible to
provide a default value which gets returned instead of `null` or if the
@@ -143,11 +140,180 @@ of the `ConfigSources`. The various getPropertyValue operations are not
cached in the ConfigResolver but might be cached in the ConfigSources.
This makes the overall calculation a bit slower, but allows for values
to change dynamically if someone likes to for example implement a
-`JmxConfigSource` (not yet part of DeltaSpike, but easily
-implementable).
+`JmxConfigSource` (not yet part of DeltaSpike, but easily implementable).
+
+=== TypedResolver API
+
+Very often the configured values represent more than just strings -- number types and booleans are commonly used as
+configuration types. ConfigResolver provides a builder-style API to access configuration values as specific types.
+The API is accessed by a call to `ConfigResolver.resolve(propertyKey)`.
+
+The simplest usage of the API is resolution of a String property, equivalent to a call to
+`ConfigResolver.getPropertyValue(propertyKey)`.
+
+.Simple example of TypedResolver
+[source,java]
+-----------------------------------------------------------------
+String userName = ConfigResolver.resolve("user.name").getValue();
+-----------------------------------------------------------------
+
+The call to `ConfigResolver.resolve(..)` returns a builder which has methods to refine the resolution, including the
+following:
+
+* `as(Class<N> clazz)` -- defines the return type of the property
+* `parameterizedBy(String propertyName)` -- sets a parameter for the resolution, similarly as in
+<<_getpropertyawarepropertyvalue, ConfigResolver.getPropertyAwarePropertyValue>>
+* `withCurrentProjectStage(boolean with)` -- indicates whether the current ProjectStage should be taken into account
+for the resolution
+* `strictly(boolean strictly)` -- indicates, whether the <<_property_value_resolution_sequence, property value
+resolution sequence>> should be taken into account. When set to true, the sequence is not followed.
+* `withDefault(T value)` -- sets the default value, used in case the resolution returns `null`
+* `getValue()` -- terminates the builder and returns the resolved value with the appropriate type
+
+.A more complete example of TypedResolver
+[source,java]
+-----------------------------------------------------------------
+Integer dbPort = ConfigResolver
+ .resolve("db.port")
+ .as(Integer.class)
+ .withProjectStage(true)
+ .parameterizedBy("db.vendor")
+ .withDefault(3306)
+ .getValue();
+-----------------------------------------------------------------
+
+==== Supported types
+
+The types supported out of the box include: String, Integer, Long, Float, Double, Boolean, Class.
+Custom types can be supported by providing an implementation of the `ConfigResolver.Converter` interface.
+
+[source,java]
+---------------------------------------------------------------------------------------------------------
+Date deadline = ConfigResolver.resolve("deadline").as(Date.class, new CustomDateConverter()).getValue());
+---------------------------------------------------------------------------------------------------------
+
+[source,java]
+------------------------------------------------------------------------------------------
+public class CustomDateConverter implements ConfigResolver.Converter<Date> {
+
+ @Override
+ public Date convert(String value)
+ {
+ String[] parts = value.split("-");
+ return new GregorianCalendar(Integer.valueOf(parts[0]), Integer.valueOf(parts[1]),
+ Integer.valueOf(parts[2])).getTime();
+ }
+}
+------------------------------------------------------------------------------------------
-== ConfigSource
+=== Injection of configured values into beans using @ConfigProperty
+
+DeltaSpike provides a way to inject configured values into your code via the qualifier `@ConfigProperty`.
+The supported types are the same as the <<_supported_types,supported types of the TypedResolver>>.
+
+[source,java]
+------------------------------------------------------
+@ApplicationScoped
+public class SomeRandomService
+{
+ @Inject
+ @ConfigProperty(name = "endpoint.poll.interval")
+ private Integer pollInterval;
+
+ @Inject
+ @ConfigProperty(name = "endpoint.poll.servername")
+ private String pollUrl;
+
+ ...
+ }
+------------------------------------------------------
+
+==== Custom ConfigProperty types
+
+Custom types can be injected using `@ConfigProperty` by providing a custom producer.
+DeltaSpike provides a base implementation for custom producers in the class `BaseConfigPropertyProducer`
+which offers the following methods:
+* `getStringPropertyValue` -- looks for the property name in `@ConfigProperty` annotation on the injection point.
+If not found, it looks for it in other annotations on the injection point.
+* `getPropertyValue` -- a shortcut to <<_configresolver, ConfigResolver#getProjectStageAwarePropertyValue>>
+* `getAnnotation` -- extracts any annotation type from the injection point, useful when a custom annotation
+is used instead of `@ConfigProperty`
+
+The following example uses `getStringPropertyValue` and a custom `@Location` annotation annotated `@ConfigProperty`.
+In such case, the `@Location` annotation is bound to a single fixed property name and acts as a type-safe replacement
+for `@ConfigProperty(name = "locationId")`.
+
+[source,java]
+--------------------------------------------------------------------
+@ApplicationScoped
+public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer {
+
+ @Produces
+ @Dependent
+ @Location
+ public LocationId produceLocationId(InjectionPoint injectionPoint)
+ {
+ String configuredValue = getStringPropertyValue(injectionPoint);
+
+ return LocationId.valueOf(configuredValue.trim().toUpperCase());
+ }
+}
+--------------------------------------------------------------------
+
+[source,java]
+-----------------------------------------------------------------
+@Target({ FIELD, METHOD })
+@Retention(RUNTIME)
+@ConfigProperty(name = "locationId", defaultValue = "LOCATION_X")
+@Qualifier
+public @interface Location {}
+-----------------------------------------------------------------
+
+The `@ConfigProperty` annotation doesn't need to be used at all. Instead, a custom annotation can be provided and
+obtained in the producer using `getAnnotation` and `getPropertyValue`:
+
+[source,java]
+------------------------------------------------------------------------------------------------------
+@ApplicationScoped
+public class NumberConfigPropertyProducer extends BaseConfigPropertyProducer
+{
+ @Produces
+ @Dependent
+ @NumberConfig(name = "unused")
+ public Float produceNumberProperty(InjectionPoint injectionPoint) throws ParseException
+ {
+ // resolve the annotation
+ NumberConfig metaData = getAnnotation(injectionPoint, NumberConfig.class);
+
+ // get the configured value from the underlying configuration system
+ String configuredValue = getPropertyValue(metaData.name(), metaData.defaultValue());
+
+ // format according to the given pattern
+ DecimalFormat df = new DecimalFormat(metaData.pattern(), new DecimalFormatSymbols(Locale.US));
+ return df.parse(configuredValue).floatValue();
+ }
+}
+------------------------------------------------------------------------------------------------------
+
+[source,java]
+-------------------------------------------------------------------
+@Qualifier
+public @interface NumberConfig
+{
+ @Nonbinding
+ String name();
+
+ @Nonbinding
+ String defaultValue() default ConfigProperty.NULL;
+
+ @Nonbinding
+ String pattern() default "#0.00";
+}
+-------------------------------------------------------------------
+
+
+== Providing configuration using ConfigSources
A `ConfigSource` is exactly what its name says: a source for configured
values. The `ConfigResolver` uses all configured implementations of
@@ -164,7 +330,6 @@ pickup the values from within the release binaries.
=== ConfigSources Provided by Default
-
By default there are implementations for the following configuration sources
(listed in the lookup order):
@@ -232,7 +397,7 @@ implementations provided by DeltaSpike do.
==== PropertyFileConfig
For registering all your own property files of a certain name in your
-classpath to get picked up as `ConfigSource`s you can also provide a
+classpath to get picked up as ConfigSources you can also provide a
class which implements the `PropertyFileConfig` interface.
The method `isOptional` indicates whether your custom property file is mandatory.
@@ -275,23 +440,36 @@ dependency to the module that contains the property file._
</jboss-deployment-structure>
---------------------------------------------------------------------------------------------------
-== Type-safe Configuration
+== Filtering configured values
-DeltaSpike provides a way to directly inject configured values into your
-code via the qualifier `@ConfigProperty`.
+It is possible to perform filtering on all configured values on their way between the ConfigSource and user code.
+This might be useful for example for decryption of values from an encrypted ConfigSource or to hide passwords from a
+log.
-------------------------------------------------------
-@ApplicationScoped
-public class SomeRandomService
-{
- @Inject
- @ConfigProperty(name = "endpoint.poll.interval")
- private Integer pollInterval;
+DeltaSpike doesn't provide any filters by default but custom filters can be provided by implementing the
+`ConfigFilter` interface. This is then enabled either using the ServiceLoader mechanism or by calling
+`ConfigResolver.addConfigFilter(ConfigFilter)`. Provided ConfigFilters are then enabled for the whole application.
- @Inject
- @ConfigProperty(name = "endpoint.poll.servername")
- private String pollUrl;
+Once some filters are provided, all operations of ConfigResolver return filtered values.
- ...
- }
-------------------------------------------------------
+.A custom ConfigFilter
+[source,java]
+-------------------------------------------------------------
+public class DecryptingConfigFilter implements ConfigFilter
+{
+ @Override
+ public String filterValue(String key, String value)
+ {
+ if (key.contains("encrypted"))
+ {
+ return decrypt(value);
+ }
+ return value;
+ }
+
+ @Override
+ public String filterValueForLog(String key, String value)
+ {
+ return "<value encrypted>";
+ }
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/documentation/src/main/asciidoc/core.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/core.adoc b/documentation/src/main/asciidoc/core.adoc
index 453b56a..84da0f2 100644
--- a/documentation/src/main/asciidoc/core.adoc
+++ b/documentation/src/main/asciidoc/core.adoc
@@ -2,21 +2,38 @@
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-== Overview
The Core module provides fundamental and defining DeltaSpike API and utility classes. As such, this module must be included in every project that uses DeltaSpike.
+Instructions for configuring your projects to use the DeltaSpike Core module are detailed in
+<<configure#, Configure DeltaSpike in Your Projects>> as part of the general instructions for configuring your projects for DeltaSpike.
-== Configure Your Projects
+== DeltaSpike Configuration
-Instructions for configuring your Maven-based and Maven-independent projects to use the DeltaSpike Core module are detailed in <<configure#, Configure DeltaSpike in Your Projects>> as part of the general instructions for configuring your projects for DeltaSpike.
+DeltaSpike provides a very flexible application configuration mechanism. Its main goal is to make it possible
+to never have to rebuild a project just for the sake of adjusting configuration values. It respects the usual
+software development cycle and takes into account project stages, various configuration sources and resolution
+mechanisms. Configuration can be overridden just by dropping a JAR into the classpath.
-== Use the Module Features
+Detailed documentation is available on a separate page: <<configuration.adoc#,Configuration>>.
-=== Core - API
+=== Internal configuration
-==== DeltaSpike Configuration
-This is described in a separate page solely targeting <<configuration.adoc#,configuration>> mechanics, API and SPI.
+The functionality of DeltaSpike itself and its modules is adjustable using the same mechanism. There are two main
+types of internal configuration:
-==== BeanProvider
+* *static configuration:* certain configurable options, like the maximum number of windows in the window scope or the
+ priority for DeltaSpike's global interceptors, are defined using the DeltaSpike configuration mechanism and can be
+ adjusted by redefining their value in the `apache-deltaspike.properties` file, as described in the
+ <<configuration.adoc#,documentation>>. All of these configuration options and their corresponding properties can be
+ found as members of interfaces extending `DeltaSpikeBaseConfig`, e.g. `CoreBaseConfig` which configures the core
+ module.
+
+* *dynamic configuration:* certain values can change dynamically during runtime and some may differ even among
+contexts. For example, much of the behaviour of the JSF module is configured in `JsfModuleConfig`. To override any of
+ the default configuration options, the `JsfModuleConfig` bean can be overridden using a custom implementation of
+ `JsfModuleConfig` which would be annotated `@Alternative` or `@Specializes`. All of the dynamic CDI-based
+ configuration beans can be found as implementations of the `DeltaSpikeConfig` interface.
+
+== BeanProvider
The `BeanProvider` utility class provides static methods for manual lookup of bean instances in places where
standard injection is not available or if the lookup depends on dynamic conditions.
@@ -122,7 +139,7 @@ fields.
BeanProvider.injectFields(myObject);
------------------------------------
-===== DependentProvider
+=== DependentProvider
`DependentProvider` must be used instead of `BeanProvider` to obtain instances of dependent-scoped beans to allow for
their proper destruction.
@@ -145,7 +162,7 @@ MyBean myBean = myBeanProvider.get();
myBeanProvider.destroy();
-----------------------------------------------------------------------------------
-==== BeanManagerProvider
+== BeanManagerProvider
This mechanism provides access to the `BeanManager` by registering the
current `BeanManager` during the startup. This is really handy if you
@@ -176,7 +193,7 @@ the lookup strategy you used before, you can deactivate the delegation to the co
(e.g. in `/META-INF/apache-deltaspike.properties`).
-==== AnnotationInstanceProvider
+== AnnotationInstanceProvider
Java EE provides a standard mechanism for obtaining annotation instances -- the `AnnotationLiteral` class.
@@ -216,13 +233,13 @@ Annotation exceptionQualifier = AnnotationInstanceProvider.of(jsfModuleConfig.ge
CurrentUser principal = AnnotationInstanceProvider.of(CurrentUser.class);
-------------------------------------------------------------------------
-==== Type-safe ProjectStage
+== Type-safe ProjectStage
The DeltaSpike <<projectstage.adoc#,ProjectStage>> mechanism allows to use configuration and implementations depending on the server environment you currently run on.
DeltaSpike provides some pre-defined <<projectstage.adoc#_introduction,ProjectStages>> but it's also possible to create your own <<projectstage.adoc#_custom_project_stages,Custom Project Stage>>, Please, check the <<projectstage.adoc#,DeltaSpike ProjectStage>> page for more details.
-==== @Exclude
+== @Exclude
With `@Exclude` it is possible to annotate beans which should be ignored
by CDI even if they are in a CDI enabled archive.
@@ -309,7 +326,7 @@ public class MyDevBean
}
---------------------------------------------------------------
-===== Custom ExpressionInterpreter
+=== Custom ExpressionInterpreter
By default only a very simple and limited syntax is supported. In real
projects there are usually quite concrete requirements. Since it would
@@ -349,15 +366,14 @@ public class ConfigAwareExpressionInterpreter implements ExpressionInterpreter<S
}
----------------------------------------------------------------------------------------------------
-==== Type-safe View-Config
-
+== Type-safe View-Config
TODO (Overview)
-==== Literals
+== Literals
Literals allow the instantiation of annotations by extending the
-abstract class 'javax.enterprise.util.AnnotationLiteral'
+abstract class `javax.enterprise.util.AnnotationLiteral`
.Example
[source,java]
@@ -386,7 +402,7 @@ DeltaSpike provides many annotation literals that you can use, including the fol
* SpecializesLiteral
* TypedLiteral
-==== Messages and I18n
+== Messages and i18n
The following implementation is the minimal effort to use type-safe
messages (which are hardcoded in this case).
@@ -477,9 +493,9 @@ public class MyBean
}
----------------------------------------------------------------------------
-==== Dynamic Message Builder
+=== Dynamic Message Builder
-===== Creating Message Instances
+==== Creating Message Instances
The following implementation creates an instance of `Message` for the
key `hello`. The final text will be resolved and interpolated lazily.
@@ -532,9 +548,9 @@ org/apache/deltaspike/example/message/Messages_de.properties
hello=Hello %s from %s
--------------------------------------------------------------------------------------------------------------------
-===== Customizing the Message Context
+==== Customizing the Message Context
-====== MessageResolver
+===== MessageResolver
A message-resolver is responsible for creating the message-text based on
the message-descriptor (key or inline-text), the current locale (and in
@@ -563,7 +579,7 @@ Message message = this.messageContext.messageResolver(new CustomMessageResolver(
The result of a `MessageResolver` is the message-text. The text might
contain placeholders which are processed by a `MessageInterpolator`
-====== MessageInterpolator
+===== MessageInterpolator
A `MessageInterpolator` replaces the placeholders in a message-text with
the arguments of the message.
@@ -584,7 +600,7 @@ private MessageContext messageContext;
Message message = this.messageContext.messageInterpolator(new CustomMessageInterpolator()).message();
-----------------------------------------------------------------------------------------------------
-====== LocaleResolver
+===== LocaleResolver
A locale resolver provides the current locale. The locale is, for example, used
to by a `MessageResolver` to choose the correct language for the
@@ -604,7 +620,7 @@ private MessageContext messageContext;
Message message = this.messageContext.localeResolver(new CustomLocaleResolver()).message();
-------------------------------------------------------------------------------------------
-==== Injecting Resources
+== Injecting Resources
DeltaSpike has simple APIs for performing basic resource loading and
property file reading.
@@ -616,13 +632,19 @@ property file reading.
private InputStream inputStream;
----------------------------------------
-This can be used to read files, from classpath or on your local file
-system, using two default implementations: `ClasspathResourceProvider`
-and `FileResourceProvider`. They can be extended as well by implementing
-the `InjectableResourceProvider` interface to allow reading from
-alternate sources, if needed (e.g. database LOBs, NoSQL storage areas).
+This can be used to read resources from the classpath or from the file
+system using the two default implementations -- `ClasspathResourceProvider`
+and `FileResourceProvider` -- or from any other source using a custom provider.
+
+=== Custom resource providers
-==== Exception Control
+The `InjectableResourceProvider` interface can be implemented to allow reading from
+alternate sources if needed (e.g. database LOBs, NoSQL storage areas). A base class called `AbstractResourceProvider`
+is provided by DeltaSpike and contains most of the methods for potential implementations. The only method which must be
+provided is the `readStream(InjectableResource)` which returns an InputStream.
+
+
+== Exception Control
Exception handling in DeltaSpike is based around the CDI eventing model.
While the implementation of exception handlers may not be the same as a
@@ -643,7 +665,7 @@ developer. In most cases, you register an exception handler simply by
annotating a handler method. Alternatively, you can handle an exception
programmatically, just as you would observe an event in CDI.
-===== Usage
+=== Usage
The entire exception handling process starts with an event. This helps
keep your application minimally coupled to DeltaSpike, but also allows
@@ -681,7 +703,7 @@ your class for use later within a try/catch block.
The event is fired with a new instance of `ExceptionToCatchEvent`
constructed with the exception to be handled.
-===== Exception Handlers
+=== Exception Handlers
As an application developer (i.e., an end user of DeltaSpike's exception
handling), you'll be focused on writing exception handlers. An exception
@@ -720,7 +742,7 @@ methods which have a parameter which is an instance of
`ExceptionEvent<T extends Throwable>` annotated with the `@Handles`
annotation.
-====== @ExceptionHandler
+==== @ExceptionHandler
The `@ExceptionHandler` annotation is simply a marker annotation that
instructs the DeltaSpike exception handling CDI extension to scan the
@@ -738,7 +760,7 @@ public class MyHandlers {}
That's all there is to it. Now we can begin defining exception handling
methods on this bean.
-====== @Handles and @BeforeHandles
+==== @Handles and @BeforeHandles
`@Handles` is a method parameter annotation that designates a method as
an exception handler. Exception handler methods are registered on beans
@@ -845,7 +867,7 @@ unchecked exceptions. Should a handler throw an unchecked exception it
will propagate up the stack and all handling done via DeltaSpike will
cease. Any exception that was being handled will be lost.
-====== Ordinal
+==== Ordinal
When DeltaSpike finds more than one handler for the same exception type,
it orders the handlers by ordinal. Handlers with higher ordinal are
@@ -881,7 +903,7 @@ invoke (until a handler marks exception as handled):
5. If multiple handlers for same type, invoke handlers with higher ordinal first
6. Continue above steps for each exception in stack
-===== Exception Chain Processing
+=== Exception Chain Processing
When an exception is thrown, chances are it is nested (wrapped) inside
other exceptions. (If you've ever examined a server log, you'll
@@ -928,7 +950,7 @@ the handlers for `EJBException` from being invoked, which is a good
thing since what useful information can really be obtained from
`EJBException`?
-===== APIs for Exception Information and Flow Control
+=== APIs for Exception Information and Flow Control
There are two APIs provided by DeltaSpike that should be familiar to
application developers:
@@ -936,7 +958,7 @@ application developers:
* `ExceptionEvent`
* `ExceptionStackEvent`
-====== ExceptionEvent
+==== ExceptionEvent
In addition to providing information about the exception being handled,
the `ExceptionEvent` object contains methods to control the exception
@@ -964,18 +986,18 @@ Once a handler is invoked it is muted, meaning it will not be run again
for that exception chain, unless it is explicitly marked as unmuted via
the `unmute()` method on `ExceptionEvent`.
-==== Scopes
+== Scopes
DeltaSpike Core provides the API and SPI for several scopes. Currently
all scopes are only implemented in the <<jsf.adoc#_scopes,JSF module>>.
-===== @WindowScoped
+=== @WindowScoped
-===== @ViewAccessScoped
+=== @ViewAccessScoped
-===== @GroupedConversationScoped
+=== @GroupedConversationScoped
-==== Creating a Custom CDI Scope
+=== Creating a Custom CDI Scope
To create a custom CDI scope to match your needs, complete the following steps:
@@ -1053,7 +1075,7 @@ public class ACustomScopeContext implements Context, Serializable {
}
-----------------------------------------------------------------------------------------------------
-==== Deactivatable
+== Deactivatable
DeltaSpike allows you to deactivate its own Extensions. You just need to
implement your <<spi.adoc#_classdeactivator,ClassDeactivator>>.
@@ -1088,15 +1110,14 @@ other <<configuration.adoc#_configsources_provided_by_default,ConfigSource>>) wi
org.apache.deltaspike.core.spi.activation.ClassDeactivator=org.test.CustomClassDeactivator
------------------------------------------------------------------------------------------
-=== Core - Utils
-
+== Utilities
DeltaSpike provides many utility classes (no constructor / static
methods) that can be useful for your project.
Below you can find an information about these classes.
-==== AnnotationUtils
+=== AnnotationUtils
Utilities for working with annotations on methods and classes.
@@ -1105,7 +1126,7 @@ Utilities for working with annotations on methods and classes.
* `#extractAnnotationFromMethodOrClass` -- uses `findAnnotation` to obtain an `Annotation` on either the given `Method` or the given `Class`, in that order
* `#getQualifierHashCode` -- computes the hashCode of a qualifier annotation, taking into account only the "binding" members (not annotated `@Nonbinding`)
-==== ArraysUtils
+=== ArraysUtils
A collection of utilities for working with Arrays
@@ -1114,7 +1135,7 @@ A collection of utilities for working with Arrays
objects, the last object in the array will be placed in resultant set.
-==== BeanUtils
+=== BeanUtils
A set of utility methods for working with beans.
@@ -1123,14 +1144,14 @@ A set of utility methods for working with beans.
* `#createInjectionPoints` -- Given a method, and the bean on which the method is declared, create a collection of injection points representing the parameters of the method.
-==== ContextUtils
+=== ContextUtils
A set of utility methods for working with contexts.
* `#isContextActive` -- Checks if the context for the scope annotation is active.
-==== ClassDeactivationUtils
+=== ClassDeactivationUtils
Helper methods for `ClassDeactivator`
@@ -1139,14 +1160,14 @@ Helper methods for `ClassDeactivator`
To add a custom `ClassDeactivator` add `org.apache.deltaspike.core.spi.activation.ClassDeactivator=my.CustomClassDeactivator` to `META-INF\apache-deltaspike.properties`. Or configure it via a custom `ConfigSource`.
-==== ExceptionUtils
+=== ExceptionUtils
Helper methods to deal with Exceptions
* `#throwAsRuntimeException` -- helper which allows to use a trick to throw a catched checked exception without a wrapping exception.
* `#changeAndThrowException` -- helper which allows to use a trick to throw a cached checked exception without a wrapping exception.
-==== PropertyFileUtils
+=== PropertyFileUtils
Helper methods for Property files
@@ -1155,14 +1176,14 @@ Helper methods for Property files
* `#getResourceBundle` -- Return the ResourceBundle for the current default Locale.
-==== ProxyUtils
+=== ProxyUtils
Helper for CDI proxies
* `#getUnproxiedClass` -- Return class of the real implementation.
* `#isProxiedClass` -- Analyses if the given class is a generated proxy class.
-==== StringUtils
+=== StringUtils
A collection of utilities for working with Strings.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/documentation/src/main/asciidoc/jsf.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/jsf.adoc b/documentation/src/main/asciidoc/jsf.adoc
index 90a3d91..ebf25b5 100644
--- a/documentation/src/main/asciidoc/jsf.adoc
+++ b/documentation/src/main/asciidoc/jsf.adoc
@@ -236,7 +236,7 @@ from `window.name`
Any window or browser tab detection will be disabled for the current
request. Scopes like @WindowScoped, @GroupedConversationScoped or
@ViewAccessScoped will not work. This is also the default mode if the
-current request doesis not support Javascript or if the user agent is a
+current request does not support Javascript or if the user agent is a
bot/crawler.
@@ -390,7 +390,7 @@ as the bean is referenced by a page - the bean will be available for the
next page (if it is used again the bean will be forwarded again). It is
important that it is based on the view-id of a page (it is not based on
the request) so, for example, Ajax requests do not trigger a cleanup if the
-request doesis not access all view-access scoped beans of the page. That's
+request does not access all view-access scoped beans of the page. That's
also the reason for the name @__View__AccessScoped.
[source,java]
@@ -641,7 +641,7 @@ inheritance.
In the following example `Pages.Admin.Index`, `Pages.Admin.Home` and
`Pages.Admin.Statistics.Home` inherit the meta-data from `Pages.Admin`
because they implement the interface whereas
-`Pages.Admin.Statistics.Index` doesis not. However, `Pages.Admin.Home`
+`Pages.Admin.Statistics.Index` does not. However, `Pages.Admin.Home`
overrides `View#navigation`. During the bootstrapping process the
meta-data gets merged and at runtime you only see the final result
(which is cached).
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/documentation/src/main/asciidoc/overview.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/overview.adoc b/documentation/src/main/asciidoc/overview.adoc
index c113f70..cd652ae 100644
--- a/documentation/src/main/asciidoc/overview.adoc
+++ b/documentation/src/main/asciidoc/overview.adoc
@@ -2,88 +2,107 @@
: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.
-== Background
-
-=== CDI
-Java Contexts and Dependency Injection for the Java EE platform (link:https://jcp.org/en/jsr/detail?id=299[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 link:https://jcp.org/en/home/index[Java Community Process (JCP)] standard. All Java EE6 compliant application servers must provide support for CDI. link:http://weld.cdi-spec.org/[JBoss Weld] is a reference implementation of the CDI specification and other spec-compliant implementations exist such as link:http://openwebbeans.apache.org/[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.
+DeltaSpike consists of a core module and a number of <<modules.adoc#, 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, a
+transactional context and scope, and much more. 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.
+As a CDI extension, DeltaSpike must be used in conjunction with a CDI implementation and supports both JBoss Weld
+and Apache OpenWebBeans. DeltaSpike is tested on a range of application servers and CDI-enabled containers
+including 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.
+DeltaSpike provides a number of link:http://deltaspike.apache.org/examples.html[examples] to show you how to use and get
+the most from this technology.
-== Features of DeltaSpike
+== Features
=== 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.
+*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 Servlet objects:* Enables CDI injection in Servlets in 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 is 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 cais not use @Vetoed or a veto based on ProjectStages or expressions is needed.
+*@Exclude annotation:* Lets you prevent classes from being treated as CDI beans even if they are in a CDI-enabled
+archive in a Java EE 6/CDI 1.0 environment where `@Vetoed` is unavailable or when you need to veto based on
+ProjectStages or expressions.
-**Scheduling tasks**: Async processes in a non Java EE 7 environment.
+*Scheduling tasks*: Async processes in a non-EE7 environment.
-*Bean Validation integration:* Allows to inject CDI beans and EJB in to Constraint-Validators.
+*Bean Validation integration:* Injection of CDI beans and EJBs into Constraint Validators.
-*BeanProvider:* Access the BeanManager and CDI beans even in non managed classes like JPA-2.0 EntityListeners or Spring Beans.
+*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.
+*Multi-window handling:* Management of logical windows for batch jobs, browser tab separation in JSF and more.
-*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.
+*Type-safe view-config:* Lets you bind metadata (e.g. for security) to views with a flexible type-safe 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.
+*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.
+*Injection in Converters and Validators:* Inject CDI beans and EJBs into 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.
+*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
+*New CDI scopes:* TransactionScoped, WindowScoped, ViewScoped, ViewAccess scope, Grouped conversation scope.
*Container Control and 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.
+*Decoupled Exception handling:* Event-based exception handling framework, similar to the CDI event observer mechanism.
-*JMX integration:* Any CDI bean can be exposed via JMX easily with one annotation.
+*JMX integration:* Any CDI bean can be exposed via JMX easily with a single 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 ProjectStages:* Compared to ProjectStages in JSF, DeltaSpike provides a type-safe, but still extensible approach which can be used in CDI based applications.
+*Type-safe ProjectStages:* Compared to ProjectStages in JSF, DeltaSpike provides a type-safe, but still extensible
+approach which can be used in CDI-based applications.
+
+== Background
+
+=== CDI
+Java Contexts and Dependency Injection for the Java EE platform (link:https://jcp.org/en/jsr/detail?id=299[JSR 299]),
+ abbreviated _CDI_ was introduced as part of Java EE 6. 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 inheritance 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 link:https://jcp.org/en/home/index[Java Community Process (JCP)] standard. All Java EE 6 compliant
+application servers must provide support for CDI. link:http://weld.cdi-spec.org/[JBoss Weld] is a reference
+implementation of the CDI specification and other spec-compliant implementations exist such as link:http://openwebbeans.apache.org/[Apache OpenWebBeans (OWB)]. While CDI is a Java EE 6 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 extension 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.
== Next
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/0b5c027c/documentation/src/main/asciidoc/projectstage.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/projectstage.adoc b/documentation/src/main/asciidoc/projectstage.adoc
index f4b4811..7957ba4 100644
--- a/documentation/src/main/asciidoc/projectstage.adoc
+++ b/documentation/src/main/asciidoc/projectstage.adoc
@@ -100,9 +100,9 @@ determine the string is the ConfigResolver.
`ProjectStageProducer` provides the producer method which allows to
inject the current ProjectStage. However, in some cases it is needed to
use ProjectStages also during the bootstrapping process of the CDI
-container and you cais not use injection. In such cases you can use
+container and you can not use injection. In such cases you can use
`ProjectStageProducer.getInstance().getProjectStage()` to resolve the
current ProjectStage. This helper also contains helpers for unit-tests
-- e.g. `#setProjectStage`. However, those methods shouldis not be needed
+- e.g. `#setProjectStage`. However, those methods should not be needed
for users (we just need them for testing different ProjectStage
scenarios).
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/documentation/src/main/asciidoc/scheduler.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/scheduler.adoc b/documentation/src/main/asciidoc/scheduler.adoc
index 4b7933b..321201f 100644
--- a/documentation/src/main/asciidoc/scheduler.adoc
+++ b/documentation/src/main/asciidoc/scheduler.adoc
@@ -176,4 +176,4 @@ or
=== Custom Scheduler
It is possible to replace the default integration with Quartz. Any scheduler that supports cron-expressions for job-classes can be used.
-For more information, see http://org.apache.deltaspike.test.scheduler.custom.
+For more information, see link:https://deltaspike.apache.org/javadoc/{latestStable}/org/apache/deltaspike/scheduler/spi/Scheduler.html[Scheduler javadoc].
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/documentation/src/main/asciidoc/security.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/security.adoc b/documentation/src/main/asciidoc/security.adoc
index 445f72f..79446be 100644
--- a/documentation/src/main/asciidoc/security.adoc
+++ b/documentation/src/main/asciidoc/security.adoc
@@ -222,7 +222,7 @@ as part of our security authorizer!
`@Secured` is build on `@SecurityBindingType` and a very simple
alternative to the rest of the security module. It is a basic hook to
integrate a custom security concept, third-party frameworks, etc. It
-doesis not provide a full blown security concept like the rest of the
+does not provide a full blown security concept like the rest of the
security module, but other DeltaSpike modules ensure that the security
concepts are integrated properly (e.g. correct behaviour within custom
scope implementations,...). It just allows to integrate other security
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/documentation/src/main/asciidoc/servlet.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/servlet.adoc b/documentation/src/main/asciidoc/servlet.adoc
index fcd64ef..c756e55 100644
--- a/documentation/src/main/asciidoc/servlet.adoc
+++ b/documentation/src/main/asciidoc/servlet.adoc
@@ -37,7 +37,7 @@ listeners and filters are automatically registered in the container.
However there are certain situations in which you will have to manually
register the listeners and filters in your `web.xml`:
-* Your container doesis not support Servlet 3.0 or newer.
+* Your container does not support Servlet 3.0 or newer.
* You have set `metadata-complete=true` in your `web.xml`.
* You packaged the servlet module in the `lib` directory of an EAR archive.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/documentation/src/main/asciidoc/spi.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/spi.adoc b/documentation/src/main/asciidoc/spi.adoc
index fd44764..fda2ded 100644
--- a/documentation/src/main/asciidoc/spi.adoc
+++ b/documentation/src/main/asciidoc/spi.adoc
@@ -6,11 +6,15 @@ DeltaSpike provides an Service Provider Interface (SPI) to enable you to extend
== Deactivatable
-This mechanism is only used for artifacts *like* implementations of (`javax.enterprise.inject.spi.Extension`) which *cais not* be deactivated with standard CDI mechanisms.
+This mechanism is only used for artifacts *like* implementations of (`javax.enterprise.inject.spi.Extension`) which
+*can not* be deactivated with standard 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 isis not needed, to provide a custom implementation if the default implementation isis not 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 is required to implement `ClassDeactivator`. Returning 'false' or 'true' allows to de-/activate the class in question. Retuning null means that the current class-deactivator doesis not have information about the class in question and cais not provide a result. Since `ClassDeactivator` implementations are configured with the low-level configuration of DeltaSpike, the class-deactivator with the highest ordinal has the final decision. DeltaSpike itself doesis not deactivate an implementation, however, an add-on or a third-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.
+To deactivate a class it is required to implement `ClassDeactivator`. Returning 'false' or 'true' allows to
+de-/activate the class in question. Retuning null means that the current class-deactivator does not have
+information about the class in question and can not provide a result. Since `ClassDeactivator` implementations are
+configured with the low-level configuration of DeltaSpike, the class-deactivator with the highest ordinal has the final decision. DeltaSpike itself does not deactivate an implementation, however, an add-on or a third-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.
IMPORTANT: Due to the ordinal feature of the low-level configuration approach it is possible that a class-deactivator with a higher ordinal, for example used in a concrete project, can re-activate a deactivated implementation.
@@ -60,7 +64,8 @@ A class-deactivator will be resolved from the environment via the default resolv
== Global Alternative
-There are several application servers (using CDI 1.0) which cais not handle alternative CDI beans correctly (e.g. due to a too strict interpretation or a broken implementation). Therefore, DeltaSpike allows to use the standard `@Alternative` annotation and an additional configuration 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 not handle alternative CDI beans correctly (e.g. due to
+a too strict interpretation or a broken implementation). Therefore, DeltaSpike allows to use the standard `@Alternative` annotation and an additional configuration entry for DeltaSpike which allows to use the alternative implementation as a global alternative.
.Standard CDI alternative implementation (without the required XML config)
[source,java]
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0b5c027c/documentation/src/main/asciidoc/test-control.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/test-control.adoc b/documentation/src/main/asciidoc/test-control.adoc
index 1c153c6..64e0fc2 100644
--- a/documentation/src/main/asciidoc/test-control.adoc
+++ b/documentation/src/main/asciidoc/test-control.adoc
@@ -232,7 +232,7 @@ easier. Therefore it is possible to create (mock-)instances manually or
via a mocking framework and add them, for example, via `DynamicMockManager`.
**Attention:** Mocking CDI beans is not supported for every feature of CDI and/or
-every implementation version. For example, we cais not mock intercepted CDI beans and
+every implementation version. For example, we can not mock intercepted CDI beans and
with some implementations mocking specialized beans fails.
Usually all features are active by default, however,
due to those reasons we deactivated this feature by default.