deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gpetra...@apache.org
Subject deltaspike git commit: DELTASPIKE-1077 improved documentation about ClassDeactivator and Deactivatable
Date Sat, 13 Feb 2016 20:38:51 GMT
Repository: deltaspike
Updated Branches:
  refs/heads/master 8d8435177 -> 6ba0b0bad


DELTASPIKE-1077 improved documentation about ClassDeactivator and Deactivatable


Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/6ba0b0ba
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/6ba0b0ba
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/6ba0b0ba

Branch: refs/heads/master
Commit: 6ba0b0bad9129ccc0eee5c44135cd31e8191031f
Parents: 8d84351
Author: gpetracek <gpetracek@apache.org>
Authored: Sat Feb 13 21:02:54 2016 +0100
Committer: gpetracek <gpetracek@apache.org>
Committed: Sat Feb 13 21:37:50 2016 +0100

----------------------------------------------------------------------
 .../core/spi/activation/ClassDeactivator.java   | 12 +++-
 documentation/src/main/asciidoc/core.adoc       | 63 ++++++++++++++++++--
 2 files changed, 68 insertions(+), 7 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/deltaspike/blob/6ba0b0ba/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/spi/activation/ClassDeactivator.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/spi/activation/ClassDeactivator.java
b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/spi/activation/ClassDeactivator.java
index 9c5841b..f04159b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/spi/activation/ClassDeactivator.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/spi/activation/ClassDeactivator.java
@@ -21,8 +21,16 @@ package org.apache.deltaspike.core.spi.activation;
 import java.io.Serializable;
 
 /**
- * <p>A class-deactivator allows to specify deactivated classes which can't be deactivated
via std. CDI mechanisms.
- * This might be the case for CDI Extensions because CDI mechanisms are not available at
startup time.</p>
+ * <p>DeltaSpike allows you to deactivate pre-configured parts (like Extensions, event-broadcasters,...).
+ * Therefore DeltaSpike offers {@link ClassDeactivator} and {@link Deactivatable}.</p>
+ *
+ * <p>A {@link ClassDeactivator} allows to specify deactivated classes (if they implement
{@link Deactivatable})
+ * which can't be deactivated/customized via std. CDI mechanisms
+ * (like the veto-method or alternative/specialized CDI-beans).
+ * This might be the case e.g. for CDI Extensions because CDI mechanisms are not available
at startup time.</p>
+ *
+ * <p>Use it mainly to deactivate specific parts explicitly (blacklist approach),
+ * if there is an issue with such parts (and waiting for the next release isn't an option).</p>
  *
  * <p>A class-deactivator will be resolved from the environment via the default resolvers
or via a custom resolver which
  * allows to use any type of configuration-format. See {@link org.apache.deltaspike.core.api.config.ConfigResolver}

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/6ba0b0ba/documentation/src/main/asciidoc/core.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/core.adoc b/documentation/src/main/asciidoc/core.adoc
index 7aebbbf..371b36b 100644
--- a/documentation/src/main/asciidoc/core.adoc
+++ b/documentation/src/main/asciidoc/core.adoc
@@ -1084,18 +1084,30 @@ public class ACustomScopeContext implements Context, Serializable
{
 
 == Deactivatable
 
-DeltaSpike allows you to deactivate its own Extensions. You just need to
-implement your <<spi.adoc#_classdeactivator,ClassDeactivator>>.
+DeltaSpike allows you to deactivate its own pre-configured parts (like Extensions, event-broadcasters,...).
+Therefore DeltaSpike offers `org.apache.deltaspike.core.spi.activation.ClassDeactivator`
and
+`org.apache.deltaspike.core.spi.activation.Deactivatable`.
 
-The ClassDeactivator should be resolved by any ConfigSource using the
+A `ClassDeactivator` allows to specify deactivated classes (if they implement `Deactivatable`)
+which can't be deactivated/customized via std. CDI mechanisms
+(like the veto-method or alternative/specialized CDI-beans).
+This might be the case e.g. for CDI Extensions because CDI mechanisms are not available at
startup time.
+
+Use it mainly to deactivate specific parts *explicitly* (blacklist approach),
+if there is an issue with such parts (and waiting for the next release isn't an option).
+
+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:
+example, if we need to provide our own version of the SecurityExtension,
+we can disable the SecurityExtension provided by DeltaSpike with the following `ClassDeactivator`:
 
+.Disable a specific extension
 [source,java]
 --------------------------------------------------------------------------
 public class CustomClassDeactivator implements ClassDeactivator
 {
-
     private static final long serialVersionUID = 1L;
 
     @Override
@@ -1117,6 +1129,47 @@ other <<configuration.adoc#_configsources_provided_by_default,ConfigSource>>)
wi
 org.apache.deltaspike.core.spi.activation.ClassDeactivator=org.test.CustomClassDeactivator
 ------------------------------------------------------------------------------------------
 
+SecurityExtension still gets started, because it isn't possible to veto it, however, it isn't
processing beans (once deactivated)
+and therefore it's e.g. possible to extend and customize the default implementation provided
by DeltaSpike.
+
+The following listing shows how to enable only a minimal set of extensions.
+Technically that's possible, however, it isn't suggested to use such an approach,
+because you might disable mechanisms need later on (in your project).
+
+.Possible but not suggested
+[source,java]
+--------------------------------------------------------------------------
+public class WhitelistFilter implements ClassDeactivator
+{
+    private List<Class<?>> limitedExtensions =
+      new ArrayList<Class<?>>()
+    {{
+        add(ConfigurationExtension.class);
+        add(PartialBeanBindingExtension.class);
+        add(RepositoryExtension.class);
+    }};
+
+    @Override
+    public Boolean isActivated(
+      Class<? extends Deactivatable> deactivatableClass)
+    {
+        return !Extension.class.isAssignableFrom(deactivatableClass) ||
+            limitedExtensions.contains(deactivatableClass);
+    }
+}
+--------------------------------------------------------------------------
+
+Instead it's better to disable the part you really like to deactivate (see `CustomClassDeactivator`).
+
+=== Deactivate Deactivatable-Classes via Config
+
+The default implementation of `ClassDeactivator` allows to deactivate classes by adding config-entries
to one of your config-sources (like `META-INF\apache-deltaspike.properties`).
+The following example shows how it would look like e.g. in case of the SecurityExtension:
+
+------------------------------------------------------------------------------------------
+deactivate.org.apache.deltaspike.security.impl.extension.SecurityExtension=true
+------------------------------------------------------------------------------------------
+
 == Utilities
 
 DeltaSpike provides many utility classes (no constructor / static


Mime
View raw message