Motivation

The basic idea is to use out-of-the-box CDI concepts to customize CODI as well as to provide custom type-safe config implementations (if it is possible). That works in combination with OpenWebBeans (OWB) and with the first versions of Weld. To keep it short: it doesn't work with versions between 1.1.0 and 1.1.3-SP1 of Weld (WELD-912 fixes it again). Therefore, it was required to introduce a custom concept. Even though the implementation for OWB (only) would be possible without a custom concept, you can use this optional concept for both CDI implementations. However, if you are using OWB you just need this information if you would like to use the alternative-config modules provided by CODI. In this case you just have to add the JARs to your project and you can use the alternative config e.g. based on a resource bundle.

Dependencies

If you would like to customize CODI in combination with Weld you just need the alternative-implementation module. If you are using OWB, you don't need this module only for this use-case (use @Specializes or @Alternative provided by CDI).

If you would like to use one or more of the alternative config modules provided by CODI you need the config module as well as the alternative-implementation module. With OWB and Weld v1.1.3-SP1+ you could also skip the modules described in this page and implement your own alternative configuration concept based on @Specializes provided by CDI.

Compatibility

Even though you need this modules in combination with OWB just in a very special use-case it works with all OWB versions.
In case of Weld you need Weld v1.1.1+ and in combination with Glassfish you have to use Glassfish v3.2+ (due to Glassfish bugs in earlier versions).

Modules

Alternative-Implementation Module

As described above you can use this module to customize CODI (not needed but also working in combination with OWB). Furthermore, it's required if you would like to use the alternative config modules described below.

This module basically provides the @AlternativeImplementation annotation. This annotation is just a marker. Internally all beans with this marker won't be filtered (vetoed) during the bootstrapping process. Beans annotated with @AlternativeImplementation have to be configured as SPI (the std. SPI mechanism provided by Java). That means you have to create a config file in /META-INF/services/. The name of the file depends on the interface/abstract class of the default implementation provided by CODI. E.g. in case of the configuration classes the file would be: META-INF/services/org.apache.myfaces.extensions.cdi.core.api.config.CodiConfig . As content you have to provide the fully qualified name of your custom bean. Furthermore, the custom implementation has to provide a public default constructor and the custom implementation has to implement/extend the interface/abstract class mentioned before.

After this two steps (annotating the custom implementation and configuring it as custom implementation), the default implementation of CODI will be filtered (vetoed) if the default implementation is an injectable CDI bean.

Alternative-Config Modules

This modules allow to use out-of-the-box config approaches like myfaces-extcdi.properties instead of the type-safe config as well as to integrate custom concepts based on the ConfiguredValueResolver concept.
Further information are available at Environment-Config Options.

Core Alternative-Configuration Module

This module allows to use custom alternative config approaches for the configs provided by the Core.

JSF Alternative-Configuration Module

This module allows to use custom alternative config approaches for the configs provided by the JSF module.

Alternative-Configuration Bundle

The module myfaces-extcdi-bundle-alternative-configuration bundles all alternative configs provided by CODI in an all-in-one JAR file.
Use the single config modules or the all-in-one bundle but not both.

Providing other alternative implementations

Sometimes it's required to activate and/or use other implementations provided by CODI or a custom implementation.
With OWB it's pretty simple - just annotate the class with @Alternative, implement the same interfaces as the original class (btw. extend from the same abstract class) and activate the implementation in the beans.xml config of CDI. As an alternative approach you can use the @Specializes annotation of CDI.

With Weld it's a bit more difficult. If the @Alternative approach doesn't work, you have to do it manually via a CDI extension.

public class VetoExtension implements Extension
{
    protected void vetoDefaultImplementations(@Observes ProcessAnnotatedType<Object> processAnnotatedType)
    {
        Class beanClass = processAnnotatedType.getAnnotatedType().getJavaClass();
        if(WindowHandler.class.isAssignableFrom(beanClass) &&
                !AlternativeWindowHandler.class.isAssignableFrom(beanClass))
        {
            processAnnotatedType.veto();
        }
    }
}

public class AlternativeWindowHandler extends ServerSideWindowHandler
{
    private static final long serialVersionUID = 6089519101832237681L;
}

As with every CDI extension you have to activate the VetoExtension in META-INF/services/javax.enterprise.inject.spi.Extension