You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by gp...@apache.org on 2012/12/16 03:08:20 UTC
svn commit: r1422448 -
/incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext
Author: gpetracek
Date: Sun Dec 16 02:08:19 2012
New Revision: 1422448
URL: http://svn.apache.org/viewvc?rev=1422448&view=rev
Log:
cleanup
Modified:
incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext
Modified: incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext?rev=1422448&r1=1422447&r2=1422448&view=diff
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext (original)
+++ incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext Sun Dec 16 02:08:19 2012
@@ -16,60 +16,6 @@ Notice: Licensed to the Apache Softwa
specific language governing permissions and limitations
under the License.
-## 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).
-
## Annotated Type Builder
DeltaSpike provides an {{AnnotatedType}} implementation (and corresponding implementations of the suite of Annotated interfaces from CDI) that should be suitable for the needs of most portable extensions. The {{AnnotatedType}} is created from {{AnnotatedTypeBuilder}}, typically in an extension's observer method, as follows:
@@ -148,288 +94,4 @@ DeltaSpike has the ability, with the Ann
TestAnnotation testAnnotation = AnnotationInstanceProvider.of(TestAnnotation.class, memberValues);
-AnnotationInstanceProvider provides an implementation of equals, hashCode and toString compliant with the javadocs for Annotation. It also caches the instances for the duration of the application. Creating a new instance of the same class and same member values will yield the same instance as before.
-
-## @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
- @Exclude
- public class NoBean
- {
- }
-
-
- Excluding a bean in case of project-stage development
- @Exclude(ifProjectStage = ProjectStage.Development.class)
- public class MyBean
- {
- }
-
-
- Excluding a bean if the project-stage is different from development
- @Exclude(exceptIfProjectStage = ProjectStage.Development.class)
- public class MyDevBean
- {
- }
-
-The following usage allows to exclude a bean based on a configured value (see the supported config sources [TODO]).
-
- Excluding a bean based on an expression which eval. to true
- @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
- @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
- @Exclude(exceptIfProjectStage = ProjectStage.Development.class)
- @Alternative
- public class MyDevBean
- {
- }
-
-## 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
- //in most cases the following works without problems:
-
- @Inject
- private BeanManager beanManager;
-
- //use:
-
- BeanManager beanManager = BeanManagerProvider.getInstance().getBeanManager();
-
- //if CDI based injection isn't available.
-
-## 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
- 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
- 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'
- 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
- 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
- Object myBean = BeanProvider.getContextualReference("myBean", false);
-
- Resolving a simple contextual instance by name and expected type
- 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
- 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
- List<MyServiceInterface> myServiceList = BeanProvider.getContextualReferences(MyServiceInterface.class, false, false);
-
-### BeanProvider in Action
-
-See the example application shipped with DeltaSpike:
-
-Example: #1
-Starting point: SimpleBeanLookupExample
-
-## Low-level configurations
-
-### ConfigResolver
-
-In some cases low-level configs are needed e.g. during the bootstrapping process of the CDI container. (Currently it's e.g. used for configuring the value of the current project-stage, configured values which can be used in the expressions for {{@Exclude}},...) Usually it isn't used by users directly, but DeltaSpike needs such a low-level approach for several features. Therefore it's possible to use a so called {{ConfigResolver}} which resolves and caches {{ConfigSource}} s per application.
-The method {{ConfigResolver#getPropertyValue}} allows to provide a string based key and returns the configured value as String or null if no value has been found ({{#getAllPropertyValues}} has a similar contract but it returns a list which might be empty if there are no configured values for the given key).
-
- Simple lookup in the low-level config
- ConfigResolver.getPropertyValue("myKey");
-
-### ConfigSource
-
-A {{ConfigResolver}} uses all configured implementations of {{ConfigSource}} to lookup the property in question.
-
-Per default there are implementations for the following config sources (listed in the lookup order):
-
- * System properties
- * Environment properties
- * JNDI values
- * Properties file values (apache-deltaspike.properties)
-
-__It's possible to change this order and to add custom config sources.__
-
- 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
-
-### 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}}.
-
- 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
-
-To add a custom config-source, you have to implement the interface {{ConfigSourceProvider}} (and {{ConfigSource}} ) and activate the implementation of {{ConfigSourceProvider}} with the std. SPI mechanism provided by Java via the {{ServiceLoader}} (that means you have to create {{/META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSourceProvider}} which contains the fully qualified class name of the custom implementation/s).
-
-If you have a simple standalone {{ConfigSource}} you can also register it directly by creating a file {{/META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSource}} which contains the fully qualified class name of your {{ConfigSource}}.
-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.
-
-## DeltaSpikeConfig (CDI based config)
-
-This interface is a marker interface for all type-safe configs which allows to find those configs easily within the IDE without knowing further details as well as with a programmatic lookup e.g. {{BeanProvider.getContextualReferences(DeltaSpikeConfig.class, true)}}.
-
- Injecting a Config
- @Inject
- private CoreConfig config; //currently we don't have this class - it's just an example
-
-Type-safe configs are just normal classes (application scoped CDI beans) and custom values can be provided by extending the config/class in question, annotate it with the std. CDI annotation {{@Specializes}} and override the corresponding getter method which provides the default value.
-
-# @ConfigProperty
-
-{{@ConfigProperty}} allows to use the extensible low-level config of DeltaSpike (which is used by DeltaSpike for configs to influence the bootstrapping process) also for custom properties.
-Please check the corresponding part of the documentation to see the default config-sources, how to add custom config-sources, change the lookup order,...
-
- Injecting a simple property
- @ApplicationScoped
- public class SettingsBean
- {
- @Inject
- @ConfigProperty(name = "property1")
- private String property1;
-
- //...
- }
-
-During the bootstrapping process of DeltaSpike the known config-sources are checked. If in the example above {{property1}} doesn't exist, the bootstrapping fails.
-
-Via converters (currently under development - [TODO]) it's possible to inject the final type (since the converter approach needs an up and running CDI container, the correct format of the configured value isn't part of the check during the bootstrapping process).
-
-Injecting a converted property
- @ApplicationScoped
- public class SettingsBean
- {
- @Inject
- @ConfigProperty(name = "property1")
- private Integer intProperty1;
-
- //...
- }
-
-If the configured property isn't available during the bootstrapping process, it's possible to skip the check.
-
-Injecting a converted property without checking it during the bootstrapping
-
- @ApplicationScoped
- public class SettingsBean
- {
- @Inject
- @ConfigProperty(name = "property1", eager = false)
- private Integer intProperty1;
-
- //...
- }
-
-Furthermore, it's possible to implement custom annotations to keep it a bit *more* type-safe (changing the name of a config-property can be done centrally and the rest is type-safe) and it's possible to provide custom meta-data.
-The following example also shows how to use a different converter (and in this case a {{MetaDataAwareConverter<S, T, M>}} instead of a simple {{Converter<S, T>}}.
-
- Implementation and usage of a custom config-property annotation
- @Target({ PARAMETER, FIELD, METHOD, CONSTRUCTOR, ANNOTATION_TYPE })
- @Retention(RUNTIME)
- @Documented
-
- @ConfigProperty(name = "property2", converter = CustomInverseStringToLongConverter.class)
-
- @Qualifier
- public @interface Property2
- {
- @Nonbinding
- boolean inverseConvert() default false;
- }
-
- @Typed()
- public class CustomInverseStringToLongConverter implements MetaDataAwareConverter<String, Long, Property2>
- {
- @Override
- public Long convert(String source, Property2 metaData)
- {
- //...
- if (metaData.inverseConvert())
- {
- //...
- }
- //...
- }
-
- //...
- }
-
- @ApplicationScoped
- public class SettingsBean
- {
- @Inject
- @Property2(inverseConvert = true)
- private Long inverseProperty;
-
- //...
- }
+AnnotationInstanceProvider provides an implementation of equals, hashCode and toString compliant with the javadocs for Annotation. It also caches the instances for the duration of the application. Creating a new instance of the same class and same member values will yield the same instance as before.
\ No newline at end of file