deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1422327 - /incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext
Date Sat, 15 Dec 2012 19:42:32 GMT
Author: gpetracek
Date: Sat Dec 15 19:42:32 2012
New Revision: 1422327

description of ProjectStage and ProjectStageProducer


Modified: incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext
--- incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext (original)
+++ incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext Sat Dec 15 19:42:32 2012
@@ -98,6 +98,64 @@ Resolving the Bean-Manager:
     //if CDI based injection is not available.
+## Type-safe ProjectStage
+Project stages allow to use implementations depending on the current environment. E.g. you
can implement a bean which creates sample-data for system tests which gets activated only
in case of project-stage `SystemTest`.
+*Besides custom project-stages* it's possible to use the following pre-defined project-stages:
+  - UnitTest
+  - Development
+  - SystemTest
+  - IntegrationTest
+  - Staging
+  - Production
+The core provides a pluggable and type-safe approach for using project stages in a project
(it's also used within the framework). Furthermore, `@Exclude` allows to use e.g. implementations
annotated with `javax.enterprise.inject.Alternative` for specific project-stages. Besides
the out-of-the-box project-stages it's possible to implement *custom but type-safe* project-stages
which will be exposed by DeltaSpike.
+Resolving and using the Project-Stage:
+    @Inject
+    private ProjectStage projectStage;
+    //...
+    boolean isDevProjectStage = ProjectStage.Development.equals(this.projectStage);
+### Custom Project Stages
+It's possible to provide custom project stage implementations.
+Therefore, you have to provide an implementation of the `ProjectStageHolder` interface.
+In this class you nest the custom project-stage implementations which have to be `public
static final class` and it's required to extend `ProjectStage`.
+It's required to provide a `public static final` instance even though, you won't use it directly.
+ProjectStageHolder for custom project stage implementations:
+    public class CustomProjectStageHolder implements ProjectStageHolder
+    {
+        public static final class CustomProjectStage extends ProjectStage
+        {
+            private static final long serialVersionUID = 1029094387976167179L;
+        }
+        public static final CustomProjectStage CustomProjectStage = new CustomProjectStage();
+    }
+Configure your custom `ProjectStageHolder` in `META-INF/services/org.apache.deltaspike.core.api.projectstage.ProjectStageHolder`.
The file has to provide the *fully qualified* class name of the custom implementation of the
`ProjectStageHolder` interface.
+Usage of a custom project stage:
+    ProjectStage customProjectStage;
+    customProjectStage = ProjectStage.valueOf("CustomProjectStage");
+    //or
+    customProjectStage = CustomProjectStageHolder.CustomProjectStage;
+    //or
+    @Exclude(ifProjectStage = CustomProjectStageHolder.CustomProjectStage.class)
+## ProjectStageProducer (for 3rd party portable extensions)
+`ProjectStageProducer` provides the producer method which allows to inject the current project-stage.
However, in some cases it's needed to use project-stages also during the bootstrapping process
of the CDI container and you can't use injection. In such cases you can use `ProjectStageProducer.getInstance().getProjectStage()`
to resolve the current project-stage. This helper also contains helpers for unit-tests - e.g.
`#setProjectStage`. However, those methods shouldn't be needed for users (we just need them
for testing different project-stage scenarios).
 ## @Exclude
 With `@Exclude` it's possible to annotate beans which should be ignored by CDI even if they
are in a CDI enabled archive.
@@ -167,10 +225,6 @@ Excluding an alternative implementation 
-## Type-safe ProjectStage
 ## Type-safe config

View raw message