Title: porposed CDI-1.1 enhancements
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.
This page contains proposals of the DeltaSpike community for CDI 1.1. Some parts might be used also for DeltaSpike for CDI 1.0.
# Context Management (with community agreement)
public interface ManagedContext extends Context
{
void start();
void stop();
}
[TODO]
## Context Management of Weld-Core (API)
A set of dependent scoped built in beans are available for context management.
/**
*
* Lifecycle management for built in contexts. {@link ManagedContext} only
* allows a context to be activated, deactivated and destroyed. It does not
* allow the context to be associated with an underlying data store. These
* operations are defined on {@link BoundContext}.
*
*
*
* CDI provides a number of managed contexts: {@link SessionContext},
* {@link ConversationContext}, {@link RequestContext}. All these managed
* contexts are scoped to the thread, and propagation of the backing store
* between threads is the responsibility of the managed context user.
*
*
* @see BoundContext
*
*/
public interface ManagedContext extends Context {
/**
* Activate the Context.
*/
public void activate();
/**
* Deactivate the Context, destroying any instances if the context is invalid.
*/
public void deactivate();
/**
* Mark the context as due for destruction when deactivate is called.
*/
public void invalidate();
}
b
/**
*
* Allows a thread-based context to be bound to some external instance storage
* (such as an HttpSession).
*
*
*
* A context may be detachable in which case a call to
* {@link ManagedContext#invalidate()} will detach the context from it's
* associated storage. A detached context is still usable (instances may be
* added or removed) however changes will not be written through to the
* underlying data store.
*
*
*
* Normally, a detachable context will have it's underlying bean store attached
* on a call to {@link ManagedContext#activate()} and detached on a call to
* {@link ManagedContext#deactivate()} however a subtype of {@link BoundContext}
* may change this behavior.
*
*
*
* If you call {@link #associate(Object)} you must ensure that you call
* {@link #dissociate(Object)} in all cases, otherwise you risk memory leaks.
*
*
* @param the type of the external instance storage
* @see ManagedContext
*/
public interface BoundContext extends Context {
/**
* Associate the context with the storage (for this thread). Once
* {@link #associate(Object)} has been called, further calls to
* {@link #associate(Object)} will be ignored, until the context has been
* subsequently {@link #dissociate(Object)} from the storage.
*
* @param storage the external storage
* @return true if the storage was attached, otherwise false
*/
public boolean associate(S storage);
/**
* Dissociate the context from the storage (for this thread). The context
* will only dissociate from the same storage it associated with.
*
* @param storage the external storage
* @return true if the storage was dissociated
*/
public boolean dissociate(S storage);
}
/**
*
* The built in dependent context, associated with {@link Dependent}. It is
* always active.
*
*
*
* There is one Dependent context which can be injected using:
*
*
*
* @Inject DependentContext dependentContext;
*
*
*/
public interface DependentContext extends Context { }
b
/**
*
* The built in request context is associated with {@link RequestScoped} and is
* a managed context which can be activated, invalidated and deactivated.
*
*
*
* CDI comes with one implementation of the request context. The
* {@link HttpRequestContext}, in which conversations are bound to the
* {@link ServletRequest}, can be injected:
*
*
*
* @Inject @Http RequestContext requestContext;
*
*
* @see HttpRequestContext
* @see RequestScoped
*
*/
public interface RequestContext extends ManagedContext {}
b
/**
*
* The built in session context is associated with {@link SessionScoped}. It can
* be activated, invalidated and deactivated.
*
*
*
* CDI comes with one implementation of the session context. The
* {@link HttpSessionContext}, in which conversations are bound to the
* {@link HttpSession}, can be injected:
*
*
*
* @Inject @Http SessionContext sessionContext;
*
*
* @see HttpSessionContext
* @sees {@link SessionScoped}
*
*/
public interface SessionContext extends ManagedContext {}
b
/**
*
* The built in application context, associated with {@link ApplicationScoped}.
* It is always active (not managed) and is backed by an application scoped
* singleton.
*
*
*
* CDI comes with one Application context which can be injected using:
*
*
*
* @Inject ApplicationContext applicationContext;
*
*
* @see SingletonContext
* @see ApplicationScoped
*
*/
public interface ApplicationContext extends Context {
/**
* Invalidate the context, causing all bean instances to be destroyed.
*/
public void invalidate();
}
b
/**
*
* The built in singleton context, associated with {@link Singleton}.
* It is always active (not managed) and is backed by an application scoped
* singleton.
*
*
*
* CDI comes with one Singleton context which can be injected using:
*
*
*
* @Inject SingletonContext singletonContext;
*
*
* @author Pete Muir
* @see SingletonContext
* @see ApplicationScoped
*
*/
public interface SingletonContext extends Context {}
And these HTTP backed implementations:
/**
*
* A request context which can be bound to the {@link ServletRequest}. The
* context is automatically attached to the map on activation, and detached when
* {@link #invalidate()} is called.
*
*
*
* This context is not thread safe, and provides no thread safety for the
* underlying map.
*
*
*/
public interface HttpRequestContext extends BoundContext, RequestContext {}
b
/**
*
* A session context which can be bound to the {@link HttpServletRequest}. The
* context is automatically attached to the map on activation, and detached when
* {@link #invalidate()} is called.
*
*
*
* This context is not thread safe, and provides no thread safety for the
* underlying map.
*
*
*/
public interface HttpSessionContext extends BoundContext, SessionContext
{
/**
*
* Mark the Session Context for destruction; the Session Context will be
* detached from the underling Http Session, and instances marked for
* destruction when the Http Request is destroyed.
*
*
*/
public void invalidate();
/**
*
* Destroy the session and all conversations stored in the session.
*
*
*
* If the context is not currently associated with a
* {@link HttpServletRequest}, then the context will be associated with the
* specified {@link HttpSession} (for this thread), activated, destroyed, and
* then deactivated.
*
*
*
* If the context is already associated with a {@link HttpServletRequest}
* then this call will detach the context from the underlying Http Session,
* and mark the context for destruction when the request is destroyed.
*
*
* @param session the {@link HttpSession} in which to store the bean
* instances
* @return true if the context was destroyed immediately
*/
public boolean destroy(HttpSession session);
}
# Map-bound contexts
We may also wish to add map-bound contexts, in which the contexts are backed by a map. Note that the example javadoc above needs expanding if we do.
Add these dependent scoped beans:
/**
*
* Allows a thread-based context to be bound to some external instance storage
* (such as an HttpSession).
*
*
*
* A context may be detachable in which case a call to
* {@link ManagedContext#invalidate()} will detach the context from it's
* associated storage. A detached context is still usable (instances may be
* added or removed) however changes will not be written through to the
* underlying data store.
*
*
*
* Normally, a detachable context will have it's underlying bean store attached
* on a call to {@link ManagedContext#activate()} and detached on a call to
* {@link ManagedContext#deactivate()} however a subtype of {@link BoundContext}
* may change this behavior.
*
*
*
* If you call {@link #associate(Object)} you must ensure that you call
* {@link #dissociate(Object)} in all cases, otherwise you risk memory leaks.
*
*
* @param the type of the external instance storage
* @see ManagedContext
*/
public interface BoundContext extends Context
{
/**
* Associate the context with the storage (for this thread). Once
* {@link #associate(Object)} has been called, further calls to
* {@link #associate(Object)} will be ignored, until the context has been
* subsequently {@link #dissociate(Object)} from the storage.
*
* @param storage the external storage
* @return true if the storage was attached, otherwise false
*/
public boolean associate(S storage);
/**
* Dissociate the context from the storage (for this thread). The context
* will only dissociate from the same storage it associated with.
*
* @param storage the external storage
* @return true if the storage was dissociated
*/
public boolean dissociate(S storage);
}
b
/**
*
* A request context which can be bound to any Map. The context is automatically
* attached to the map on activation, and detached when {@link #invalidate()} is
* called.
*
*
*
* This context is not thread safe, and provides no thread safety for the
* underlying map. A thread-safe map can be used to back the context.
*
*/
public interface BoundRequestContext extends RequestContext, BoundContext