Added: websites/staging/deltaspike/trunk/content/draft/cdi-1.1-proposals.html ============================================================================== --- websites/staging/deltaspike/trunk/content/draft/cdi-1.1-proposals.html (added) +++ websites/staging/deltaspike/trunk/content/draft/cdi-1.1-proposals.html Sun Jun 9 09:26:31 2013 @@ -0,0 +1,830 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content="deltaspike-generate-pages"> + <meta name="author" content="chm"> + + <title>Apache DeltaSpike - porposed CDI-1.1 enhancements</title> + + + + + <!-- 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. --> + + <!-- Styles --> + + <link href="./../deltaspike/resources/css/bootstrap.css" rel="stylesheet"> + <!--<link href="./../deltaspike/resources/css/prettify.css" rel="stylesheet" /> --> + <link href="./../deltaspike/resources/css/codehilite.css" rel="stylesheet" /> + <link href="./../deltaspike/resources/css/bootstrap-responsive.css" rel="stylesheet"> + <style type="text/css"> + body { + padding-top: 60px; + padding-bottom: 40px; + } + </style> + <script type="text/javascript"> + + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-36103647-1']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); + + </script> +</head> + +<body> + + <div class="navbar navbar-fixed-top"> + <div class="navbar-inner"> + <div class="container"> + <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse"> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </a> + <a class="brand" href="index.html"><img src="./../deltaspike/resources/images/deltaspike-logo-medium.png"/></a> + <div class="nav-collapse"> + <ul class="nav"> + <li class="active"><a href="./../deltaspike/index.html">Home</a></li> + <li><a href="./../deltaspike/documentation.html">Documentation</a></li> + <li><a href="./../deltaspike/source.html">Source</a></li> + <!-- <li><a href="./../deltaspike/download.html">Download</a></li> --> + <li><a href="./../deltaspike/community.html">Community</a></li> + <!-- <li><a href="./../deltaspike/support.html">Support</a></li> --> + <li><a href="./../deltaspike/news.html">News</a></li> + <li><a href="./../deltaspike/migration-guide.html">Migration</a></li> + </ul> + </div><!--/.nav-collapse --> + <form id="search-form" action="http://www.google.com/search"; method="get" class="navbar-search pull-right" > + <input value="incubator.apache.org/deltaspike" name="sitesearch" type="hidden"/> + <input class="search-query" name="q" id="query" type="text" /> + </form> + </div> + </div> + </div> + + <div class="container"> + <div class="row"> + <div class="span12"> + <div class="page-title"> + <h1>porposed CDI-1.1 enhancements</h1> + </div> + <p>This page contains proposals of the DeltaSpike community for CDI 1.1. Some parts might be used also for DeltaSpike for CDI 1.0.</p> +<h1 id="context-management-with-community-agreement">Context Management (with community agreement)</h1> +<div class="codehilite"><pre><span class="n">public</span> <span class="n">interface</span> <span class="n">ManagedContext</span> <span class="n">extends</span> <span class="n">Context</span> +<span class="p">{</span> + <span class="n">void</span> <span class="n">start</span><span class="p">();</span> + + <span class="n">void</span> <span class="n">stop</span><span class="p">();</span> +<span class="p">}</span> +</pre></div> + + +<p>[TODO]</p> +<h2 id="context-management-of-weld-core-api">Context Management of Weld-Core (API)</h2> +<p>A set of dependent scoped built in beans are available for context management.</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * Lifecycle management for built in contexts. {@link ManagedContext} only</span> +<span class="cm"> * allows a context to be activated, deactivated and destroyed. It does not</span> +<span class="cm"> * allow the context to be associated with an underlying data store. These</span> +<span class="cm"> * operations are defined on {@link BoundContext}.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * CDI provides a number of managed contexts: {@link SessionContext},</span> +<span class="cm"> * {@link ConversationContext}, {@link RequestContext}. All these managed</span> +<span class="cm"> * contexts are scoped to the thread, and propagation of the backing store</span> +<span class="cm"> * between threads is the responsibility of the managed context user.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * @see BoundContext</span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">ManagedContext</span> <span class="k">extends</span> <span class="n">Context</span> <span class="p">{</span> + + <span class="cm">/**</span> +<span class="cm"> * Activate the Context.</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">activate</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * Deactivate the Context, destroying any instances if the context is invalid.</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">deactivate</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * Mark the context as due for destruction when deactivate is called.</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">invalidate</span><span class="p">();</span> + +<span class="p">}</span> +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * Allows a thread-based context to be bound to some external instance storage</span> +<span class="cm"> * (such as an HttpSession).</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * A context may be <em>detachable</em> in which case a call to</span> +<span class="cm"> * {@link ManagedContext#invalidate()} will detach the context from it's</span> +<span class="cm"> * associated storage. A detached context is still usable (instances may be</span> +<span class="cm"> * added or removed) however changes will not be written through to the</span> +<span class="cm"> * underlying data store.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * Normally, a detachable context will have it's underlying bean store attached</span> +<span class="cm"> * on a call to {@link ManagedContext#activate()} and detached on a call to</span> +<span class="cm"> * {@link ManagedContext#deactivate()} however a subtype of {@link BoundContext}</span> +<span class="cm"> * may change this behavior.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * If you call {@link #associate(Object)} you must ensure that you call</span> +<span class="cm"> * {@link #dissociate(Object)} in all cases, otherwise you risk memory leaks.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * @param <S> the type of the external instance storage</span> +<span class="cm"> * @see ManagedContext</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">BoundContext</span><span class="o"><</span><span class="no">S</span><span class="o">></span> <span class="k">extends</span> <span class="n">Context</span> <span class="p">{</span> + + <span class="cm">/**</span> +<span class="cm"> * Associate the context with the storage (for this thread). Once</span> +<span class="cm"> * {@link #associate(Object)} has been called, further calls to</span> +<span class="cm"> * {@link #associate(Object)} will be ignored, until the context has been</span> +<span class="cm"> * subsequently {@link #dissociate(Object)} from the storage.</span> +<span class="cm"> *</span> +<span class="cm"> * @param storage the external storage</span> +<span class="cm"> * @return true if the storage was attached, otherwise false</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">boolean</span> <span class="n">associate</span><span class="p">(</span><span class="no">S</span> <span class="n">storage</span><span class="p">);</span> + + <span class="cm">/**</span> +<span class="cm"> * Dissociate the context from the storage (for this thread). The context</span> +<span class="cm"> * will only dissociate from the same storage it associated with.</span> +<span class="cm"> *</span> +<span class="cm"> * @param storage the external storage</span> +<span class="cm"> * @return true if the storage was dissociated</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">boolean</span> <span class="n">dissociate</span><span class="p">(</span><span class="no">S</span> <span class="n">storage</span><span class="p">);</span> + +<span class="p">}</span> + + +<span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * The built in dependent context, associated with {@link Dependent}. It is</span> +<span class="cm"> * always active.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * There is one Dependent context which can be injected using:</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <pre></span> +<span class="cm"> * &#064Inject DependentContext dependentContext;</span> +<span class="cm"> * </pre></span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">DependentContext</span> <span class="k">extends</span> <span class="n">Context</span> <span class="p">{</span> <span class="p">}</span> +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * The built in request context is associated with {@link RequestScoped} and is</span> +<span class="cm"> * a managed context which can be activated, invalidated and deactivated.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * CDI comes with one implementation of the request context. The</span> +<span class="cm"> * {@link HttpRequestContext}, in which conversations are bound to the</span> +<span class="cm"> * {@link ServletRequest}, can be injected:</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <pre></span> +<span class="cm"> * &#064Inject &#064Http RequestContext requestContext;</span> +<span class="cm"> * </pre></span> +<span class="cm"> *</span> +<span class="cm"> * @see HttpRequestContext</span> +<span class="cm"> * @see RequestScoped</span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">RequestContext</span> <span class="k">extends</span> <span class="n">ManagedContext</span> <span class="p">{}</span> +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * The built in session context is associated with {@link SessionScoped}. It can</span> +<span class="cm"> * be activated, invalidated and deactivated.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * CDI comes with one implementation of the session context. The</span> +<span class="cm"> * {@link HttpSessionContext}, in which conversations are bound to the</span> +<span class="cm"> * {@link HttpSession}, can be injected:</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <pre></span> +<span class="cm"> * &#064Inject &#064Http SessionContext sessionContext;</span> +<span class="cm"> * </pre></span> +<span class="cm"> *</span> +<span class="cm"> * @see HttpSessionContext</span> +<span class="cm"> * @sees {@link SessionScoped}</span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">SessionContext</span> <span class="k">extends</span> <span class="n">ManagedContext</span> <span class="p">{}</span> +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * The built in application context, associated with {@link ApplicationScoped}.</span> +<span class="cm"> * It is always active (not managed) and is backed by an application scoped</span> +<span class="cm"> * singleton.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * CDI comes with one Application context which can be injected using:</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <pre></span> +<span class="cm"> * &#064Inject ApplicationContext applicationContext;</span> +<span class="cm"> * </pre></span> +<span class="cm"> *</span> +<span class="cm"> * @see SingletonContext</span> +<span class="cm"> * @see ApplicationScoped</span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">ApplicationContext</span> <span class="k">extends</span> <span class="n">Context</span> <span class="p">{</span> + + <span class="cm">/**</span> +<span class="cm"> * Invalidate the context, causing all bean instances to be destroyed.</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">invalidate</span><span class="p">();</span> + +<span class="p">}</span> +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * The built in singleton context, associated with {@link Singleton}.</span> +<span class="cm"> * It is always active (not managed) and is backed by an application scoped</span> +<span class="cm"> * singleton.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * CDI comes with one Singleton context which can be injected using:</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <pre></span> +<span class="cm"> * &#064Inject SingletonContext singletonContext;</span> +<span class="cm"> * </pre></span> +<span class="cm"> *</span> +<span class="cm"> * @author Pete Muir</span> +<span class="cm"> * @see SingletonContext</span> +<span class="cm"> * @see ApplicationScoped</span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">SingletonContext</span> <span class="k">extends</span> <span class="n">Context</span> <span class="p">{}</span> +</pre></div> + + +<p>And these HTTP backed implementations:</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * A request context which can be bound to the {@link ServletRequest}. The</span> +<span class="cm"> * context is automatically attached to the map on activation, and detached when</span> +<span class="cm"> * {@link #invalidate()} is called.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * This context is not thread safe, and provides no thread safety for the</span> +<span class="cm"> * underlying map.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">HttpRequestContext</span> <span class="k">extends</span> <span class="n">BoundContext</span><span class="o"><</span><span class="n">ServletRequest</span><span class="o">></span><span class="p">,</span> <span class="n">RequestContext</span> <span class="p">{}</span> +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * A session context which can be bound to the {@link HttpServletRequest}. The</span> +<span class="cm"> * context is automatically attached to the map on activation, and detached when</span> +<span class="cm"> * {@link #invalidate()} is called.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * This context is not thread safe, and provides no thread safety for the</span> +<span class="cm"> * underlying map.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">HttpSessionContext</span> <span class="k">extends</span> <span class="n">BoundContext</span><span class="o"><</span><span class="n">HttpServletRequest</span><span class="o">></span><span class="p">,</span> <span class="n">SessionContext</span> +<span class="p">{</span> + + <span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * Mark the Session Context for destruction; the Session Context will be</span> +<span class="cm"> * detached from the underling Http Session, and instances marked for</span> +<span class="cm"> * destruction when the Http Request is destroyed.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">invalidate</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * Destroy the session and all conversations stored in the session.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * If the context is not currently associated with a</span> +<span class="cm"> * {@link HttpServletRequest}, then the context will be associated with the</span> +<span class="cm"> * specified {@link HttpSession} (for this thread), activated, destroyed, and</span> +<span class="cm"> * then deactivated.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * If the context is already associated with a {@link HttpServletRequest}</span> +<span class="cm"> * then this call will detach the context from the underlying Http Session,</span> +<span class="cm"> * and mark the context for destruction when the request is destroyed.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * @param session the {@link HttpSession} in which to store the bean</span> +<span class="cm"> * instances</span> +<span class="cm"> * @return true if the context was destroyed immediately</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">boolean</span> <span class="n">destroy</span><span class="p">(</span><span class="n">HttpSession</span> <span class="n">session</span><span class="p">);</span> + +<span class="p">}</span> +</pre></div> + + +<h1 id="map-bound-contexts">Map-bound contexts</h1> +<p>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.</p> +<p>Add these dependent scoped beans:</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * Allows a thread-based context to be bound to some external instance storage</span> +<span class="cm"> * (such as an HttpSession).</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * A context may be <em>detachable</em> in which case a call to</span> +<span class="cm"> * {@link ManagedContext#invalidate()} will detach the context from it's</span> +<span class="cm"> * associated storage. A detached context is still usable (instances may be</span> +<span class="cm"> * added or removed) however changes will not be written through to the</span> +<span class="cm"> * underlying data store.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * Normally, a detachable context will have it's underlying bean store attached</span> +<span class="cm"> * on a call to {@link ManagedContext#activate()} and detached on a call to</span> +<span class="cm"> * {@link ManagedContext#deactivate()} however a subtype of {@link BoundContext}</span> +<span class="cm"> * may change this behavior.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * If you call {@link #associate(Object)} you must ensure that you call</span> +<span class="cm"> * {@link #dissociate(Object)} in all cases, otherwise you risk memory leaks.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * @param <S> the type of the external instance storage</span> +<span class="cm"> * @see ManagedContext</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">BoundContext</span><span class="o"><</span><span class="no">S</span><span class="o">></span> <span class="k">extends</span> <span class="n">Context</span> +<span class="p">{</span> + + <span class="cm">/**</span> +<span class="cm"> * Associate the context with the storage (for this thread). Once</span> +<span class="cm"> * {@link #associate(Object)} has been called, further calls to</span> +<span class="cm"> * {@link #associate(Object)} will be ignored, until the context has been</span> +<span class="cm"> * subsequently {@link #dissociate(Object)} from the storage.</span> +<span class="cm"> *</span> +<span class="cm"> * @param storage the external storage</span> +<span class="cm"> * @return true if the storage was attached, otherwise false</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">boolean</span> <span class="n">associate</span><span class="p">(</span><span class="no">S</span> <span class="n">storage</span><span class="p">);</span> + + <span class="cm">/**</span> +<span class="cm"> * Dissociate the context from the storage (for this thread). The context</span> +<span class="cm"> * will only dissociate from the same storage it associated with.</span> +<span class="cm"> *</span> +<span class="cm"> * @param storage the external storage</span> +<span class="cm"> * @return true if the storage was dissociated</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">boolean</span> <span class="n">dissociate</span><span class="p">(</span><span class="no">S</span> <span class="n">storage</span><span class="p">);</span> + +<span class="p">}</span> +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * A request context which can be bound to any Map. The context is automatically</span> +<span class="cm"> * attached to the map on activation, and detached when {@link #invalidate()} is</span> +<span class="cm"> * called.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * This context is not thread safe, and provides no thread safety for the</span> +<span class="cm"> * underlying map. A thread-safe map can be used to back the context.</span> +<span class="cm"> * </p></span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">BoundRequestContext</span> <span class="k">extends</span> <span class="n">RequestContext</span><span class="p">,</span> <span class="n">BoundContext</span><span class="o"><</span><span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="p">,</span> <span class="n">Object</span><span class="o">>></span> <span class="p">{}</span> +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * A session context which can be bound to any Map. The context is automatically</span> +<span class="cm"> * attached to the map on activation, and detached when {@link #invalidate()} is</span> +<span class="cm"> * called.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * This context is not thread safe, and provides no thread safety for the</span> +<span class="cm"> * underlying map. A thread-safe map can be used to back the context.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">BoundSessionContext</span> <span class="k">extends</span> <span class="n">SessionContext</span><span class="p">,</span> <span class="n">BoundContext</span><span class="o"><</span><span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="p">,</span> <span class="n">Object</span><span class="o">>></span> <span class="p">{}</span> +</pre></div> + + +<p>As always, conversations are harder to model. In this case, we need to provide both a map for the "session" (in which a conversation may stored long term) and a map for the current "request".</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * A conversation is used to span multiple requests, however is shorter than a</span> +<span class="cm"> * session. The {@link BoundConversationContext} uses one Map to represent a</span> +<span class="cm"> * request, and a second to represent the session, which are encapsulated in a</span> +<span class="cm"> * {@link BoundRequest}.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">BoundRequest</span> <span class="p">{</span> + + <span class="cm">/**</span> +<span class="cm"> * Get the current request map.</span> +<span class="cm"> *</span> +<span class="cm"> * @return</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="p">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">getRequestMap</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * Get the current session map.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * A {@link BoundRequest} may be backed by a data store that only creates</span> +<span class="cm"> * sessions on demand. It is recommended that if the session is not created</span> +<span class="cm"> * on demand, or that the session has already been created (but is not</span> +<span class="cm"> * required by this access) that the session is returned as it allows the</span> +<span class="cm"> * conversation context to work more efficiently.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * @param create if true, then a session must be created</span> +<span class="cm"> * @return the session map; null may be returned if create is false</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="p">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">getSessionMap</span><span class="p">(</span><span class="n">boolean</span> <span class="n">create</span><span class="p">);</span> + +<span class="p">}</span> +</pre></div> + + +<h3 id="context-conversation-management-of-weld-core-api">Context / Conversation Management of Weld-Core (API)</h3> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * The built in conversation context is associated with</span> +<span class="cm"> * {@link ConversationScoped}. It can be activated, invalidated and deactivated.</span> +<span class="cm"> * and provides various options for configuring conversation defaults.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * CDI comes with one implementation of the conversation context. The</span> +<span class="cm"> * {@link HttpConversationContext}, in which conversations are bound to the</span> +<span class="cm"> * {@link HttpSession}, can be injected:</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <pre></span> +<span class="cm"> * &#064Inject &#064Http ConversationContext conversationContext;</span> +<span class="cm"> * </pre></span> +<span class="cm"> *</span> +<span class="cm"> * @see BoundConversationContext</span> +<span class="cm"> * @see HttpConversationContext</span> +<span class="cm"> * @see ConversationScoped</span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">ConversationContext</span> <span class="k">extends</span> <span class="n">ManagedContext</span> +<span class="p">{</span> + + <span class="cm">/**</span> +<span class="cm"> * Cause any expired conversations to be ended, and therefore marked for</span> +<span class="cm"> * destruction when deactivate is called.</span> +<span class="cm"> *</span> +<span class="cm"> * @throws IllegalStateException if the context is unable to access the</span> +<span class="cm"> * underlying data store</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">invalidate</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * Activate the conversation context, using the id provided to attempt to</span> +<span class="cm"> * restore a long-running conversation</span> +<span class="cm"> *</span> +<span class="cm"> * @param cid if the cid is null, a transient conversation will be created,</span> +<span class="cm"> * otherwise the conversation will be restored</span> +<span class="cm"> * @throws IllegalStateException if the context is unable to access the</span> +<span class="cm"> * underlying data store</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">activate</span><span class="p">(</span><span class="n">String</span> <span class="n">cid</span><span class="p">);</span> + + <span class="cm">/**</span> +<span class="cm"> * Activate the conversation context, starting a new transient conversation</span> +<span class="cm"> *</span> +<span class="cm"> * @throws IllegalStateException if the context is unable to access the</span> +<span class="cm"> * underlying data store</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">activate</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * Set the name of the parameter used to propagate the conversation id</span> +<span class="cm"> *</span> +<span class="cm"> * @param cid the name of the conversation id parameter</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">setParameterName</span><span class="p">(</span><span class="n">String</span> <span class="n">cid</span><span class="p">);</span> + + <span class="cm">/**</span> +<span class="cm"> * Get the name of the parameter used to propagate the conversation id</span> +<span class="cm"> *</span> +<span class="cm"> * @return the name of the conversation id parameter</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">String</span> <span class="n">getParameterName</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * Set the concurrent access timeout</span> +<span class="cm"> *</span> +<span class="cm"> * @param timeout the timeout (in ms) for the concurrent access lock</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">setConcurrentAccessTimeout</span><span class="p">(</span><span class="n">long</span> <span class="n">timeout</span><span class="p">);</span> + + <span class="cm">/**</span> +<span class="cm"> * Get the current concurrent access timeout</span> +<span class="cm"> *</span> +<span class="cm"> * @return the timeout (in ms) for the concurrent access lock</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">long</span> <span class="n">getConcurrentAccessTimeout</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * Set the default inactivity timeout. This may be overridden on a per</span> +<span class="cm"> * conversation basis using {@link Conversation#setTimeout(long)}</span> +<span class="cm"> *</span> +<span class="cm"> * @param timeout the default inactivity timeout (in ms)</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="k">void</span> <span class="n">setDefaultTimeout</span><span class="p">(</span><span class="n">long</span> <span class="n">timeout</span><span class="p">);</span> + + <span class="cm">/**</span> +<span class="cm"> * Get the default inactivity timeout. This may have been overridden on a per</span> +<span class="cm"> * conversation basis.</span> +<span class="cm"> *</span> +<span class="cm"> * @return the default inactivity timeout (in ms)</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">long</span> <span class="n">getDefaultTimeout</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * Get conversations currently known to the context. This will include any</span> +<span class="cm"> * non transient conversations, as well as any conversations which were</span> +<span class="cm"> * previously long running and have been made transient during this request.</span> +<span class="cm"> *</span> +<span class="cm"> * @return a collection containing the conversations</span> +<span class="cm"> *</span> +<span class="cm"> * @throws IllegalStateException if the context is unable to access the</span> +<span class="cm"> * underlying data store</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">Collection</span><span class="o"><</span><span class="n">ManagedConversation</span><span class="o">></span> <span class="n">getConversations</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * Get the conversation with the given id.</span> +<span class="cm"> *</span> +<span class="cm"> * @param id the id of the conversation to get</span> +<span class="cm"> * @return the conversation, or null if no conversation is known</span> +<span class="cm"> *</span> +<span class="cm"> * @throws IllegalStateException if the context is unable to access the</span> +<span class="cm"> * underlying data store</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">ManagedConversation</span> <span class="n">getConversation</span><span class="p">(</span><span class="n">String</span> <span class="n">id</span><span class="p">);</span> + + <span class="cm">/**</span> +<span class="cm"> * Generate a new, unique, conversation id</span> +<span class="cm"> *</span> +<span class="cm"> * @return a new, unique conversation id</span> +<span class="cm"> *</span> +<span class="cm"> * @throws IllegalStateException if the context is unable to access the</span> +<span class="cm"> * underlying data store</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">String</span> <span class="n">generateConversationId</span><span class="p">();</span> + + <span class="cm">/**</span> +<span class="cm"> * Get a handle the current conversation (transient or otherwise).</span> +<span class="cm"> *</span> +<span class="cm"> * @return the current conversation</span> +<span class="cm"> * @throws IllegalStateException if the context is unable to access the</span> +<span class="cm"> * underlying data store</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">ManagedConversation</span> <span class="n">getCurrentConversation</span><span class="p">();</span> + +<span class="p">}</span> +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre>package org.jboss.weld.context; + +import javax.enterprise.context.ContextNotActiveException; +import javax.enterprise.context.Conversation; + +/** + * <span class="nt"><p></span> + * Provides management operations for conversations, including locking, and + * expiration management. + * <span class="nt"></p></span> + * + * @see ConversationContext + * + */ +public interface ManagedConversation extends Conversation { + + /** + * Attempts to unlock the conversation + * + * @throws ContextNotActiveException if the conversation context is not + * active + * @return true if the unlock was successful, false otherwise + */ + public boolean unlock(); + + /** + * Attempts to lock the conversation for exclusive usage + * + * @param timeout The time in milliseconds to wait on the lock + * @return True if lock was successful, false otherwise + * @throws InterruptedException if the lock operation was unsuccessful * @throws + * @throws ContextNotActiveException if the conversation context is not + * active + */ + public boolean lock(long timeout); + + /** + * Gets the last time the conversation was used (for data access) + * + * @return time (in ms) since the conversation was last used + * @throws ContextNotActiveException if the conversation context is not + * active + */ + public long getLastUsed(); + + /** + * Touches the managed conversation, updating the "last used" timestamp + * + * @throws ContextNotActiveException if the conversation context is not + * active + */ + public void touch(); + +} +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * A conversation context which can be bound to a pair of Maps encapsulated by</span> +<span class="cm"> * {@link BoundRequest}. The context is automatically attached to the bound</span> +<span class="cm"> * request on activation, and detached when {@link #invalidate()} is called.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * The {@link BoundConversationContext} is detachable, and transient</span> +<span class="cm"> * conversations are only attached at the end of a request.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * This context is not thread safe, and provides no thread safety for the</span> +<span class="cm"> * underlying map. A thread-safe map can be used to back the context - in this</span> +<span class="cm"> * case the map can be used as an underlying store in multiple threads safely.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">BoundConversationContext</span> <span class="k">extends</span> <span class="n">ConversationContext</span><span class="p">,</span> <span class="n">BoundContext</span><span class="o"><</span><span class="n">BoundRequest</span><span class="o">></span> +<span class="p">{</span> + + <span class="cm">/**</span> +<span class="cm"> * Destroy all conversations in the session.</span> +<span class="cm"> *</span> +<span class="cm"> * @param session the session for which to destroy all conversations</span> +<span class="cm"> * @return</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">boolean</span> <span class="n">destroy</span><span class="p">(</span><span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="p">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">session</span><span class="p">);</span> + +<span class="p">}</span> +</pre></div> + + +<p>b</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * An Http Session backed conversation context. A transient conversation will be</span> +<span class="cm"> * detached from the underlying session. If the conversation is promoted to long</span> +<span class="cm"> * running, context will be attached to the underlying Http Session at the end</span> +<span class="cm"> * of the request.</span> +<span class="cm"> *</span> +<span class="cm"> */</span> +<span class="n">public</span> <span class="k">interface</span> <span class="n">HttpConversationContext</span> <span class="k">extends</span> <span class="n">BoundContext</span><span class="o"><</span><span class="n">HttpServletRequest</span><span class="o">></span><span class="p">,</span> <span class="n">ConversationContext</span> +<span class="p">{</span> + + <span class="cm">/**</span> +<span class="cm"> * <p></span> +<span class="cm"> * If the context is not currently associated with a</span> +<span class="cm"> * {@link HttpServletRequest}, then the context will be associated with the</span> +<span class="cm"> * specified {@link HttpSession} (for this thread), activated, destroyed, and</span> +<span class="cm"> * then deactivated. Any conversations associated with the context will also</span> +<span class="cm"> * be destroyed.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * If the context is already associated with a {@link HttpServletRequest}</span> +<span class="cm"> * then this call will detach the context from the underlying Http Session,</span> +<span class="cm"> * and mark the context for destruction when the request is destroyed.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * <p></span> +<span class="cm"> * This will cause any transient conversations, and any long running</span> +<span class="cm"> * conversations associated with the session, to be destroyed.</span> +<span class="cm"> * </p></span> +<span class="cm"> *</span> +<span class="cm"> * @param session the {@link HttpSession} in which to store the bean</span> +<span class="cm"> * instances</span> +<span class="cm"> * @return true if the context was destroyed immediately</span> +<span class="cm"> */</span> + <span class="n">public</span> <span class="n">boolean</span> <span class="n">destroy</span><span class="p">(</span><span class="n">HttpSession</span> <span class="n">session</span><span class="p">);</span> + +<span class="p">}</span> +</pre></div> + </div> + </div> + + <hr> + + <footer> + <p>Copyright © 20011-2012 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.</p> + <p>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p> + </footer> + + </div> <!-- /container --> + + <!-- Javascript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <!--<script src="./../deltaspike/resources/js/prettyfy.js"></script> --> + <script src="./../deltaspike/resources/js/prettyprint.js"></script> + <script src="./../deltaspike/resources/js/jquery.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-transition.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-alert.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-modal.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-dropdown.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-scrollspy.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-tab.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-tooltip.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-popover.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-button.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-collapse.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-carousel.js"></script> + <script src="./../deltaspike/resources/js/bootstrap-typeahead.js"></script> + +</body> +</html> \ No newline at end of file
