You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by st...@apache.org on 2012/07/02 12:38:05 UTC
svn commit: r1356170 - /incubator/deltaspike/site/trunk/content/deltaspike/
Author: struberg
Date: Mon Jul 2 10:38:03 2012
New Revision: 1356170
URL: http://svn.apache.org/viewvc?rev=1356170&view=rev
Log:
DELTASPIKE-214 transition documents from WiKi to CMS
original WiKi content mostly by gpetracek,
conversion contributed by cmoulliard, txs!
Added:
incubator/deltaspike/site/trunk/content/deltaspike/I18.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/build.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/examples.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/exceptions.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/getting-started.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/integration-tests.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/irc.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/source.mdtext (with props)
incubator/deltaspike/site/trunk/content/deltaspike/spi.mdtext (with props)
Added: incubator/deltaspike/site/trunk/content/deltaspike/I18.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/I18.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/I18.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/I18.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,151 @@
+Title:
+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.
+
+# I18n
+
+## Type-safe messages
+
+### Simple use-case
+
+The following implementation is the minimal effort to use type-safe messages (which are hardcoded in this case).
+
+ Simple type-safe message
+ @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
+ @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
+ @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
+ @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.
+
+ public class MyBean
+ {
+ @Inject
+ private MessageContext messageContext;
+
+ public Message createMessage()
+ {
+ return this.messageContext.message().text("{hello}").create();
+ }
+ }
+
+### 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. The JSF module of MyFaces CODI will provide a default implementation which uses the configured application message bundle as message source. However, usually it's required to provide an implementation in every project (because the impl. is aware of the message-source).
+
+ Configuration of a message-resolver|borderStyle=solid
+ context.config().change().messageResolver(new CustomMessageResolver());
+
+ Hint
+ In case of a key as message-descriptor you might see the key and some missing-message-markers like ??? or the key itself.
+ In such a case the key isn't defined in the message-source or there is no or the wrong message-resolver configured for the current context.
+
+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. MyFaces CODI supports numbered- and named-arguments. However, it's possible to provide a custom {{MessageInterpolator}}.
+
+ Configuration of a message-interpolator|borderStyle=solid
+ context.config().change().messageResolver(new CustomMessageInterpolator());
+
+ Hint
+ If the message still contains placeholders after the interpolation, there might be a missing argument or the message-text uses a wrong syntax for the placeholders or the current context has no or the wrong {{MessageInterpolator}} .
+
+#### 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. The JSF module of MyFaces CODI provides a {{LocaleResolver}} which uses the locale of the current view(-root) (if a {{FacesContext}} is available).
+
+ Configuration of a locale-resolver|borderStyle=solid
+ context.config().change().localeResolver(new CustomLocaleResolver());
+
+ Configuration of a message-handler|borderStyle=solid
+ context.config().change().addMessageHandler(new CustomMessageHandler());
+
+ Info
+ Instead of {{context.config().change()}} it's also possible to use {{context.config().use()}} .
+ Instead of changing the current context, the current context gets cloned and the new context uses e.g. a new resolver which is configured via the fluent api.
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/I18.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/build.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/build.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/build.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/build.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,45 @@
+Title:
+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.
+
+# Building DeltaSpike from source
+
+Deltaspike uses [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
+
+## Build example
+
+ mvn clean install -Pexamples -POWB //build everything including the examples with OpenWebBeans
+ or
+ mvn clean install -Pexamples -PWeld //build everything including the examples with Weld
+
+## Jenkins Builds
+
+https://builds.apache.org/view/A-F/view/DeltaSpike/
+
+## Sonar
+
+https://analysis.apache.org/dashboard/index/org.apache.deltaspike:deltaspike-project
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/build.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/examples.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/examples.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/examples.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/examples.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,23 @@
+Title:
+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.
+
+# Examples
+
+## #1
+artifact-id: deltaspike-jse-owb-example
+(the shown use-cases also work with *Weld* - only the bootstrapping of the container is different, because this example is based on Java-SE and therefore outside of an Java-EE(6+) application server.
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/examples.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/exceptions.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/exceptions.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/exceptions.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/exceptions.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,294 @@
+Title:
+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.
+
+# Exception Handling
+
+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.
+
+## Exception Handling - Usage
+
+### Eventing into the exception handling framework
+
+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:
+
+ 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.
+
+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 handler annotations
+
+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}}.
+
+ @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).
+
+ @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.
+
+ @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.
+
+## 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}}?
+
+## Handler 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:
+
+ 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):
+
+ # Unwrap exception stack
+ # Begin processing root cause
+ # Invoke any callback methods annotated with @BeforeHandles for the closest type to the exception
+ # Find handler for the closest type to the exception
+ # If multiple handlers for same type, invoke handlers with higher ordinal first
+ # Continue above steps for each exception in stack
+
+## 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}}.
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/exceptions.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,437 @@
+Title:
+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.
+
+# Feature Overview
+
+## 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:
+
+ Modifying an AnnotatedType
+ public class NamingConventionAwareMetadataFilter implements Extension
+ {
+ public void ensureNamingConvention(@Observes ProcessAnnotatedType processAnnotatedType)
+ {
+ Class<?> beanClass = processAnnotatedType.getAnnotatedType().getJavaClass();
+
+ Named namedAnnotation = beanClass.getAnnotation(Named.class);
+ if(namedAnnotation != null &&
+ namedAnnotation.value().length() > 0 &&
+ Character.isUpperCase(namedAnnotation.value().charAt(0)))
+ {
+ AnnotatedTypeBuilder builder = new AnnotatedTypeBuilder();
+ builder.readFromType(beanClass);
+
+ String beanName = namedAnnotation.value();
+ String newBeanName = beanName.substring(0, 1).toLowerCase() + beanName.substring(1);
+
+ builder.removeFromClass(Named.class)
+ .addToClass(new NamedLiteral(newBeanName));
+
+ processAnnotatedType.setAnnotatedType(builder.create());
+ }
+ }
+ }
+ //don't forget to configure the extension in /META-INF/services/javax.enterprise.inject.spi.Extension
+
+
+In the example above we create a new builder, and initialize it using an existing {{AnnotatedType}}. We can then add or remove annotations from the class, and its members. When we have finished modifying the type, we call {{#create()}} to spit out a new, immutable, {{AnnotatedType}}. In the example {{@Named}} gets replaced if the bean-name doesn't start with a lower case character. {{NamedLiteral}} takes the new value which should be used for the new instance of {{@Named}}. That means if a class is annotated e.g. with {{@Named("MyBean")}} it will be replaced with {{@Named("myBean")}} during the bootstrapping process.
+
+AnnotatedTypeBuilder provides the following methods:
+ * addToClass
+ * addToConstructor
+ * addToConstructorParameter
+ * addToField
+ * addToMethod
+ * addToMethodParameter
+ * addToParameter
+ * overrideConstructorParameterType
+ * overrideFieldType
+ * overrideMethodParameterType
+ * overrideParameterType
+ * readFromType
+ * removeFromAll
+ * removeFromClass
+ * removeFromConstructor
+ * removeFromConstructorParameter
+ * removeFromField
+ * removeFromMethod
+ * removeFromMethodParameter
+ * removeFromParameter
+ * getJavaClass
+ * setJavaClass
+ * create
+
+## AnnotationInstanceProvider
+
+DeltaSpike has the ability, with the AnnotationInstanceProvider class, to dynamically create instances of annotations. These are useful for adding annotations to bean metadata in extensions, adding qualifiers to events, etc. Usage is very simple and straight forward. There are two public methods: {{of(Class<T extends Annotation>)}} and {{of(Class<T extends Annotation>, Map<String, ?>)}}. The first is simply a short cut passing an empty map to the second. The map parameter is a map of values to be used for the members of the annotation. The keys in the map must be the names of members in the annotation (i.e. value, type, etc.). Simple usages are below.
+
+ No Member values
+ RequestScoped requestScopedInstance = AnnotationInstanceProvider.of(RequestScoped.class);
+
+ Multiple member values
+ Map<String, Object> memberValues = new HashMap<String, Object>();
+ memberValues.put("booleanValue", false);
+ memberValues.put("booleanValues", new boolean[]{false});
+ memberValues.put("byteValue", (byte) 0);
+ memberValues.put("byteValues", new byte[]{(byte) 0});
+ memberValues.put("type", Object.class);
+ memberValues.put("types", new Class[]{Object.class});
+
+ 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;
+
+ //...
+ }
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/features.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/getting-started.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/getting-started.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/getting-started.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/getting-started.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,70 @@
+Title:
+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.
+
+# DeltaSpike Module Overview
+
+DeltaSpike consists of the following modules:
+
+Required modules:
+
+ * Core
+
+**Hint**
+
+In the listings below replace the placeholders for the version with the version of your choice or use:
+
+ <properties>
+ <deltaspike.version>incubating-0.1-SNAPSHOT</deltaspike.version>
+ </properties>
+
+
+## With Java-EE6+
+If you are using DeltaSpike in a Java-EE6 environment, you don't need to configure a CDI implementation explicitly because it's shipped with the container.
+
+## Without Java-EE6+
+Java-EE5 application servers as well as pure servlet containers like Apache Tomcat don't provide a CDI implementation out-of-the-box. So don't forget to setup the CDI implementation of your choice.
+
+## With Java-SE
+
+Several DeltaSpike features can be used with Java-SE5+ only. Therefore, you have to bootstrap the CDI container of your choise manually.
+
+ public class SimpleApp {
+ public static void main(String[] args) {
+ CdiContainer.start();
+
+ //You can use CDI here - since you can't inject a bean in this class directly use the BeanManagerProvider or the BeanProvider
+
+ CdiContainer.stop();
+ }
+ }
+
+ /**
+ * Helper class to start and stop the OpenWebBeansContainer
+ */
+ public class CdiContainer {
+ private static ContainerLifecycle lifecycle = null;
+
+ public static void start() {
+ lifecycle = WebBeansContext.currentInstance().getService(ContainerLifecycle.class);
+ lifecycle.startApplication(null);
+ }
+
+ public static void stop() {
+ lifecycle.stopApplication(null);
+ }
+ }
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/getting-started.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/integration-tests.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/integration-tests.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/integration-tests.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/integration-tests.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,56 @@
+Title:
+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.
+
+## 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
+
+### JBossAS7
+
+#### 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
+
+### GlassFish 3.1
+
+Install GlassFish (default setup without admin-password) and start GlassFish with asadmin start-domain
+
+ Executing the Arquillian tests with Oracle Glassfish 3.1+
+ mvn clean install -Pglassfish-remote-3.1
+
+### 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%\server\lib\weblogic.jar exists.
+Start the domain.
+
+ Executing the Arquillian tests with Oracle WebLogic 12c
+ mvn clean install -Pwls-remote-12c
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/integration-tests.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/irc.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/irc.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/irc.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/irc.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,21 @@
+Title:
+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.
+
+# IRC
+
+You can join us on irc.freenode.net, channel #deltaspike
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/irc.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,275 @@
+Title:
+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.
+
+# JPA Module
+
+## @Transactional
+
+This annotation is an alternative to transactional EJBs which allows to execute a method within a transaction.
+Before it's possible to start using the annotation, it's required to implement a CDI producer for an {{EntityManager}} and it's needed to inject the {{EntityManager}} in the bean which uses {{@Transactional}}. As shown later on it's also possible to use multiple qualifiers for using different {{EntityManager}}s.
+
+The following example shows a simple producer for an {{EntityManager}} and the corresponding dispose-method.
+Producing it as request scoped bean means that the dispose method will be called on finishing the request.
+As an alternative it's possible to use a special scope called {{@TransactionScoped}} provided by the same DeltaSpike module.
+
+ Producer for the default EntityManager
+ //...
+ public class EntityManagerProducer
+ {
+ //or manual bootstrapping
+ @PersistenceContext
+ private EntityManager entityManager;
+
+ @Produces
+ @RequestScoped
+ protected EntityManager createEntityManager()
+ {
+ return this.entityManager;
+ }
+
+ protected void closeEntityManager(@Disposes EntityManager entityManager)
+ {
+ if (entityManager.isOpen())
+ {
+ entityManager.close();
+ }
+ }
+ }
+
+The following examples show how to use the {{EntityManager}} produced by the example above.
+
+ Beans with transactional method
+ //...
+ public class TransactionalBean
+ {
+ @Inject
+ private EntityManager entityManager;
+
+ @Transactional
+ public void executeInTransaction()
+ {
+ //...
+ }
+ }
+
+ Simple transactional bean (all methods transactional)
+ //...
+ @Transactional
+ public class TransactionalBean
+ {
+ @Inject
+ private EntityManager entityManager;
+
+ //...
+ }
+
+As illustrated in the following example it's also possible to use {{@Transactional}} for stereotypes.
+
+ Stereotype for transactional beans (+ usage)
+ @Stereotype
+ @Transactional
+ @ApplicationScoped
+ public @interface Repository
+ {
+ }
+
+ //...
+ @Repository
+ public class TransactionalBean
+ {
+ @Inject
+ private EntityManager entityManager;
+
+ //...
+ }
+
+Besides such simple usages, it's also supported to use qualifiers to access multiple persistence-units in parallel.
+The default qualifier for {{@Transactional}} is {{@Any}}. Therefore a transaction for every injected entity manager will be started.
+The example afterwards shows how to change this default behaviour.
+
+ Producer for multiple entity managers (+ usage)
+ //...
+ public class EntityManagerProducer
+ {
+ @PersistenceContext(unitName = "firstDB")
+ private EntityManager firstEntityManager;
+
+ @PersistenceContext(unitName = "secondDB")
+ private EntityManager secondEntityManager;
+
+ @Produces
+ @First
+ @RequestScoped
+ protected EntityManager createFirstEntityManager()
+ {
+ return this.firstEntityManager;
+ }
+
+ protected void closeFirstEntityManager(@Disposes @First EntityManager entityManager)
+ {
+ if (firstEntityManager.isOpen())
+ {
+ firstEntityManager.close();
+ }
+ }
+
+ @Produces
+ @Second
+ @RequestScoped
+ protected EntityManager createSecondEntityManager()
+ {
+ return this.secondEntityManager;
+ }
+
+ protected void closeSecondEntityManager(@Disposes @Second EntityManager entityManager)
+ {
+ if (secondEntityManager.isOpen())
+ {
+ secondEntityManager.close();
+ }
+ }
+ }
+
+
+ //...
+ public class FirstLevelTransactionBean
+ {
+ @Inject
+ private @First EntityManager firstEntityManager;
+
+ @Inject
+ private NestedTransactionBean nestedTransactionBean;
+
+ @Transactional
+ public void executeInTransaction()
+ {
+ //...
+ this.nestedTransactionBean.executeInTransaction();
+ }
+ }
+
+ //...
+ public class NestedTransactionBean
+ {
+ @Inject
+ private @Second EntityManager secondEntityManager;
+
+ @Transactional
+ public void executeInTransaction()
+ {
+ //...
+ }
+ }
+
+The following example shows how to use only the specified {{EntityManager}}/s
+
+ Activating entity managers manually
+ public class MultiTransactionBean
+ {
+ @Inject
+ private EntityManager defaultEntityManager;
+
+ @Inject
+ private @First EntityManager firstEntityManager;
+
+ @Inject
+ private @Second EntityManager secondEntityManager;
+
+ @Transactional(qualifier = Default.class)
+ public void executeInDefaultTransaction()
+ {
+ }
+
+ @Transactional(qualifier = First.class)
+ public void executeInFirstTransaction()
+ {
+ }
+
+ @Transactional(qualifier = Second.class)
+ public void executeInSecondTransaction()
+ {
+ }
+
+ @Transactional(qualifier = {First.class, Second.class})
+ public void executeInFirstAndSecondTransaction()
+ {
+ }
+ }
+
+All examples also work with nested calls. In the following example the transaction handling is done on the entry point (after FirstLevelTransactionBean#executeInTransaction).
+
+ Joining existing transaction in nested call
+ //...
+ public class FirstLevelTransactionBean
+ {
+ @Inject
+ private EntityManager entityManager;
+
+ @Inject
+ private NestedTransactionBean nestedTransactionBean;
+
+ @Transactional
+ public void executeInTransaction()
+ {
+ this.nestedTransactionBean.executeInTransaction();
+ }
+ }
+
+ //...
+ public class NestedTransactionBean
+ {
+ @Inject
+ private EntityManager entityManager;
+
+ @Transactional
+ public void executeInTransaction()
+ {
+ //...
+ }
+ }
+
+The final transaction handling for all {{EntityManager}} s is also done after the outermost transactional method if {{NestedTransactionBean}} uses a different {{EntityManager}}.
+So it's possible to catch an exception in {{FirstLevelTransactionBean}} e.g. to try an optional path instead of an immediate rollback.
+
+## @TransactionScoped
+
+{{@Transactional}} also starts a context which is available as long as the transaction started by {{@Transactional}}. Besides other beans you can use this scope for the {{EntityManager}} itself. That means the {{EntityManager}} will be closed after leaving the method annotated with {{@Transactional}}.
+
+ Producer for the default EntityManager which should be used only for one transaction
+ //...
+ public class EntityManagerProducer
+ {
+ //or manual bootstrapping
+ @PersistenceContext
+ private EntityManager entityManager;
+
+ @Produces
+ @TransactionScoped
+ protected EntityManager createEntityManager()
+ {
+ return this.entityManager;
+ }
+
+ protected void closeEntityManager(@Disposes EntityManager entityManager)
+ {
+ if (entityManager.isOpen())
+ {
+ entityManager.close();
+ }
+ }
+ }
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/jpa.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,213 @@
+Title:
+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.
+
+# Security Module
+
+## SecurityBinding for class and method invocations
+
+This feature of the security module functions by intercepting method calls, and performing a security check before invocation is allowed to proceed.
+
+In order to use the DeltaSpike security module, you must first have installed the proper dependencies into your POM file. Once this is complete, you may proceed to create a security parameter binding annotation. This is what we will use to add security behavior to our business classes and methods.
+
+ Create the SecurityBinding
+ @Retention(value = RUNTIME)
+ @Target({TYPE, METHOD})
+ @Documented
+ @SecurityBindingType
+ public @interface CustomSecurityBinding {
+ }
+
+Next, we must define an Authorizer class to implement behavior for our custom SecurityBindingType. This class is simply a CDI bean which declares a @Secures method, qualified with the security binding annotation we created in the first step.
+
+This method has access to the InvocationContext of the method call, so if we need to access parameter arguments, we can do so using the given context. Note that we may also inject other beans into the parameter list of our @Secures method.
+
+ Create the Authorizer
+ @ApplicationScoped
+ public class CustomAuthorizer
+ {
+ @Secures
+ @CustomSecurityBinding
+ public boolean doSecuredCheck(InvocationContext invocationContext, BeanManager manager, @LoggedIn User user) throws Exception
+ {
+ return user.isLoggedIn(); // perform security check
+ }
+ }
+
+We can then use our new annotation to secure business or bean methods. This binding annotation may be placed on the entire class (securing all methods,) or on individual methods that you wish to secure.
+
+ Secure a bean method
+ @ApplicationScoped
+ public class SecuredBean1
+ {
+ @CustomSecurityBinding
+ public void doSomething(Thing thing)
+ {
+ thing.doSomething();
+ }
+ }
+
+Next, we may access parameter values from the method invocation directly in our authorizer bean by creating custom @SecurityParameterBinding types; this is a simple step once we have completed the work above:
+
+ Create a parameter binding annotation
+ @Retention(value = RUNTIME)
+ @Target({PARAMETER})
+ @Documented
+ @SecurityParameterBinding
+ public @interface CurrentThing {
+ }
+
+Now, when a secured method is invoked, we can inject actual parameter values as arguments into our authorizer method, providing domain-level security in our applications:
+
+ Update the Authorizer to use parameter binding
+ @ApplicationScoped
+ public class CustomAuthorizer
+ {
+ @Secures
+ @CustomSecurityBinding
+ public boolean doSecuredCheck(InvocationContext invocationContext, BeanManager manager, @LoggedIn User user, @CurrentThing Thing thing) throws Exception
+ {
+ return thing.hasMember(user); // perform security check against our method parameter
+ }
+ }
+
+Note that our business method must also be annotated.
+
+ Complete the parameter binding
+ @ApplicationScoped
+ public class SecuredBean1
+ {
+ @CustomSecurityBinding
+ public void doSomething(@CurrentThing Thing thing)
+ {
+ thing.doSomething();
+ }
+ }
+
+Our method is now secured, and we are able to use given parameter values as part of our security authorizer!
+
+## Integrating 3rd party security frameworks
+
+### @Secured
+
+{{@Secured}} is build on {{@SecurityBindingType}} and a very simple alternative to the rest of the security module.
+It's a basic hook to integrate a custom security concept, 3rd party frameworks,... . It doesn't provide a full blown security concept like the rest of the security module, but other DeltaSpike modules ensure that the security concepts are integrated properly (e.g. correct behaviour within custom scope implementations,...). It just allows to integrate other security frameworks easily.
+
+(In MyFaces CODI it was originally a CDI interceptor. This part changed a bit, because between the interceptor and {{@Secured}} is the {{@SecurityBindingType}} concept which triggers {{@Secured}} as on possible approach. Therefore the basic behaviour remains the same and you can think about it like an interceptor.)
+
+ Securing all intercepted methods of a CDI bean
+ //...
+ @Secured(CustomAccessDecisionVoter.class)
+ public class SecuredBean
+ {
+ //...
+ }
+
+or
+
+ Securing specific methods
+ //...
+ public class SecuredBean
+ {
+ @Secured(CustomAccessDecisionVoter.class)
+ public String getResult()
+ {
+ //...
+ }
+ }
+
+### AccessDecisionVoter
+
+This interface is (besides the {{Secured}} annotation) the most important part of the concept. Both artifact types are also the only required parts.
+
+ public class CustomAccessDecisionVoter implements AccessDecisionVoter
+ {
+ @Override
+ public Set<SecurityViolation> checkPermission(AccessDecisionVoterContext accessDecisionVoterContext)
+ {
+ Method method = accessDecisionVoterContext.<InvocationContext>getSource().getMethod();
+
+ //...
+ }
+ }
+
+[TODO] hint about the changed parameter/s
+
+### SecurityViolation
+
+In case of a detected violation a {{SecurityViolation}} has to be added to the result returned by the {{AccessDecisionVoter}}.
+
+[TODO] AbstractAccessDecisionVoter
+
+### @Secured and Stereotypes with custom Meta-data
+
+If there are multiple {{AccessDecisionVoter}} and maybe in different constellations, it's easier to provide an expressive CDI stereotypes for it. Later on that also allows to change the behaviour in a central place.
+
+ Stereotype support of @Secured}
+ @Named
+ @Admin
+ public class MyBean implements Serializable
+ {
+ //...
+ }
+
+ //...
+ @Stereotype
+ @Secured(RoleAccessDecisionVoter.class)
+ public @interface Admin
+ {
+ }
+
+Furthermore, it's possible to provide custom meta-data easily.
+
+ Stereotype of @Secured with custom meta-data}
+ @Named
+ @Admin(securityLevel=3)
+ public class MyBean implements Serializable
+ {
+ //...
+ }
+
+ //...
+ @Stereotype
+ @Secured(RoleAccessDecisionVoter.class)
+ public @interface Admin
+ {
+ int securityLevel();
+ }
+
+ @ApplicationScoped
+ public class RoleAccessDecisionVoter implements AccessDecisionVoter
+ {
+ private static final long serialVersionUID = -8007511215776345835L;
+
+ public Set<SecurityViolation> checkPermission(AccessDecisionVoterContext voterContext)
+ {
+ Admin admin = voterContext.getMetaDataFor(Admin.class.getName(), Admin.class);
+ int level = admin.securityLevel();
+ //...
+ }
+ }
+{code}
+
+## AccessDecisionVoterContext
+
+[TODO]
+
+## SecurityStrategy SPI
+
+[TODO]
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/security.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/source.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/source.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/source.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/source.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,25 @@
+Title:
+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.
+
+# Checking out from GitHub repo (anonymous)
+
+ gir clone git://github.com/apache/incubator-deltaspike.git ./
+
+# Checking out for members
+
+ git clone https://github.com/apache/incubator-deltaspike ./
\ No newline at end of file
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/source.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/deltaspike/site/trunk/content/deltaspike/spi.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/spi.mdtext?rev=1356170&view=auto
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/spi.mdtext (added)
+++ incubator/deltaspike/site/trunk/content/deltaspike/spi.mdtext Mon Jul 2 10:38:03 2012
@@ -0,0 +1,67 @@
+Title:
+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.
+
+# DeltaSpike-SPI
+
+## Deactivatable
+
+This interface is just a marker interface which is implemented by all pre-configured DeltaSpike artifacts which can be deactivated manually (e.g. to improve the performance if a part isn't needed, to provide a custom implementation if the default implementation isn't pluggable by default or to bypass an implementation which causes an issue (in this case please also *contact us* and we will fix it). This mechanism is only used for artifacts *like* implementations of ({{javax.enterprise.inject.spi.Extension}}) which *can't* be deactivated with std. CDI mechanisms.
+
+To deactivate a class it's required to implement {{ClassDeactivator}}. Returning 'false' or 'true' allows to de-/activate the class in question. Retuning null means that the current class-deactivator doesn't have information about the class in question and can't provide a result. Since {{ClassDeactivator}} implementations are configured with the low-level config of DeltaSpike, the class-deactivator with the highest ordinal has the final decision. DeltaSpike itself doesn't deactivate an implementation, however, an add-on or a 3rd party portable CDI extension based on DeltaSpike (Core+) can use the concept to deactivate a default implementation of DeltaSpike in favour of its own implementation. (*Attention*: due to the ordinal feature of the low-level config approach it's possible that a class-deactivator with a higher ordinal, e.g. used in a concrete project, can re-activate a deactivated implementation. *Please note* that you might have to deactivate the parts of the add-on
or 3rd party CDI extension which relies on its own implementation. Therefore, you should *be really careful with re-activation*.) The implementation should be stateless because the result will be cached and as soon as everything is initialized the class-deactivators won't be used any longer.
+
+ Deactivate classes via ClassDeactivator
+ //This class needs to be configured via one of the supported config sources!
+ public class CustomClassDeactivator extends ClassDeactivator
+ {
+ @Override
+ public Boolean isActivated(Class<? extends Deactivatable> targetClass)
+ {
+ if (targetClass.equals(MyClass.class))
+ {
+ return Boolean.FALSE;
+ }
+ return null; //no result for the given class
+ }
+ }
+
+A {{ClassDeactivator}} needs to be configured (see the supported config sources [TODO: link]). The key is the fully qualified name of the interface ({{org.apache.deltaspike.core.api.activation.ClassDeactivator}})
+
+## ClassDeactivation
+
+This helper is *not* intended to be used by users. DeltaSpike (and CDI extensions can) use/s it to check if a given class is activated. (Furthermore, it's optimized and callers don't have to care about synchronization,...)
+The method {{isActivated}} needs to be called manually to evaluate if a (non-CDI- or low-level-) class should be used. That means the pre-configured class *which uses* this helper won't disappear, instead it falls e.g. back to a minimal implementation which doesn't execute the target logic of the class itself or uses one of the other implementations (if there are multiple).
+
+h1. Global Alternative
+
+There are several application servers (using CDI 1.0) which can't handle alternative CDI beans correctly (e.g. due to a too strict interpretation or a broken implementation). Therefore, DeltaSpike allows to use the std. {{@Alternative}} annotation and an additional config entry for DeltaSpike which allows to use the alternative implementation as a global alternative.
+
+ Std. CDI alternative implementation (without the required XML config)
+ public class CustomBean
+ {
+ }
+
+ @Alternative
+ //...
+ public class AlternativeCustomBean extends CustomBean
+ {
+ }
+ {code}
+
+Instead of configuring the alternative in the beans.xml, a global alternative needs to be configured in /META-INF/apache-deltaspike.properties. CDI 1.1 should fix this issue and migrating to it means to remove the config entry for DeltaSpike again and move to the std. CDI config approach.
+
+ custom.CustomBean=custom.AlternativeCustomBean
Propchange: incubator/deltaspike/site/trunk/content/deltaspike/spi.mdtext
------------------------------------------------------------------------------
svn:eol-style = native