You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by ra...@apache.org on 2014/09/16 21:52:34 UTC
[4/4] git commit: DELTASPIKE-716 - Migration from Markdown to Asciidoc
DELTASPIKE-716 - Migration from Markdown to Asciidoc
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/d8d70fe9
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/d8d70fe9
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/d8d70fe9
Branch: refs/heads/master
Commit: d8d70fe9fc9396b293629a2b1f791376358fd781
Parents: 90be543
Author: Rafael Benevides <ra...@gmail.com>
Authored: Thu Sep 11 10:45:36 2014 -0300
Committer: Rafael Benevides <ra...@gmail.com>
Committed: Mon Sep 15 11:12:02 2014 -0300
----------------------------------------------------------------------
documentation/pom.xml | 2 +-
.../src/main/asciidoc/bean-validation.adoc | 46 +
documentation/src/main/asciidoc/build.adoc | 155 ++
.../src/main/asciidoc/configuration.adoc | 297 +++
.../main/asciidoc/container-control-test.adoc | 157 --
.../src/main/asciidoc/container-control.adoc | 201 ++
documentation/src/main/asciidoc/core.adoc | 1113 ++++++++++
documentation/src/main/asciidoc/data.adoc | 1390 +++++++++++++
documentation/src/main/asciidoc/index.adoc | 729 +++++++
documentation/src/main/asciidoc/jpa.adoc | 512 +++++
documentation/src/main/asciidoc/jsf.adoc | 1929 ++++++++++++++++++
.../src/main/asciidoc/partial-bean.adoc | 44 +
.../src/main/asciidoc/projectstage.adoc | 110 +
.../asciidoc/releasenotes/deltaspike_1.0.2.ad | 84 -
.../asciidoc/releasenotes/deltaspike_1.0.2.adoc | 84 +
documentation/src/main/asciidoc/scheduler.adoc | 145 ++
documentation/src/main/asciidoc/security.adoc | 531 +++++
documentation/src/main/asciidoc/servlet.adoc | 285 +++
documentation/src/main/asciidoc/source.adoc | 74 +
documentation/src/main/asciidoc/spi.adoc | 124 ++
.../src/main/asciidoc/test-control.adoc | 416 ++++
.../src/main/template/document.html.erb | 10 +-
22 files changed, 8190 insertions(+), 248 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/pom.xml
----------------------------------------------------------------------
diff --git a/documentation/pom.xml b/documentation/pom.xml
index c7ceb7d..7c166d9 100644
--- a/documentation/pom.xml
+++ b/documentation/pom.xml
@@ -35,7 +35,7 @@
<url>http://deltaspike.apache.org</url>
<properties>
- <asciidoctor.version>0.1.4</asciidoctor.version>
+ <asciidoctor.version>1.5.0</asciidoctor.version>
<svn.scmPubUrl>https://svn.apache.org/repos/asf/deltaspike/site/trunk/content/documentation/</svn.scmPubUrl>
<svn.scmPubCheckoutDirectory>${project.build.directory}/co-site</svn.scmPubCheckoutDirectory>
</properties>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/bean-validation.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/bean-validation.adoc b/documentation/src/main/asciidoc/bean-validation.adoc
new file mode 100644
index 0000000..0210948
--- /dev/null
+++ b/documentation/src/main/asciidoc/bean-validation.adoc
@@ -0,0 +1,46 @@
+= Bean Validation Module
+
+: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
+
+The main feature of the Bean Validation module is to provide CDI
+integration in to `ConstraintValidator`s. This allows you to inject CDI
+objects, EJBs etc in to your validators.
+
+=== Scoping
+
+
+`ConstraintValidator`s will inherit whatever scope as defined in the
+bean class. Inherently, a `ConstraintValidator` may be invoked by
+multiple threads so please keep that in mind when using them. You should
+consider using at least `RequestScoped` validators.
+
+
+=== Code Requirements
+
+
+There are no compile dependencies to use the Bean Validation module. You
+simply need to override the factory, either in Java:
+
+[source,java]
+------------------------------------------------------------------------------------------------
+Validation.byDefaultProvider().configure().constraintValidatorFactory(new CDIAwareConstraintValidatorFactory()).buildValidatorFactory()
+-------------------------------------------------------------------------------------------------
+
+Or in XML:
+
+[source,xml]
+------------------------------------------------------------------------------------------------------------------------
+:::xml
+<validation-config xmlns="http://jboss.org/xml/ns/javax/validation/configuration"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/configuration">
+ <constraint-validator-factory>org.apache.deltaspike.beanvalidation.impl.CDIAwareConstraintValidatorFactory</constraint-validator-factory>
+</validation-config>
+------------------------------------------------------------------------------------------------------------------------
+
+And then you can simply build your `ConstraintValidator`s based on CDI
+programming rules.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/build.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/build.adoc b/documentation/src/main/asciidoc/build.adoc
new file mode 100644
index 0000000..48fb04b
--- /dev/null
+++ b/documentation/src/main/asciidoc/build.adoc
@@ -0,0 +1,155 @@
+= Building DeltaSpike from 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
+
+Deltaspike uses http://maven.apache.org/[maven] build tool to automate the compilation, testing and packaging of the project
+
+=== Full build
+
+-----------------
+mvn clean install
+-----------------
+
+=== Build with test
+
+
+------------------------------------------------------------------
+mvn clean install -POWB //execute the unit tests with OpenWebBeans
+or
+mvn clean install -PWeld //execute the unit tests with Weld
+------------------------------------------------------------------
+
+
+=== Integration Tests
+
+
+With the unpack Maven-Plugin all Arquillian-Tests get copied to the
+integration-test module. Together with the special integration-tests
+they get executed via a remote container. Currently we have
+configurations for the following containers.
+
+
+==== TomEE
+
+
+*Executing the Arquillian tests with Apache TomEE*
+
+---------------------------------------
+mvn clean install -Ptomee-build-managed
+---------------------------------------
+
+
+==== JBoss AS7
+
+
+===== Without existing AS7
+
+
+*Executing the Arquillian tests with JBoss AS7 (without AS7 installation)*
+
+-------------------------------------------
+mvn clean install -Pjbossas-build-managed-7
+-------------------------------------------
+
+===== With existing AS7
+
+
+Set JBoss_HOME
+
+*Executing the Arquillian tests with JBoss AS7 (AS7 installation
+required)*
+
+-------------------------------------
+mvn clean install -Pjbossas-managed-7
+-------------------------------------
+
+
+==== WildFly 8
+
+
+===== Without existing WF8
+
+
+*Executing the Arquillian tests with JBoss-WF8 (without WF8 installation)*
+
+-----------------------------------------
+mvn clean install -Pwildfly-build-managed
+-----------------------------------------
+
+
+===== With existing WF8
+
+
+Set WILDFLY_HOME
+
+*Executing the Arquillian tests with JBoss-WF8 (WF8 installation
+required)*
+
+-----------------------------------
+mvn clean install -Pwildfly-managed
+-----------------------------------
+
+
+==== GlassFish 3.1
+
+
+
+===== Without existing GF3
+
+*Executing the Arquillian tests with GF3 (without GF3 installation)*
+
+---------------------------------------------
+mvn clean install -Pglassfish-build-managed-3
+---------------------------------------------
+
+
+===== With existing GF3
+
+Install GlassFish (default setup without admin-password) and start
+GlassFish with asadmin start-domain *and* asadmin start-database
+
+*Executing the Arquillian tests with Oracle Glassfish 3.1+*
+
+----------------------------------------
+mvn clean install -Pglassfish-remote-3.1
+----------------------------------------
+
+
+==== GlassFish 4
+
+===== Without existing GF4
+
+*Executing the Arquillian tests with GF4 (without GF4 installation)*
+
+---------------------------------------------
+mvn clean install -Pglassfish-build-managed-4
+---------------------------------------------
+
+
+==== WebLogic 12c
+
+
+Install WebLogic 12c. Start Confiuration Wizard to create a new basic
+WebLogic Domain. Default options and domain name = base_domain,
+administrator user name = weblogic1, administrator password = weblogic1.
+Set WLS_HOME so that %WLS_HOME%.jar exists. Start the domain.
+
+*Executing the Arquillian tests with Oracle WebLogic 12c*
+
+----------------------------------
+mvn clean install -Pwls-remote-12c
+----------------------------------
+
+
+=== Jenkins Builds
+
+https://builds.apache.org/view/A-D/view/DeltaSpike/
+
+
+=== Sonar
+
+https://analysis.apache.org/dashboard/index/org.apache.deltaspike:deltaspike-project
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/configuration.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/configuration.adoc b/documentation/src/main/asciidoc/configuration.adoc
new file mode 100644
index 0000000..7f3e114
--- /dev/null
+++ b/documentation/src/main/asciidoc/configuration.adoc
@@ -0,0 +1,297 @@
+= DeltaSpike Configuration Mechanism
+
+: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]
+
+== Configuration Basics
+
+
+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
+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
+propagated to the Staging environment and finally (if all people are
+happy with it) will get moved to the Production system. And all this
+without any changes on the binary itself!
+
+The Apache DeltaSpike configuration system makes this possible by
+providing a default configuration inside the binary and allowing to
+amend this configuration (e.g. database credentials, some URLs from
+remote REST or SOAP endpoints, etc) from outside like environment
+settings, JNDI or the current <<projectstage.adoc#,ProjectStage>>.
+
+
+=== Drop-In Configuration
+
+This mechanism also allows for dynamic configuration in case of a JAR
+drop-in. By adding some JAR to the classpath, all it's contained
+configuration will get picked up and considered in the property value
+evaluation. You could also use this mechanism to switch implementations
+of some SPI (Service Provider Interface) in your own code.
+
+=== CDI-Extension Configuration
+
+In some cases low-level configs are needed e.g. during the bootstrapping
+process of the CDI container.
+
+The good news: our DeltaSpike configuration mechanism does not rely on
+any other EE mechanism to be booted. Which means it can perfectly get
+used to even configure those parts itself. Since the mechanism doesn't
+rely on CDI it can for example be used to configure CDI-Extensions.
+
+Currently this is e.g. used to configure the value of the current <<projectstage.adoc#,ProjectStage>>, configured values which can be
+used in the expressions for `@Exclude`, 'Deactivatable', etc. DeltaSpike
+needs such a low-level approach for several features internally, but
+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.
+
+
+== ConfigResolver
+
+
+The `ConfigResolver` is the central point to pick up configured values
+in DeltaSpike.
+
+=== 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.
+
+`ConfigResolver#getAllPropertyValues(String key)` has a similar contract
+but it returns a list which might be empty if there are no configured
+values for the given key.
+
+This is a code excerpt about how to do a simple lookup in the deltaspike
+configuration:
+
+[source,java]
+-------------------------------------------------------------------------------
+String dbUserName = ConfigResolver.getPropertyValue("databaseconfig.username");
+-------------------------------------------------------------------------------
+
+
+=== 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.
+
+This is done by first looking up the ProjectStage (this internally
+happens with the DeltaSpike ConfigResolver as well) and then go down the
+following lookup chain until we found a configured value.
+
+* key + '.' + projectStage , e.g. "databaseconfig.username.Production"
+* key alone , e.g. "databaseconfig.username"
+
+=== getPropertyAwarePropertyValue()
+
+The method
+`ConfigResolver#getProjectStageAwarePropertyValue(String key, String property)`
+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:
+
+* propertyValue = property + '.' + projectStage, e.g. "dbvendor.Production"
+* if nothing found: propertyValue = property, e.g. "dbvendor"
+
+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, e.g. "databaseconfig.username"
+
+
+=== 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
+final result is an empty String.
+
+*Performance Hint:*
+
+The only `ConfigResolver` operation which is cached is the determination
+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 e.g. implement a
+`JmxConfigSource` (not yet part of DeltaSpike, but easily
+implementable).
+
+
+== ConfigSource
+
+A `ConfigSource` is exactly what it's name says: a source for configured
+values. The `ConfigResolver` uses all configured implementations of
+`ConfigSource` to lookup the property in question.
+
+Each 'ConfigSource' has a specified 'ordinal' which can be configured
+using the key `deltaspike_ordinal`. This ordinal get's used to determine
+the importance of the values taken from the very ConfigSource. A higher
+ordinal means that the values taken from this ConfigSource will override
+values from less important ConfigSources. This is the trick which allows
+to amend configuration from outside a binary - given those outside
+ConfigSources have a higher `deltaspike_ordinal` than the ones who
+pickup the values from within the release binaries.
+
+=== ConfigSources provided by default
+
+
+Per default there are implementations for the following config sources
+(listed in the lookup order):
+
+* System properties (deltaspike_ordinal = 400)
+* Environment properties (deltaspike_ordinal = 300)
+* JNDI values (deltaspike_ordinal = 200, the base name is "java:comp/env/deltaspike/")
+* Properties file values (apache-deltaspike.properties) (deltaspike_ordinal = 100, default filename is "META-INF/apache-deltaspike.properties")
+
+*It's possible to change this order and to add custom config sources.*
+
+*Note:* Important Hints esp. for custom implementations: - The
+config-source with the highest ordinal gets used first. - If a custom
+implementation should be invoked _before_ the default implementations,
+use an ordinal-value > 400 - If a custom implementation should be
+invoked _after_ the default implementations, use an ordinal-value < 100
+- The `ConfigResolver` performs no caching. If your custom ConfigSource
+operation is expensive, then you might think about introducing some
+caching.
+
+
+=== Reordering of the default order of Config-Sources
+
+To change the lookup order, you have to configure the ordinal in the
+corresponding config source (e.g. to change the config ordinal of the
+config source for system properties, you have to set the system property
+with the ordinal key 'deltaspike_ordinal' and the new value).
+
+Example with `/META-INF/apache-deltaspike.properties`: If the properties
+file/s should be used *before* the other implementations, you have to
+configure an ordinal > 400. That means, you have to add e.g.
+`deltaspike_ordinal=401`.
+
+Each single property file is treated as own `ConfigSource` and thus can
+have different `deltaspike_ordinal` values!
+
+*Hint:*
+
+In case of *property files* which are supported by default
+(`/META-INF/apache-deltaspike.properties`) every file is handled as
+independent config-source, but all of them have ordinal 400 by default
+(and can be reordered in a fine-grained manner).
+
+=== Custom Config-Sources
+
+
+ConfigSources are picked up using the `java.util.ServiceLoader'
+mechanism.
+
+To add a custom config-source, you have to implement the interface
+`ConfigSource` and register your implementation in a file
+`/META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSource`
+by writing the fully qualified class name of the custom implementation/s
+into it.
+
+If you need dynamic ConfigSources you can also register a
+`ConfigSourceProvider` in a similar way. This is useful if you like to
+dynamically pick up multiple ConfigSources of the same kind. E.g. if you
+like to pick up all `myproject.properties` files from all the JARs in
+your classpath.
+
+Please note that a single `ConfigSource` should be either registered
+directly or via a `ConfigSourceProvider`, but never both ways.
+
+*Important Hint:*
+
+Have a look at the abstract base-implementation of `ConfigSource`
+DeltaSpike is using internally, if a custom implementation should load
+the ordinal value from the config-source like the default
+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
+class which implements the `PropertyFileConfig` interface.
+
+[source,java]
+---------------------------------------------------------------------
+public class MyCustomPropertyFileConfig implements PropertyFileConfig
+{
+ @Override
+ public String getPropertyFileName()
+ {
+ return "myconfig.properties";
+ }
+}
+---------------------------------------------------------------------
+
+_Note: If you are using WildFly with EAR packaging and with
+ear-subdeployments-isolated=true, then your EAR should have a deployment
+dependency to the module that contains the property file._
+
+[source,xml]
+---------------------------------------------------------------------------------------------------
+<jboss-deployment-structure>
+ <ear-subdeployments-isolated>true</ear-subdeployments-isolated>
+ <deployment>
+ <dependencies>
+ <!-- This module contains the custom PropertyFileConfig and the property file -->
+ <module name="deployment.yourproject.ear.yoursubmodule.jar" meta-inf="import" />
+ </dependencies>
+ </deployment>
+</jboss-deployment-structure>
+---------------------------------------------------------------------------------------------------
+
+== Type-safe configuration
+
+DeltaSpike provides a way to directly inject configured values into your
+code via the qualifier `@ConfigProperty`.
+
+------------------------------------------------------
+@ApplicationScoped
+public class SomeRandomService
+{
+ @Inject
+ @ConfigProperty(name = "endpoint.poll.interval")
+ private Integer pollInterval;
+
+ @Inject
+ @ConfigProperty(name = "endpoint.poll.servername")
+ private String pollUrl;
+
+ ...
+ }
+------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/container-control-test.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/container-control-test.adoc b/documentation/src/main/asciidoc/container-control-test.adoc
deleted file mode 100644
index fc420ed..0000000
--- a/documentation/src/main/asciidoc/container-control-test.adoc
+++ /dev/null
@@ -1,157 +0,0 @@
-= Container & Control
-
-:toc:
-
-== Introduction
-
-There are basically two parts:
-
- - The `CdiContainer` interface allows to boot and shutdown the CDI container in SE applications.
- - The `ContextControl` interface allows to control the life-cycle of the built-in contexts of the CDI container.
-
-=== CdiContainer
-You can use the `CdiContainerLoader` as a simple factory to gain access to the underlying `CdiContainer` implementation. This is of little interest for Java EE applications since the CDI Container
-already gets properly booted and shut down by the Servlet container integration.
-
-
-[source,java]
-----
-// this will give you a CdiContainer for Weld or OWB, depending on the jar you added
-CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
-// now we gonna boot the CDI container. This will trigger the classpath scan, etc
-cdiContainer.boot();
-// and finally we like to start all built-in contexts
-cdiContainer.getContextControl().startContexts();
-// now we can use CDI in our SE application.
-// And there is not a single line of OWB or Weld specific code in your project!
-// finally we gonna stop the container
-cdiContainer.shutdown();
-----
-
-=== ContextControl usage
-
-The `ContextControl` interface allows you to start and stop built-in standard Contexts like `@RequestScoped`, `@ConversationScoped`, `@SessionScoped`, etc. It is provided as `@Dependent` bean and can get injected in the classic CDI way. This is not only usable in Java SE projects but also very helpful in Servlets and Java EE containers.
-
-**Restarting the RequestContext in unit tests**
-
-In unit testing it can be necessary to test with attached and also with detached JPA entities. A very common approach for
-JPA is the link: http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Server/1.0/html/Hibernate_Entity_Manager_Reference_Guide/transactions.html[entitymanager-per-request approach^]
-and thus have a producer method which creates a `@RequestScoped EntityManager`. Since a single unit test is usually
-treated as one ‘request’ a problem arises detaching entities.
-
-Using ContextControl to detach entities:
-
-[source,java]
-----
-@Test
-public void testMyBusinessLogic()
-{
- doSomeJpaStuff()
- MyEntity me = em.find(...);
- ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
- //stopping the request context will dispose the @RequestScoped EntityManager
- ctxCtrl.stopContext(RequestScoped.class);
- // and now immediately restart the context again
- ctxCtrl.startContext(RequestScoped.class);
- // the entity 'em' is now in a detached state!
- doSomeStuffWithTheDetachedEntity(em);
-}
-----
-
-Attaching a Request Context to a new thread in EE
-
-Accessing the `@RequestScoped` bean in a new thread will result in a `ContextNotActiveException`. The request-context usually gets started for a particular thread via a simple `ServletRequestListener`. So "no servlet-request" means that there is no Servlet-Context for the current (/new) Thread.
-You might face such issues, if you would like to reuse business services in e.g. a Quartz Job.
-
-Controlling the request-context for a Quartz-Job:
-
-[source,java]
-----
-public class CdiJob implements org.quartz.Job
-{
- public void execute(JobExecutionContext context) throws JobExecutionException
- {
- ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
- //this will implicitly bind a new RequestContext to the current thread
- ctxCtrl.startContext(RequestScoped.class);
- try
- {
- doYourWork();
- }
- finally
- {
- //stop the RequestContext to ensure that all request-scoped beans get cleaned up.
- ctxCtrl.stopContext(RequestScoped.class);
- }
- }
-}
-----
-
-=== Embedded Servlet Support
-
-Starting with 1.0.2, you can use DeltaSpike to power embedded Servlet runtimes. This work is done via Servlet Listeners. The configuration is specific to each container, below are some examples.
-
-The two main listeners are `CdiServletRequestListener` and `CdiServletContextListener`. `CdiServletRequestListener` is responsible for starting a `RequestContext` on each incoming request. In most containers this is all you need. For Tomcat specifically, you need to use `CdiServletContextListener` which registers the `CdiServletRequestListener`.
-
-The main usecase for this feature is for lightweight embedded runtimes, microservices. For each of these, it is assumed that you are using the following start up code somewhere:
-
-[source,java]
-----
-CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
-cdiContainer.boot();
-cdiContainer.getContextControl().startContexts();
-----
-
-==== Jetty
-For Jetty, you need to add an `EventListener` which will be your `CdiServletRequestListener`. The object must be instantiated. This must be done before the server is started.
-
-[source,java]
-----
-Server server = new Server(port);
-ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
-context.setContextPath("/");
-server.setHandler(context);
-context.addEventListener(new CdiServletRequestListener());
-context.addServlet(new ServletHolder(new YourServlet()),"/*");
-server.start();
-----
-
-==== Undertow
-For Undertow, you register the `CdiServletRequestListener` via `ListenerInfo` by passing in the class to their builders. Then you add the `ListenerInfo` to your deployment before starting.
-
-[source,java]
-----
-ServletInfo servletInfo = Servlets.servlet("YourServletName", YourServlet.class).setAsyncSupported(true)
- .setLoadOnStartup(1).addMapping("/*");
-ListenerInfo listenerInfo = Servlets.listener(CdiServletRequestListener.class); // <1>
-DeploymentInfo di = new DeploymentInfo()
- .addListener(listenerInfo) // <2>
- .setContextPath("/")
- .addServlet(servletInfo).setDeploymentName("CdiSEServlet")
- .setClassLoader(ClassLoader.getSystemClassLoader());
-DeploymentManager deploymentManager = Servlets.defaultContainer().addDeployment(di);
-deploymentManager.deploy();
-Undertow server = Undertow.builder()
- .addHttpListener(port, "localhost")
- .setHandler(deploymentManager.start())
- .build();
-server.start();
-----
-<1> Register as a listener.
-<2> Add to deployment
-
-==== Tomcat
-For Tomcat, you need to register the `CdiServletContextListener` instead of the `CdiServletRequestListener`. It is added as an `ApplicationListener` by passing in the class name as a `String`.
-
-[source,java]
-----
-Tomcat tomcat = new Tomcat();
-tomcat.setPort(port);
-File base = new File("...");
-Context ctx = tomcat.addContext("/",base.getAbsolutePath());
-StandardContext standardContext = (StandardContext)ctx;
-standardContext.addApplicationListener(CdiServletContextListener.class.getName());
-Wrapper wrapper = Tomcat.addServlet(ctx,"YourServlet",YourServlet.class.getName());
-wrapper.addMapping("/*");
-tomcat.start();
-----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/container-control.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/container-control.adoc b/documentation/src/main/asciidoc/container-control.adoc
new file mode 100644
index 0000000..0298553
--- /dev/null
+++ b/documentation/src/main/asciidoc/container-control.adoc
@@ -0,0 +1,201 @@
+= Container & Control
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+[TOC]
+
+== Introduction
+
+There are basically two parts:
+
+* The `CdiContainer` interface allows to boot and shutdown the CDI container in SE applications.
+* The `ContextControl` interface allows to control the life-cycle of the built-in contexts of the CDI container.
+
+=== CdiContainer
+
+You can use the `CdiContainerLoader` as a simple factory to gain access
+to the underlying `CdiContainer` implementation. This is of little
+interest for Java EE applications since the CDI Container already gets
+properly booted and shut down by the Servlet container integration.
+
+[source,java]
+------------------------------------------------------------------------------------
+// this will give you a CdiContainer for Weld or OWB, depending on the jar you added
+CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
+
+// now we gonna boot the CDI container. This will trigger the classpath scan, etc
+cdiContainer.boot();
+
+// and finally we like to start all built-in contexts
+cdiContainer.getContextControl().startContexts();
+
+// now we can use CDI in our SE application.
+// And there is not a single line of OWB or Weld specific code in your project!
+
+// finally we gonna stop the container
+cdiContainer.shutdown();
+------------------------------------------------------------------------------------
+
+=== ContextControl usage
+
+
+The `ContextControl` interface allows you to start and stop built-in
+standard Contexts like `@RequestScoped`, `@ConversationScoped`,
+`@SessionScoped`, etc. It is provided as `@Dependent` bean and can get
+injected in the classic CDI way. This is not only usable in Java SE
+projects but also very helpful in Servlets and Java EE containers.
+
+*Restarting the RequestContext in unit tests*
+
+In unit testing it can be necessary to test with attached and also with
+detached JPA entities. A very common approach for JPA is the
+http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Server/1.0/html/Hibernate_Entity_Manager_Reference_Guide/transactions.html[entitymanager-per-request
+approach] and thus have a producer method which creates a @RequestScoped
+EntityManager. Since a single unit test is usually treated as one
+‘request’ a problem arises detaching entities.
+
+Using ContextControl to detach entities:
+
+[source,java]
+---------------------------------------------------------------------------------------
+@Test
+public void testMyBusinessLogic()
+{
+ doSomeJpaStuff()
+ MyEntity me = em.find(...);
+
+ ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
+
+ //stopping the request context will dispose the @RequestScoped EntityManager
+ ctxCtrl.stopContext(RequestScoped.class);
+
+ // and now immediately restart the context again
+ ctxCtrl.startContext(RequestScoped.class);
+
+ // the entity 'em' is now in a detached state!
+ doSomeStuffWithTheDetachedEntity(em);
+}
+---------------------------------------------------------------------------------------
+
+Attaching a Request Context to a new thread in EE
+
+Accessing the `@RequestScoped` bean in a new thread will result in a
+`ContextNotActiveException`. The request-context usually gets started
+for a particular thread via a simple `ServletRequestListener`. So "no
+servlet-request" means that there is no Servlet-Context for the current
+(/new) Thread. You might face such issues, if you would like to reuse
+business services in e.g. a Quartz Job.
+
+Controlling the request-context for a Quartz-Job:
+
+[source,java]
+---------------------------------------------------------------------------------------------
+public class CdiJob implements org.quartz.Job
+{
+ public void execute(JobExecutionContext context) throws JobExecutionException
+ {
+ ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
+
+ //this will implicitly bind a new RequestContext to the current thread
+ ctxCtrl.startContext(RequestScoped.class);
+
+ try
+ {
+ doYourWork();
+ }
+ finally
+ {
+ //stop the RequestContext to ensure that all request-scoped beans get cleaned up.
+ ctxCtrl.stopContext(RequestScoped.class);
+ }
+ }
+}
+---------------------------------------------------------------------------------------------
+
+=== Embedded Servlet Support
+
+Starting with 1.0.2, you can use DeltaSpike to power embedded Servlet
+runtimes. This work is done via Servlet Listeners. The configuration is
+specific to each container, below are some examples.
+
+The two main listeners are `CdiServletRequestListener` and
+`CdiServletContextListener`. `CdiServletRequestListener` is responsible
+for starting a `RequestContext` on each incoming request. In most
+containers this is all you need. For Tomcat specifically, you need to
+use `CdiServletContextListener` which registers the
+`CdiServletRequestListener`.
+
+The main usecase for this feature is for lightweight embedded runtimes,
+microservices. For each of these, it is assumed that you are using the
+following start up code somewhere:
+
+[source,java]
+-----------------------------------------------------------------
+CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
+cdiContainer.boot();
+cdiContainer.getContextControl().startContexts();
+-----------------------------------------------------------------
+
+==== Jetty
+
+For Jetty, you need to add an `EventListener` which will be your
+`CdiServletRequestListener`. The object must be instantiated. This must
+be done before the server is started.
+
+[source,java]
+------------------------------------------------------------------------------------------
+Server server = new Server(port);
+ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
+context.setContextPath("/");
+server.setHandler(context);
+
+context.addEventListener(new CdiServletRequestListener());
+context.addServlet(new ServletHolder(new YourServlet()),"/*");
+
+server.start();
+------------------------------------------------------------------------------------------
+
+==== Undertow
+
+For Undertow, you register the `CdiServletRequestListener` via
+`ListenerInfo` by passing in the class to their builders. Then you add
+the `ListenerInfo` to your deployment before starting.
+
+[source,java]
+--------------------------------------------------------------------------------------------------------
+ServletInfo servletInfo = Servlets.servlet("YourServletName", YourServlet.class).setAsyncSupported(true)
+ .setLoadOnStartup(1).addMapping("/*");
+ListenerInfo listenerInfo = Servlets.listener(CdiServletRequestListener.class);
+DeploymentInfo di = new DeploymentInfo()
+ .addListener(listenerInfo)
+ .setContextPath("/")
+ .addServlet(servletInfo).setDeploymentName("CdiSEServlet")
+ .setClassLoader(ClassLoader.getSystemClassLoader());
+DeploymentManager deploymentManager = Servlets.defaultContainer().addDeployment(di);
+deploymentManager.deploy();
+Undertow server = Undertow.builder()
+ .addHttpListener(port, "localhost")
+ .setHandler(deploymentManager.start())
+ .build();
+server.start();
+--------------------------------------------------------------------------------------------------------
+
+==== Tomcat
+
+
+For Tomcat, you need to register the `CdiServletContextListener` instead
+of the `CdiServletRequestListener`. It is added as an
+`ApplicationListener` by passing in the class name as a `String`.
+
+[source,java]
+-----------------------------------------------------------------------------------
+Tomcat tomcat = new Tomcat();
+tomcat.setPort(port);
+File base = new File("...");
+Context ctx = tomcat.addContext("/",base.getAbsolutePath());
+StandardContext standardContext = (StandardContext)ctx;
+standardContext.addApplicationListener(CdiServletContextListener.class.getName());
+Wrapper wrapper = Tomcat.addServlet(ctx,"YourServlet",YourServlet.class.getName());
+wrapper.addMapping("/*");
+tomcat.start();
+-----------------------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/core.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/core.adoc b/documentation/src/main/asciidoc/core.adoc
new file mode 100644
index 0000000..043eee5
--- /dev/null
+++ b/documentation/src/main/asciidoc/core.adoc
@@ -0,0 +1,1113 @@
+= Core
+
+: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]
+
+== Core - API
+
+
+=== DeltaSpike Configuration
+
+
+This is described in an own chapter solely targeting our <<configuration.adoc#,configuration>> mechanics, API and SPI.
+
+=== BeanProvider
+
+
+The `BeanProvider` is a class which provides (static) util methods which
+allow to lookup beans if it isn't possible to inject them via `@Inject`
+or if the lookup depends on dynamic conditions. Instead of using the
+term 'bean', the term 'contextual instance' is used because that's the
+term used by CDI itself.
+
+The following example shows a simple lookup. With the second parameter
+it's possible to specify if the contextual instance is optional. If it
+isn't expected that the contextual instance is optional, but no instance
+has been found, an `IllegalStateException` will be thrown.
+
+Resolving a simple contextual instance:
+
+[source,java]
+-------------------------------------------------------------------------
+MyBean myBean = BeanProvider.getContextualReference(MyBean.class, false);
+-------------------------------------------------------------------------
+
+Pass `true` as second argument, if you look for an implementation of the
+given interface and an implementation isn't required or it isn't
+required that there is an instance with the given qualifier (see the
+qualifier example for further details).
+
+Resolving an optional contextual instance:
+
+[source,java]
+---------------------------------------------------------------------------------------------------------
+MyServiceInterface optionalService = BeanProvider.getContextualReference(MyServiceInterface.class, true);
+---------------------------------------------------------------------------------------------------------
+
+Optionally you can provide a qualifier for the contextual instance in
+question. CDI qualifiers are annotations, therefore you need to
+implement a corresponding literal for providing an instance.
+
+Literal implementation for '@MyQualifier':
+
+[source,java]
+---------------------------------------------------------------------------------------------
+import javax.enterprise.util.AnnotationLiteral;
+//...
+
+public class MyQualifierLiteral extends AnnotationLiteral<MyQualifier> implements MyQualifier
+{
+}
+---------------------------------------------------------------------------------------------
+
+The following example will return a contextual instance with the
+qualifier `@MyQualifier`
+
+Resolving a simple contextual instance with qualifier:
+
+[source,java]
+---------------------------------------------------------------------------------------------------
+MyBean myBean = BeanProvider.getContextualReference(MyBean.class, false, new MyQualifierLiteral());
+---------------------------------------------------------------------------------------------------
+
+The `@Named` qualifier has a special role and allows to specify a string
+based name (e.g. for referencing CDI beans in EL-expressions). However,
+the following examples show how to do a manual lookup by name.
+
+Resolving a simple contextual instance by name:
+
+[source,java]
+---------------------------------------------------------------------
+Object myBean = BeanProvider.getContextualReference("myBean", false);
+---------------------------------------------------------------------
+
+Resolving a simple contextual instance by name and expected type:
+
+[source,java]
+-----------------------------------------------------------------------------------
+MyBean myBean = BeanProvider.getContextualReference("myBean", false, MyBean.class);
+-----------------------------------------------------------------------------------
+
+Sometimes it's essential to resolve all contextual instances which
+implement e.g. an interface or all beans with the same type but a
+different qualifier. The following example shows how to do such a lookup
+which returns all contextual instances (independent of the scope -> also
+dependent scoped instances).
+
+Resolving all contextual instances of a given type:
+
+[source,java]
+---------------------------------------------------------------------------------------------------------------
+List<MyServiceInterface> myServiceList = BeanProvider.getContextualReferences(MyServiceInterface.class, false);
+---------------------------------------------------------------------------------------------------------------
+
+Since dependent scoped beans have a special role in CDI (you have to
+destroy them manually - esp. if you get them via a manual lookup), you
+can also call the previous util method with an additional parameter to
+filter dependent scoped instances.
+
+Resolving all contextual instances of a given type without dependent
+scoped instances:
+
+[source,java]
+----------------------------------------------------------------------------------------------------------------------
+List<MyServiceInterface> myServiceList = BeanProvider.getContextualReferences(MyServiceInterface.class, false, false);
+----------------------------------------------------------------------------------------------------------------------
+
+Furthermore, it's possible to trigger the injection of fields of any
+given instance, if it wasn't done by the container (e.g. because the
+class is in a jar-file without beans.xml) and `@Inject` is used for 1-n
+fields.
+
+Manually inject fields:
+
+[source,java]
+------------------------------------
+BeanProvider.injectFields(myObject);
+------------------------------------
+
+=== BeanManagerProvider
+
+This mechanism provides access to the `BeanManager` by registering the
+current `BeanManager` during the startup. This is really handy if you
+like to access CDI functionality from places where no CDI based
+injection is available. If a simple but manual bean-lookup is needed,
+it's easier to use the `BeanProvider`.
+
+Resolving the Bean-Manager:
+
+[source,java]
+-----------------------------------------------------------------------------
+//in most cases the following works without problems:
+@Inject
+private BeanManager beanManager;
+
+//use
+BeanManager beanManager = BeanManagerProvider.getInstance().getBeanManager();
+
+//if CDI based injection is not available.
+-----------------------------------------------------------------------------
+
+=== Type-safe ProjectStage
+
+
+The DeltaSpike <<projectstage.adoc#,ProjectStage>> mechanism allows to
+use configuration and implementations depending on the server
+environment you currently run on.
+
+=== @Exclude
+
+
+With `@Exclude` it's possible to annotate beans which should be ignored
+by CDI even if they are in a CDI enabled archive.
+
+Excluding a bean in any case:
+
+[source,java]
+-------------------
+@Exclude
+public class NoBean
+{
+}
+-------------------
+
+Excluding a bean in case of project-stage development:
+
+[source,java]
+---------------------------------------------------------
+@Exclude(ifProjectStage = ProjectStage.Development.class)
+public class MyBean
+{
+}
+---------------------------------------------------------
+
+Excluding a bean if the project-stage is different from development:
+
+[source,java]
+---------------------------------------------------------------
+@Exclude(exceptIfProjectStage = ProjectStage.Development.class)
+public class MyDevBean
+{
+}
+---------------------------------------------------------------
+
+The following usage allows to exclude a bean based on a configured value
+(see the <<configuration.adocl#_configsources_provided_by_default,supported config sources>>).
+
+Excluding a bean based on an expression which eval. to true:
+
+[source,java]
+-------------------------------------
+@Exclude(onExpression = "db==prodDB")
+public class DevDbBean
+{
+}
+-------------------------------------
+
+By default a simple syntax is supported ([TODO]), however, it's possible
+to provide a custom `ExpressionInterpreter` for interpreting custom
+expressions.
+
+Excluding a bean based on a custom expression:
+
+[source,java]
+------------------------------------------------------------------------------------------
+@Exclude(onExpression = "db eq prodDB", interpretedBy = SimpleExpressionInterpreter.class)
+public class DevDbBean
+{
+}
+
+public class SimpleExpressionInterpreter implements ExpressionInterpreter<String, Boolean>
+{
+ @Override
+ public Boolean evaluate(String expression)
+ {
+ if(expression.contains(" eq "))
+ {
+ //...
+ }
+ //...
+ }
+}
+------------------------------------------------------------------------------------------
+
+In several cases it's also useful to combine this feature with the
+`@Alternative` annotation provided by CDI.
+
+In addition to the following snippet, it's required to configure the
+implementation as alternative in the beans.xml file. This config entry
+won't be changed e.g. for different environments, because it just gets
+active if it isn't excluded during the bootstrapping process.
+
+Excluding an alternative implementation if the project-stage is
+different from development:
+
+[source,java]
+---------------------------------------------------------------
+@Exclude(exceptIfProjectStage = ProjectStage.Development.class)
+@Alternative
+public class MyDevBean
+{
+}
+---------------------------------------------------------------
+
+==== Custom ExpressionInterpreter
+
+Per default only a very simple and limited syntax is supported. In real
+projects there are usually quite concrete requirements. Since it would
+be very complex to support most of them, it's easier for users to
+implement an optimized syntax. For such cases a custom
+ExpressionInterpreter is needed:
+
+[source,java]
+----------------------------------------------------------------------------------------------------
+@Alternative
+@Exclude(onExpression = "environment!=HSQL", interpretedBy = ConfigAwareExpressionInterpreter.class)
+public class DevDbBean implements DbBean
+{
+}
+
+public class ConfigAwareExpressionInterpreter implements ExpressionInterpreter<String, Boolean>
+{
+ public Boolean evaluate(String expression)
+ {
+ if (expression == null)
+ {
+ return false;
+ }
+
+ String[] values = expression.split("!=");
+
+ if (values.length != 2)
+ {
+ throw new IllegalArgumentException("'" + expression + "' isn't a supported syntax");
+ }
+
+ String configuredValue = ConfigResolver.getPropertyValue(values[0], null);
+
+ //exclude if null or the configured value is different
+ return configuredValue == null || !values[1].trim().equalsIgnoreCase(configuredValue);
+ }
+}
+----------------------------------------------------------------------------------------------------
+
+=== Type-safe View-Config
+
+
+TODO (Overview)
+
+=== Literals
+
+Literals allow the instantiation of annotations by extending the
+abstract class 'javax.enterprise.util.AnnotationLiteral'
+
+*Example*
+
+[source,java]
+----------------------------------------------------------------------------------------------
+public abstract class PayByQualifier
+ extends AnnotationLiteral<PayBy>
+ implements PayBy {}
+
+ PayBy paybyCheque = new PayByQualifier() { public PaymentMethod value() { return CHEQUE; } };
+----------------------------------------------------------------------------------------------
+
+DeltaSpike provides many annotation literals that you can use - e.g.:
+
+* AlternativeLiteral
+* AnyLiteral
+* ApplicationScopedLiteral
+* ConversationScopedLiteral
+* DefaultLiteral
+* DependentScopeLiteral
+* ModelLiteral
+* NamedLiteral
+* NewLiteral
+* RequestedScopeLiteral
+* SessionScopeLiteral
+* Singleton
+* SpecializesLiteral
+* TypedLiteral
+
+=== Messages & I18n
+
+The following implementation is the minimal effort to use type-safe
+messages (which are hardcoded in this case).
+
+*Simple type-safe message*
+
+[source,java]
+---------------------------------------------
+@MessageBundle
+public interface SimpleMessage
+{
+ @MessageTemplate("Welcome to DeltaSpike")
+ String welcomeToDeltaSpike();
+}
+---------------------------------------------
+
+The following implementation uses the key `welcome_to_deltaspike` to do
+a lookup in the default message bundle. The default bundle has the same
+name as the interface (but .properties instead of .java (/.class) as
+file extension).
+
+*Internationalized type-safe message*
+
+[source,java]
+-----------------------------------------------------------------
+@MessageBundle
+public interface SimpleMessage
+{
+ @MessageTemplate("{welcome_to_deltaspike}")
+ String welcomeToDeltaSpike();
+}
+
+org.apache.deltaspike.example.message.SimpleMessage
+
+->
+
+org/apache/deltaspike/example/message/SimpleMessage.properties
+org/apache/deltaspike/example/message/SimpleMessage_en.properties
+org/apache/deltaspike/example/message/SimpleMessage_de.properties
+...
+
+//content (as usual in message bundle files):
+welcome_to_deltaspike=Welcome to DeltaSpike
+-----------------------------------------------------------------
+
+The following implementation uses the key `welcome_to_deltaspike` to do
+a lookup in a custom message bundle known by `CustomMessageResolver`.
+
+*Internationalized type-safe message*
+
+[source,java]
+--------------------------------------------------------------------
+@MessageBundle
+@MessageContextConfig(messageResolver = CustomMessageResolver.class)
+public interface SimpleMessage
+{
+ @MessageTemplate("{welcome_to_deltaspike}")
+ String welcomeToDeltaSpike();
+}
+--------------------------------------------------------------------
+
+`@MessageContextConfig` allows to provide a custom `MessageResolver`,
+`MessageInterpolator` and `LocaleResolver`.
+
+The following implementation shows the usage of an internationalized
+simple type-safe message.
+
+*Internationalized type-safe message with parameter/s*
+
+[source,java]
+----------------------------------------------------------------------------
+@MessageBundle
+@MessageContextConfig(messageInterpolator = CustomMessageInterpolator.class)
+public interface SimpleMessage
+{
+ //in the message bundle: welcome_to=Welcome to %s
+
+ @MessageTemplate("{welcome_to}")
+ String welcomeTo(String name);
+}
+
+//...
+public class MyBean
+{
+ @Inject
+ private SimpleMessage messages;
+
+ public String welcomeToDeltaSpike
+ {
+ return this.messages.welcomeTo("DeltaSpike");
+ }
+}
+----------------------------------------------------------------------------
+
+=== Dynamic Message Builder
+
+
+==== Creating message instances
+
+
+The following implementation creates an instance of `Message` for the
+key `hello`. The final text will be resolved and interpolated lazily.
+Later on it might be supported to provide a different `MessageContext`
+via `#toString(MessageContext)` like it is in MyFaces CODI right now.
+
+You can use `#argument(String)` to pass these arguments to the message
+template specified on `#template(String)` method. The template pattern
+uses printf-style format strings.
+
+[source,java]
+---------------------------------------------------------------------------------------------
+public class MyBean
+{
+
+ @Inject
+ private MessageContext messageContext;
+
+ public void action()
+ {
+ Message message = this.messageContext.message();
+ write(message.template("Hello %s from %s").argument("World").argument("DeltaSpike"));
+ }
+ //...
+}
+---------------------------------------------------------------------------------------------
+
+Besides the static config via `@MessageContextConfig#messageSource`, you
+can also specify the message sources dynamically.
+
+[source,java]
+--------------------------------------------------------------------------------------------------------------------
+@Inject
+private MessageContext messageContext;
+
+public void action()
+{
+ Message message = this.messageContext.messageSource("org.apache.deltaspike.example.message.Messages").message();
+ write(message.template("{hello}").argument("World").argument("DeltaSpike"));
+}
+//...
+->
+
+org/apache/deltaspike/example/message/Messages.properties
+org/apache/deltaspike/example/message/Messages_en.properties
+org/apache/deltaspike/example/message/Messages_de.properties
+...
+
+//content (as usual) in message bundle files:
+hello=Hello %s from %s
+--------------------------------------------------------------------------------------------------------------------
+
+==== Customizing the message context
+
+
+===== MessageResolver
+
+A message-resolver is responsible for creating the message-text based on
+the message-descriptor (key or inline-text), the current locale (and in
+some cases the message-payload). (The supported format e.g. if it's
+required to escape a key, if inline-text is supported,... depends on the
+concrete implementation.) In case of a message-key, the message-resolver
+has to transform it to the message-text by looking it up in a message
+source like a resource-bundle.
+
+*Configuration of a message-resolver*
+
+Besides the static config via `@MessageContextConfig#messageResolver`,
+you can use it dynamically via passing a custom message-resolver
+instance to the current messageContext:
+
+[source,java]
+---------------------------------------------------------------------------------------------
+@Inject
+private MessageContext messageContext;
+
+//...
+
+Message message = this.messageContext.messageResolver(new CustomMessageResolver()).message();
+---------------------------------------------------------------------------------------------
+
+The result of a `MessageResolver` is the message-text. The text might
+contain placeholders which are processed by a `MessageInterpolator`
+
+===== MessageInterpolator
+
+A `MessageInterpolator` replaces the placeholders in a message-text with
+the arguments of the message.
+
+*Configuration of a message-interpolator*
+
+Besides the static config via
+`@MessageContextConfig#messageInterpolator, you can use it dynamically
+via passing a custom message-interpolator instance to the current
+messageContext:
+
+[source,java]
+-----------------------------------------------------------------------------------------------------
+@Inject
+private MessageContext messageContext;
+
+//...
+Message message = this.messageContext.messageInterpolator(new CustomMessageInterpolator()).message();
+-----------------------------------------------------------------------------------------------------
+
+===== LocaleResolver
+
+A locale resolver provides the current locale. The locale is e.g. used
+to by a `MessageResolver` to choose the correct language for the
+message-text.
+
+*Configuration of a locale-resolver*
+
+Besides the static config via `@MessageContextConfig#localeResolver, you
+can use it dynamically via passing a custom locale-resolver instance to
+the current messageContext:
+
+-------------------------------------------------------------------------------------------
+@Inject
+private MessageContext messageContext;
+
+//...
+Message message = this.messageContext.localeResolver(new CustomLocaleResolver()).message();
+-------------------------------------------------------------------------------------------
+
+=== Injecting Resources
+
+DeltaSpike has simple APIs for performing basic resource loading and
+property file reading.
+
+[source,java]
+----------------------------------------
+@Inject
+@InjectableResource("myfile.properties")
+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).
+
+===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
+CDI event, and the programming model is not exactly the same as
+specifying a CDI event observer, the concepts are very similar.
+DeltaSpike makes use of events for many of its features. Eventing is
+actually the only way to start using DeltaSpike's exception handling.
+
+This event is fired either by the application or a DeltaSpike exception
+handling integration. DeltaSpike then hands the exception off to a chain
+of registered handlers, which deal with the exception appropriately. The
+use of CDI events to connect exceptions to handlers makes this strategy
+of exception handling non-invasive and minimally coupled to the
+exception handling infrastructure.
+
+The exception handling process remains mostly transparent to the
+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
+
+The entire exception handling process starts with an event. This helps
+keep your application minimally coupled to DeltaSpike, but also allows
+for further extension. Exception handling in DeltaSpike is all about
+letting you take care of exceptions the way that makes the most sense
+for your application Events provide this delicate balance. Firing the
+event is the main way of starting the exception handling proccess.
+
+Manually firing an event to use DeltaSpike's exception handling is
+primarily used in your own try/catch blocks. It's very painless and also
+easy. Let's examine a sample that might exist inside of a simple
+business logic lookup into an inventory database:
+
+[source,java]
+----------------------------------------------------------------------------
+public class InventoryActions {
+ @PersistenceContext private EntityManager em;
+ @Inject private Event<ExceptionToCatchEvent> catchEvent;
+
+ public Integer queryForItem(Item item) {
+ try {
+ Query q = em.createQuery("SELECT i from Item i where i.id = :id");
+ q.setParameter("id", item.getId());
+ return q.getSingleResult();
+ } catch (PersistenceException e) {
+ catchEvent.fire(new ExceptionToCatchEvent(e));
+ }
+ }
+}
+----------------------------------------------------------------------------
+
+The `Event` of generic type `ExceptionToCatchEvent` is injected into
+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
+
+
+As an application developer (i.e., an end user of DeltaSpike's exception
+handling), you'll be focused on writing exception handlers. An exception
+handler is a method on a CDI bean that is invoked to handle a specific
+type of exception. Within that method, you can implement any logic
+necessary to handle or respond to the exception.
+
+*If there are no exception handlers for an exception, the exception is
+rethrown - except `ExceptionToCatchEvent#optinal` is set to true*
+
+Given that exception handler beans are CDI beans, they can make use of
+dependency injection, be scoped, have interceptors or decorators and any
+other functionality available to CDI beans.
+
+Exception handler methods are designed to follow the syntax and
+semantics of CDI observers, with some special purpose exceptions
+explained in this guide. The advantage of this design is that exception
+handlers will be immediately familiar to you if you are studying or
+well-versed in CDI.
+
+In this and subsequent sections, you'll learn how to define an exception
+handler, explore how and when it gets invoked, modify an exception and a
+stack trace, and even extend exception handling further through events
+that are fired during the handling workflow. We'll begin by covering the
+two annotations that are used to declare an exception handler,
+`@ExceptionHandler` and `@Handles`, and `@BeforeHandles` to create a
+callback before the handler is called.
+
+Exception handlers are considered equal if they both handle the same
+exception class, have the same qualifiers, the same ordinal and the same
+value for `isBeforeHandler()`.
+
+Exception handlers are contained within exception handler beans, which
+are CDI beans annotated with `@ExceptionHandler`. Exception handlers are
+methods which have a parameter which is an instance of
+`ExceptionEvent<T extends Throwable>` annotated with the `@Handles`
+annotation.
+
+===== @ExceptionHandler
+
+The `@ExceptionHandler` annotation is simply a marker annotation that
+instructs the DeltaSpike exception handling CDI extension to scan the
+bean for handler methods.
+
+Let's designate a CDI bean as an exception handler by annotating it with
+`@ExceptionHandler`.
+
+[source,java]
+--------------------------
+@ExceptionHandler
+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` is a method parameter annotation that designates a method as
+an exception handler. Exception handler methods are registered on beans
+annotated with `@ExceptionHandler`. DeltaSpike will discover all such
+methods at deployment time.
+
+Let's look at an example. The following method is invoked for every
+exception that DeltaSpike processes and prints the exception message to
+stdout. (`Throwable` is the base exception type in Java and thus
+represents all exceptions).
+
+[source,java]
+----------------------------------------------------------------
+@ExceptionHandler
+public class MyHandlers
+{
+ void printExceptions(@Handles ExceptionEvent<Throwable> evt)
+ {
+ System.out.println("Something bad happened:" +
+ evt.getException().getMessage());
+ evt.handleAndContinue();
+ }
+}
+----------------------------------------------------------------
+
+The `@Handles` annotation on the first parameter designates this method
+as an exception handler (though it is not required to be the first
+parameter). This parameter must be of type
+`ExceptionEvent<T extends Throwable>`, otherwise it's detected as a
+definition error. The type parameter designates which exception the
+method should handle. This method is notified of all exceptions
+(requested by the base exception type `Throwable`).
+
+The `ExceptionEvent` instance provides access to information about the
+exception and can be used to control exception handling flow. In this
+case, it's used to read the current exception being handled in the
+exception chain, as returned by `getException()`.
+
+This handler does not modify the invocation of subsequent handlers, as
+designated by invoking `handleAndContinue()` on `ExceptionEvent`. As
+this is the default behavior, this line could be omitted.
+
+The `@Handles` annotation must be placed on a parameter of the method,
+which must be of type `ExceptionEvent<T extends Throwable>`. Handler
+methods are similar to CDI observers and, as such, follow the same
+principles and guidelines as observers (such as invocation, injection of
+parameters, qualifiers, etc) with the following exceptions:
+
+* a parameter of a handler method must be a `ExceptionEvent`
+* handlers are ordered before they are invoked (invocation order of
+observers is non-deterministic)
+* any handler can prevent subsequent handlers from being invoked
+
+In addition to designating a method as exception handler, the `@Handles`
+annotation specifies an `ordinal` about when the method should be
+invoked relative to other handler methods of the same type. Handlers
+with higher ordinal are invoked before handlers with a lower ordinal
+that handle the same exception type. The default ordinal (if not
+specified) is 0.
+
+The `@BeforeHandles` designates a method as a callback to happen before
+handlers are called.
+
+Let's take a look at more sophisticated example that uses all the
+features of handlers to log all exceptions.
+
+[source,java]
+-------------------------------------------------------------------------------------------
+@ExceptionHandler
+public class MyHandlers
+{
+ void logExceptions(@BeforeHandles @WebRequest ExceptionEvent<Throwable> evt, Logger log)
+ {
+ log.warn("Something bad happened: " + evt.getException().getMessage());
+ }
+
+ void logExceptions(@Handles @WebRequest ExceptionEvent<Throwable> evt, Logger log)
+ {
+ // possibly send a HTTP Error code
+ }
+}
+-------------------------------------------------------------------------------------------
+
+This handler has a default ordinal of 0 (the default value of the
+ordinal attribute on `@Handles`).
+
+This handler is qualified with `@WebRequest`. When DeltaSpike calculates
+the handler chain, it filters handlers based on the exception type and
+qualifiers. This handler will only be invoked for exceptions passed to
+DeltaSpike that carry the `@WebRequest` qualifier. We'll assume this
+qualifier distinguishes a web page request from a REST request.
+
+Any additional parameters of a handler method are treated as injection
+points. These parameters are injected into the handler when it is
+invoked by DeltaSpike. In this case, we are injecting a `Logger` bean
+that must be defined within the application (or by an extension).
+
+A handler is guaranteed to only be invoked once per exception
+(automatically muted), unless it re-enables itself by invoking the
+`unmute()` method on the `ExceptionEvent` instance.
+
+Handlers must not throw checked exceptions, and should avoid throwing
+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
+
+When DeltaSpike finds more than one handler for the same exception type,
+it orders the handlers by ordinal. Handlers with higher ordinal are
+executed before handlers with a lower ordinal. If DeltaSpike detects two
+handlers for the same type with the same ordinal, the order is
+non-deterministic.
+
+Let's define two handlers with different ordinals:
+
+[source,java]
+------------------------------------------------------------------------------------
+void handleIOExceptionFirst(@Handles(ordinal = 100) ExceptionEvent<IOException> evt)
+{
+ System.out.println("Invoked first");
+}
+
+void handleIOExceptionSecond(@Handles ExceptionEvent<IOException> evt)
+{
+ System.out.println(“Invoked second”);
+}
+------------------------------------------------------------------------------------
+
+The first method is invoked first since it has a higher ordinal (100)
+than the second method, which has the default ordinal (0).
+
+To summarize, here's how DeltaSpike determines the order of handlers to
+invoke (until a handler marks exception as handled):
+
+1. Unwrap exception stack
+2. Begin processing root cause
+3. Invoke any callback methods annotated with @BeforeHandles for the closest type to the exception
+4. Find handler for the closest type to the exception
+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
+
+When an exception is thrown, chances are it's nested (wrapped) inside
+other exceptions. (If you've ever examined a server log, you'll
+appreciate this fact). The collection of exceptions in its entirety is
+termed an exception chain.
+
+The outermost exception of an exception chain (e.g., EJBException,
+ServletException, etc) is probably of little use to exception handlers.
+That's why DeltaSpike doesn't simply pass the exception chain directly
+to the exception handlers. Instead, it intelligently unwraps the chain
+and treats the root exception cause as the primary exception.
+
+The first exception handlers to be invoked by DeltaSpike are those that
+match the type of root cause. Thus, instead of seeing a vague
+`EJBException`, your handlers will instead see an meaningful exception
+such as `ConstraintViolationException`. _This feature, alone, makes
+DeltaSpike's exception handling a worthwhile tool._
+
+DeltaSpike continues to work through the exception chain, notifying
+handlers of each exception in the stack, until a handler flags the
+exception as handled or the whole exception chain has been iterated.
+Once an exception is marked as handled, DeltaSpike stops processing the
+exception chain. If a handler instructs DeltaSpike to rethrow the
+exception (by invoking `ExceptionEvent#throwOriginal()`, DeltaSpike will
+rethrow the exception outside the DeltaSpike exception handling
+infrastructure. Otherwise, it simply returns flow control to the caller.
+
+Consider a exception chain containing the following nested causes (from
+outer cause to root cause):
+
+* EJBException
+* PersistenceException
+* SQLGrammarException
+
+DeltaSpike will unwrap this exception and notify handlers in the
+following order:
+
+* SQLGrammarException
+* PersistenceException
+* EJBException
+
+If there's a handler for `PersistenceException`, it will likely prevent
+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
+
+There are two APIs provided by DeltaSpike that should be familiar to
+application developers:
+
+* `ExceptionEvent`
+* `ExceptionStackEvent`
+
+===== ExceptionEvent
+
+In addition to providing information about the exception being handled,
+the `ExceptionEvent` object contains methods to control the exception
+handling process, such as rethrowing the exception, aborting the handler
+chain or unmuting the current handler. Five methods exist on the
+`ExceptionEvent` object to give flow control to the handler
+
+* `abort()` - terminate all handling immediately after this handler,
+does not mark the exception as handled, does not re-throw the exception.
+* `throwOriginal()` - continues through all handlers, but once all
+handlers have been called (assuming another handler does not call
+abort() or handled()) the initial exception passed to DeltaSpike is
+rethrown. Does not mark the exception as handled.
+* `handled()` - marks the exception as handled and terminates further
+handling.
+* `handleAndContinue()` - default. Marks the exception as handled and
+proceeds with the rest of the handlers.
+* `skipCause()` - marks the exception as handled, but proceeds to the
+next cause in the cause container, without calling other handlers for
+the current cause.
+* `rethrow(Throwable)` - Throw a new exception after this handler is
+invoked
+
+Once a handler is invoked it is muted, meaning it will not be run again
+for that exception chain, unless it's explicitly marked as unmuted via
+the `unmute()` method on `ExceptionEvent`.
+
+=== 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
+
+
+
+==== @ViewAccessScoped
+
+
+@GroupedConversationScoped
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+=== Creating a custom CDI Scope
+
+
+If you want to create a custom CDI scope to match your needs, you will
+need to follow these steps:
+
+First, create an Annotation with annotated with @javax.inject.Scope;
+Example:
+
+[source,java]
+----------------------------------------------------------------
+@Scope
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE,ElementType.METHOD,ElementType.FIELD})
+public @interface ACustomScope {}
+----------------------------------------------------------------
+
+Second, create an Extension to add the scope and a context for it.
+Example:
+
+[source,java]
+---------------------------------------------------------------------------------------
+public class ACustomScopeExtension implements Extension, Serializable {
+
+ public void addACustomScope(@Observes final BeforeBeanDiscovery event) {
+ event.addScope(ACustomScope.class, true, false);
+ }
+
+ public void registerACustomScopeContext(@Observes final AfterBeanDiscovery event) {
+ event.addContext(new ACustomScopeContext());
+ }
+}
+---------------------------------------------------------------------------------------
+
+Implement a javax.enterprise.context.spi.Context interface to hold the
+javax.enterprise.inject.spi.Bean instances according to your needs
+
+[source,java]
+-----------------------------------------------------------------------------------------------------
+public class ACustomScopeContext implements Context, Serializable {
+
+ // Get the scope type of the context object.
+ public Class<? extends Annotation> getScope() {
+ return ACustomScope.class;
+ }
+
+ // Return an existing instance of certain contextual type or create a new instance by calling
+ // javax.enterprise.context.spi.Contextual.create(CreationalContext) and return the new instance.
+ public <T> T get(Contextual<T> contextual, CreationalContext<T> creationalContext) {
+ Bean bean = (Bean) contextual;
+ // you can store the bean somewhere
+ if (somewhere.containsKey(bean.getName())) {
+ return (T) somewhere.get(bean.getName());
+ } else {
+ T t = (T) bean.create(creationalContext);
+ somewhere.put(bean.getName(), t);
+ return t;
+ }
+ }
+
+ // Return an existing instance of a certain contextual type or a null value.
+ public <T> T get(Contextual<T> contextual) {
+ Bean bean = (Bean) contextual;
+ // you can store the bean somewhere
+ if (somewhere.containsKey(bean.getName())) {
+ return (T) somewhere.get(bean.getName());
+ } else {
+ return null;
+ }
+ }
+
+ // Determines if the context object is active.
+ public boolean isActive() {
+ return true;
+ }
+
+}
+-----------------------------------------------------------------------------------------------------
+
+=== Deactivatable
+
+
+DeltaSpike allows you to deactivate its own Extensions. You just need to
+implement your <<spi.adoc#_classdeactivator,ClassDeactivator>>.
+
+The ClassDeactivator should be resolved by any ConfigSource using the
+key `org.apache.deltaspike.core.spi.activation.ClassDeactivator`. For
+example, we can disable SecurityExtension having the following class:
+
+[source,java]
+--------------------------------------------------------------------------
+public class CustomClassDeactivator implements ClassDeactivator
+{
+
+ private static final long serialVersionUID = 1L;
+
+ @Override
+ public Boolean isActivated(Class<? extends Deactivatable> targetClass)
+ {
+ if (targetClass.equals(SecurityExtension.class))
+ {
+ return Boolean.FALSE;
+ }
+ return null; //no result for the given class
+ }
+}
+--------------------------------------------------------------------------
+
+now, we can use the file /META-INF/apache-deltaspike.properties (or any
+other <<configuration.adoc#_configsources_provided_by_default,ConfigSource>>) with the following key/value:
+
+------------------------------------------------------------------------------------------
+org.apache.deltaspike.core.spi.activation.ClassDeactivator=org.test.CustomClassDeactivator
+------------------------------------------------------------------------------------------
+
+== Core - Utils
+
+
+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.
+
+=== ArraysUtils
+
+
+A collection of utilities for working with Arrays
+
+* `#asSet` - Create a set from an array. If the array contains duplicate
+objects, the last object in the array will be placed in resultant set.
+
+
+=== BeanUtils
+
+A set of utility methods for working with beans.
+
+* `#getQualifiers` - Extract the qualifiers from a set of annotations.
+* `#extractAnnotation` - Extract the annotations.
+* `#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.
+
+=== ClassDeactivationUtils
+
+
+Helper methods for `ClassDeactivator`
+
+* `#isActivated` - Evaluates if the given `Deactivatable` is active.
+
+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
+
+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
+
+Helper methods for Property files
+
+* `#resolvePropertyFiles` - Allows to lookup for resource bundle files.
+* `#loadProperties` - Load a Properties file from the given URL.
+* `#getResourceBundle` - Return the ResourceBundle for the current default Locale.
+
+
+=== ProxyUtils
+
+Helper for CDI proxies
+
+* `#getUnproxiedClass` - Return class of the real implementation.
+* `#isProxiedClass` - Analyses if the given class is a generated proxy class.
+
+=== StringUtils
+
+A collection of utilities for working with Strings.
+
+* `#isEmpty` - return true if the String is null or empty ( `string.trim().isEmpty()` )
+