You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by bu...@apache.org on 2013/06/09 11:26:33 UTC
svn commit: r864998 [7/15] - in /websites/staging/deltaspike/trunk/content:
./ deltaspike/ deltaspike/draft/ deltaspike/resources/ draft/ resources/
resources/css/ resources/files/ resources/images/ resources/js/
Added: websites/staging/deltaspike/trunk/content/draft/exception_draft.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/draft/exception_draft.html (added)
+++ websites/staging/deltaspike/trunk/content/draft/exception_draft.html Sun Jun 9 09:26:31 2013
@@ -0,0 +1,1445 @@
+<!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 - Exception Control Draft</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>Exception Control Draft</h1>
+ </div>
+ <h1 id="agreed-api">Agreed API</h1>
+<div class="codehilite"><pre><span class="err">@</span><span class="n">Retention</span><span class="p">(</span><span class="n">RetentionPolicy</span><span class="p">.</span><span class="n">RUNTIME</span><span class="p">)</span>
+<span class="err">@</span><span class="n">Target</span><span class="p">(</span><span class="n">ElementType</span><span class="p">.</span><span class="n">PARAMETER</span><span class="p">)</span>
+<span class="err">@</span><span class="n">Documented</span>
+<span class="n">public</span> <span class="err">@</span><span class="n">interface</span> <span class="n">BeforeHandles</span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * Precedence relative to callbacks for the same type</span>
+<span class="cm"> */</span>
+ <span class="kt">int</span> <span class="n">ordinal</span><span class="p">()</span> <span class="k">default</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>b</p>
+<div class="codehilite"><pre><span class="err">@</span><span class="n">Retention</span><span class="p">(</span><span class="n">RetentionPolicy</span><span class="p">.</span><span class="n">RUNTIME</span><span class="p">)</span>
+<span class="err">@</span><span class="n">Target</span><span class="p">(</span><span class="n">ElementType</span><span class="p">.</span><span class="n">PARAMETER</span><span class="p">)</span>
+<span class="err">@</span><span class="n">Documented</span>
+<span class="n">public</span> <span class="err">@</span><span class="n">interface</span> <span class="n">Handles</span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * Precedence relative to handlers for the same type</span>
+<span class="cm"> */</span>
+ <span class="kt">int</span> <span class="n">ordinal</span><span class="p">()</span> <span class="k">default</span> <span class="mi">0</span><span class="p">;</span> <span class="c1">//TODO discuss Precedence</span>
+<span class="p">}</span>
+
+<span class="cm">/**</span>
+<span class="cm"> * Marker for types containing Exception Handler methods.</span>
+<span class="cm"> */</span>
+<span class="err">@</span><span class="n">Retention</span><span class="p">(</span><span class="n">RetentionPolicy</span><span class="p">.</span><span class="n">RUNTIME</span><span class="p">)</span>
+<span class="err">@</span><span class="n">Target</span><span class="p">(</span><span class="n">ElementType</span><span class="p">.</span><span class="n">TYPE</span><span class="p">)</span>
+<span class="err">@</span><span class="n">Documented</span>
+<span class="n">public</span> <span class="err">@</span><span class="n">interface</span> <span class="n">ExceptionHandler</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"> * Payload for an exception to be handled. Implementations of this interface should not expose internals and remain</span>
+<span class="cm"> * immutable for this contract.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param <T> Exception type this event represents</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">interface</span> <span class="n">ExceptionEvent</span><span class="o"><</span><span class="no">T</span> <span class="k">extends</span> <span class="n">Throwable</span><span class="o">></span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * The exception causing this event.</span>
+<span class="cm"> */</span>
+ <span class="no">T</span> <span class="n">getException</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Instructs the dispatcher to abort further processing of handlers.</span>
+<span class="cm"> */</span>
+ <span class="k">void</span> <span class="n">abort</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Instructs the dispatcher to throw the original exception after handler processing.</span>
+<span class="cm"> */</span>
+ <span class="k">void</span> <span class="n">throwOriginal</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Instructs the dispatcher to terminate additional handler processing and mark the event as handled.</span>
+<span class="cm"> */</span>
+ <span class="k">void</span> <span class="n">handled</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Default instruction to dispatcher, continues handler processing.</span>
+<span class="cm"> */</span>
+ <span class="k">void</span> <span class="n">handledAndContinue</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Similar to {@link ExceptionEvent#handledAndContinue()},</span>
+<span class="cm"> * but instructs the dispatcher to markHandled to the next element</span>
+<span class="cm"> * in the cause chain without processing additional handlers for this cause chain element.</span>
+<span class="cm"> */</span>
+ <span class="k">void</span> <span class="n">skipCause</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Instructs the dispatcher to allow this handler to be invoked again.</span>
+<span class="cm"> */</span>
+ <span class="k">void</span> <span class="n">unmute</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Rethrow the exception, but use the given exception instead of the original.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param t Exception to be thrown in place of the original.</span>
+<span class="cm"> */</span>
+ <span class="k">void</span> <span class="n">rethrow</span><span class="p">(</span><span class="n">Throwable</span> <span class="n">t</span><span class="p">);</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Check to see if this exception has been handled.</span>
+<span class="cm"> */</span>
+ <span class="n">boolean</span> <span class="n">isMarkedHandled</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>b</p>
+<div class="codehilite"><pre><span class="c1">//TODO discuss the introduction of an interface</span>
+<span class="cm">/**</span>
+<span class="cm"> * Information about the current exception and exception cause container. This object is not immutable.</span>
+<span class="cm"> */</span>
+<span class="p">@</span><span class="n">Typed</span><span class="p">()</span>
+<span class="n">public</span> <span class="k">class</span> <span class="n">ExceptionStackEvent</span> <span class="n">implements</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="n">private</span> <span class="k">static</span> <span class="k">final</span> <span class="n">long</span> <span class="n">serialVersionUID</span> <span class="o">=</span> <span class="o">-</span><span class="mh">6069790756478700680</span><span class="no">L</span><span class="p">;</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Builds the stack from the given exception.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param exception Caught exception</span>
+<span class="cm"> */</span>
+ <span class="n">public</span> <span class="n">ExceptionStackEvent</span><span class="p">(</span><span class="k">final</span> <span class="n">Throwable</span> <span class="n">exception</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">Collection</span><span class="o"><</span><span class="n">Throwable</span><span class="o">></span> <span class="n">getCauseElements</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Test if iteration is finished</span>
+<span class="cm"> *</span>
+<span class="cm"> * @return finished with iteration</span>
+<span class="cm"> */</span>
+ <span class="n">public</span> <span class="n">boolean</span> <span class="n">isLast</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">Throwable</span> <span class="n">getNext</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">Collection</span><span class="o"><</span><span class="n">Throwable</span><span class="o">></span> <span class="n">getRemaining</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Tests if the current exception is the root exception</span>
+<span class="cm"> *</span>
+<span class="cm"> * @return Returns true if iteration is at the root exception (top of the inverted stack)</span>
+<span class="cm"> */</span>
+ <span class="n">public</span> <span class="n">boolean</span> <span class="n">isRoot</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Current exception in the iteration</span>
+<span class="cm"> *</span>
+<span class="cm"> * @return current exception</span>
+<span class="cm"> */</span>
+ <span class="n">public</span> <span class="n">Throwable</span> <span class="n">getCurrent</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Internal only.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param elements new stack.</span>
+<span class="cm"> */</span>
+ <span class="n">public</span> <span class="k">void</span> <span class="n">setCauseElements</span><span class="p">(</span><span class="n">Collection</span><span class="o"><</span><span class="n">Throwable</span><span class="o">></span> <span class="n">elements</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="c1">//...</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"> * Entry point event into the Catch system. This object is nearly immutable, the only mutable portion</span>
+<span class="cm"> * is the handled flag.</span>
+<span class="cm"> */</span>
+<span class="p">@</span><span class="n">Typed</span><span class="p">()</span>
+<span class="n">public</span> <span class="k">class</span> <span class="n">ExceptionToCatchEvent</span> <span class="n">implements</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * Constructor that adds qualifiers for the handler(s) to run.</span>
+<span class="cm"> * Typically only integrators will be using this constructor.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param exception Exception to handle</span>
+<span class="cm"> * @param qualifiers qualifiers to use to narrow the handlers called</span>
+<span class="cm"> */</span>
+ <span class="n">public</span> <span class="n">ExceptionToCatchEvent</span><span class="p">(</span><span class="n">Throwable</span> <span class="n">exception</span><span class="p">,</span> <span class="n">Annotation</span><span class="p">...</span> <span class="n">qualifiers</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Basic constructor without any qualifiers defined.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param exception Exception to handle.</span>
+<span class="cm"> */</span>
+ <span class="n">public</span> <span class="n">ExceptionToCatchEvent</span><span class="p">(</span><span class="n">Throwable</span> <span class="n">exception</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">Throwable</span> <span class="n">getException</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Internal only.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param handled new value</span>
+<span class="cm"> */</span>
+ <span class="n">public</span> <span class="k">void</span> <span class="n">setHandled</span><span class="p">(</span><span class="n">boolean</span> <span class="n">handled</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Test to see if the exception has been handled via Solder Catch.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @return test if the exception has been through Solder Catch handling.</span>
+<span class="cm"> */</span>
+ <span class="n">public</span> <span class="n">boolean</span> <span class="n">isHandled</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Qualifiers with which the instance was created.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @return Qualifiers with which the instance was created.</span>
+<span class="cm"> */</span>
+ <span class="n">public</span> <span class="n">Set</span><span class="o"><</span><span class="n">Annotation</span><span class="o">></span> <span class="n">getQualifiers</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</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"> * Flow control enum. Used in the dispatcher to determine how to markHandled.</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">enum</span> <span class="n">ExceptionHandlingFlow</span>
+<span class="p">{</span>
+ <span class="no">HANDLED</span><span class="p">,</span>
+ <span class="no">HANDLED_AND_CONTINUE</span><span class="p">,</span>
+ <span class="no">SKIP_CAUSE</span><span class="p">,</span>
+ <span class="no">ABORT</span><span class="p">,</span>
+ <span class="no">THROW_ORIGINAL</span><span class="p">,</span>
+ <span class="no">THROW</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>b</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Container for the exception and it's stack trace.</span>
+<span class="cm"> */</span>
+<span class="p">@</span><span class="n">Typed</span><span class="p">()</span>
+<span class="n">public</span> <span class="k">final</span> <span class="k">class</span> <span class="n">ExceptionStackItem</span> <span class="n">implements</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="n">public</span> <span class="n">ExceptionStackItem</span><span class="p">(</span><span class="k">final</span> <span class="n">Throwable</span> <span class="n">cause</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">ExceptionStackItem</span><span class="p">(</span><span class="n">Throwable</span> <span class="n">throwable</span><span class="p">,</span> <span class="n">StackTraceElement</span><span class="p">[]</span> <span class="n">stackTraceElements</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">StackTraceElement</span><span class="p">[]</span> <span class="n">getStackTraceElements</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">Throwable</span> <span class="n">getThrowable</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="c1">//...</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"> * Meta data interface about an exception handler. It is the responsibility of the</span>
+<span class="cm"> * implementation to support {@link javax.enterprise.inject.spi.InjectionPoint}s and to</span>
+<span class="cm"> * validate those {@link javax.enterprise.inject.spi.InjectionPoint}s.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param <T> Exception for which this handler is responsible</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">interface</span> <span class="n">HandlerMethod</span><span class="o"><</span><span class="no">T</span> <span class="k">extends</span> <span class="n">Throwable</span><span class="o">></span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * Obtains the set of handled event qualifiers.</span>
+<span class="cm"> */</span>
+ <span class="n">Set</span><span class="o"><</span><span class="n">Annotation</span><span class="o">></span> <span class="n">getQualifiers</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Obtains the handled event type.</span>
+<span class="cm"> */</span>
+ <span class="n">Type</span> <span class="n">getExceptionType</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Flag indicating this handler should be invoked during the before traversal.</span>
+<span class="cm"> */</span>
+ <span class="n">boolean</span> <span class="n">isBeforeHandler</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Calls the handler method, passing the given event object.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param event event to pass to the handler.</span>
+<span class="cm"> */</span>
+ <span class="k">void</span> <span class="n">notify</span><span class="p">(</span><span class="n">ExceptionEvent</span><span class="o"><</span><span class="no">T</span><span class="o">></span> <span class="k">event</span><span class="p">);</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Obtains the precedence of the handler.</span>
+<span class="cm"> */</span>
+ <span class="k">int</span> <span class="n">getOrdinal</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Basic {@link Object#equals(Object)} but must use all of the get methods from this interface to</span>
+<span class="cm"> * maintain compatibility.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param o Object being compared to this.</span>
+<span class="cm"> * @return true or false based on standard equality.</span>
+<span class="cm"> */</span>
+ <span class="p">@</span><span class="n">Override</span>
+ <span class="n">boolean</span> <span class="n">equals</span><span class="p">(</span><span class="n">Object</span> <span class="n">o</span><span class="p">);</span>
+
+ <span class="p">@</span><span class="n">Override</span>
+ <span class="k">int</span> <span class="n">hashCode</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h1 id="under-discussion">Under discussion</h1>
+<ul>
+<li>Exception Handlers</li>
+<li>Entry into the Exception Handling system</li>
+</ul>
+<h2 id="apispi">API/SPI</h2>
+<h1 id="use-cases">Use-cases</h1>
+<h2 id="fire-and-observe-exceptions">Fire and observe exceptions</h2>
+<p>An exception happens either in some business logic or from the container (maybe a session timed out or something like that). Developers need a simple, easy to use way to handle exceptions in a uniform way. They also need to be able to tell, after exception handling, if the exception was actually handled (a handler was found for the particular exception type or super type) or if it needs to be bubbled up to a higher level.</p>
+<h3 id="scenario">Scenario</h3>
+<div class="codehilite"><pre><span class="n">Business</span> <span class="n">method</span> <span class="n">using</span> <span class="k">try</span> <span class="o">/</span> <span class="k">catch</span>
+<span class="n">public</span> <span class="n">void</span> <span class="n">myBusinessMethod</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="k">try</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="p">}</span> <span class="k">catch</span> <span class="p">(</span><span class="n">Exception</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">entry</span> <span class="n">into</span> <span class="n">exception</span> <span class="n">handling</span> <span class="n">system</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>b</p>
+<div class="codehilite"><pre><span class="n">JSF</span> <span class="n">integration</span>
+<span class="n">public</span> <span class="n">void</span> <span class="n">handle</span><span class="p">()</span> <span class="n">throws</span> <span class="n">FacesException</span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">iterate</span> <span class="n">over</span> <span class="n">exceptions</span>
+ <span class="o">//</span> <span class="n">entry</span> <span class="n">into</span> <span class="n">exception</span> <span class="n">handling</span> <span class="n">system</span>
+ <span class="o">//</span> <span class="n">exception</span> <span class="n">handling</span> <span class="n">inspection</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>b</p>
+<div class="codehilite"><pre><span class="n">JAX</span><span class="o">-</span><span class="n">RS</span> <span class="n">integration</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">MyExceptionMapper</span> <span class="n">implements</span> <span class="n">ExceptionMapper</span><span class="o"><</span><span class="n">Throwable</span><span class="o">></span> <span class="p">{</span>
+ <span class="n">public</span> <span class="n">Response</span> <span class="n">toResponse</span><span class="p">(</span><span class="n">E</span> <span class="n">exception</span><span class="p">)</span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">entry</span> <span class="n">into</span> <span class="n">exception</span> <span class="n">handling</span> <span class="n">system</span>
+ <span class="o">//</span> <span class="n">exception</span> <span class="n">handling</span> <span class="n">inspection</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h1 id="message-module-draft">Message module draft</h1>
+<h1 id="features-to-merge">Features to merge</h1>
+<p>original list: https://issues.apache.org/jira/browse/DELTASPIKE-119</p>
+<h2 id="part-1">Part 1</h2>
+<p>|| Feature || Comments || Objections || Discussion finished
+| Basic API | | | (+) |
+| Serializable messages | | not compatible with type-safe messages | |
+| Transferable messages (resolve the final text for a different context (locale,â¦)) and context-config | | | (+) |
+| custom message types | | | |
+| creating messages via builder pattern | | | (+) |
+| numbered message arguments | | | (+) |
+| eval existing converter approach for numbered message arguments | | | |
+| message resolver to support different message-sources | | | (+) |
+| message interpolator | | | (+) |
+| locale resolver | | | (+) due to type-safe messages it changed a bit - we have to re-visit it |
+| type safe messages | | | (+) |</p>
+<h2 id="part-2">Part 2</h2>
+<p>This part depends on decissions of part 1.</p>
+<p>|| Feature || Comments || Objections || Discussion finished
+| el support (= el interpolation) | | | |
+| named message arguments | | | |
+| message payload -> allows to control processing of the message (via custom impl. of different SPIs) â similar to payload in bean-validation | | | |
+| message context (config) is immutable to avoid side-effects | | | |
+| clone a message context to use the same config but itâs possible to change it before the new context gets created (and is immutable) | | | |
+| formatter to allow to format argument-values for the final message text (similar to a converter -> we can think about merging the concepts) | | | |
+| tooling for devs to generate their own type-safe messages | | | |
+| messages within a database, or any other possible back end | | | |
+| inline translated type safe messages | | | |
+| pluralizer system for message i18n | | | |
+| static helpers for simple messages | | | |</p>
+<h2 id="part-3">Part 3</h2>
+<p>This part depends on the planned integration with other technologies like JSF, BV,...</p>
+<p>|| Feature || Comments || Objections || Discussion finished
+| add message to the "current" context | | | |
+| factories to customize the default behaviour | | | |
+| allows multi-tenant support | | | |
+| message targets (ie. a message for a specific component) | | | |
+| application and client locale | | | |
+| application and client timezone | | | |
+| support jsr310 dates | | | |
+| transaction phase for message, ie. only produce a message when a transaction is committed (usually used in conjunction with observers) | | | |
+| integrate type safe messages with bean validation | | | |
+| ability to hook Bean Validation messages into same infrastructure | needs clarification - reason: ConstraintViolation#getMessage returns a string | | |
+| ability to hook JSF validation messages into same infrastructure | see "current" context | | |
+| messages surviving multiple http redirects | | | |</p>
+<h2 id="part-4">Part 4</h2>
+<p>This part contains features for integrating 3rd party libraries.</p>
+<p>|| Feature || Comments || Objections || Discussion finished
+| support joda-time dates | | | |</p>
+<h1 id="agreed-api_1">Agreed API</h1>
+<h2 id="basic-api">Basic API</h2>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Basic interface for all message-types</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">interface</span> <span class="n">Message</span> <span class="k">extends</span> <span class="n">Localizable</span><span class="p">,</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * @return the message key (or inline-text) of the current message</span>
+<span class="cm"> */</span>
+ <span class="n">String</span> <span class="n">getDescriptor</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @return all named and numbered arguments</span>
+<span class="cm"> */</span>
+ <span class="n">Serializable</span><span class="p">[]</span> <span class="n">getArguments</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @param arguments 1-n new arguments for the current message</span>
+<span class="cm"> * @return the current instance</span>
+<span class="cm"> */</span>
+ <span class="n">Message</span> <span class="n">addArgument</span><span class="p">(</span><span class="n">Serializable</span><span class="p">...</span> <span class="n">arguments</span><span class="p">);</span>
+
+ <span class="cm">/*</span>
+<span class="cm"> * TBD</span>
+<span class="cm"> */</span>
+ <span class="n">String</span> <span class="n">toText</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>b</p>
+<div class="codehilite"><pre><span class="p">@</span><span class="n">MessageBundle</span>
+<span class="n">public</span> <span class="n">interface</span> <span class="n">CustomMessageBundle</span>
+<span class="p">{</span>
+ <span class="p">@</span><span class="n">Message</span><span class="p">(</span>"<span class="n">Hello</span> <span class="c">%s")</span>
+ <span class="n">Message</span> <span class="n">sayHello</span><span class="p">(</span><span class="n">String</span> <span class="n">cause</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="o">//</span><span class="p">...</span>
+
+<span class="p">@</span><span class="n">Inject</span>
+<span class="n">private</span> <span class="n">CustomMessageBundle</span> <span class="n">messages</span><span class="p">;</span>
+
+<span class="o">//</span><span class="p">...</span>
+
+<span class="n">String</span> <span class="n">messageText</span><span class="p">;</span>
+<span class="n">messageText</span> <span class="p">=</span> <span class="n">messages</span><span class="p">.</span><span class="n">sayHello</span><span class="p">(</span>"<span class="n">DeltaSpike</span>"<span class="p">).</span><span class="n">toText</span><span class="p">();</span>
+<span class="o">//</span><span class="n">or</span>
+<span class="n">messageText</span> <span class="p">=</span> <span class="n">messages</span><span class="p">.</span><span class="n">sayHello</span><span class="p">(</span>"<span class="n">DeltaSpike</span>"<span class="p">).</span><span class="n">toString</span><span class="p">();</span>
+<span class="o">//</span><span class="n">or</span>
+<span class="n">Message</span> <span class="n">message</span> <span class="p">=</span> <span class="n">messages</span><span class="p">.</span><span class="n">sayHello</span><span class="p">(</span>"<span class="n">DeltaSpike</span>"<span class="p">);</span>
+</pre></div>
+
+
+<h1 id="api-under-discussion-part-1">API under discussion - Part 1</h1>
+<h2 id="message-interface">Message Interface</h2>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Basic interface for all message-types</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">interface</span> <span class="n">Message</span> <span class="k">extends</span> <span class="n">Localizable</span><span class="p">,</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * @return the message key (or inline-text) of the current message</span>
+<span class="cm"> */</span>
+ <span class="n">String</span> <span class="n">getDescriptor</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @return all named and numbered arguments</span>
+<span class="cm"> */</span>
+ <span class="n">Serializable</span><span class="p">[]</span> <span class="n">getArguments</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @param arguments 1-n new arguments for the current message</span>
+<span class="cm"> * @return the current instance</span>
+<span class="cm"> */</span>
+ <span class="n">Message</span> <span class="n">addArgument</span><span class="p">(</span><span class="n">Serializable</span><span class="p">...</span> <span class="n">arguments</span><span class="p">);</span>
+
+ <span class="c1">//TODO check compatibility with type-safe messages</span>
+ <span class="c1">//payload postponed (addPayload, getPayload)</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="localizable">Localizable</h2>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Classes which implement it can provide the message-text based on the given {@link MessageContext}</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">interface</span> <span class="n">Localizable</span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * @param messageContext the current context</span>
+<span class="cm"> * @return the text which represents the current instance for the given message context</span>
+<span class="cm"> */</span>
+ <span class="n">String</span> <span class="n">toString</span><span class="p">(</span><span class="n">MessageContext</span> <span class="n">messageContext</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="messageinterpolator">MessageInterpolator</h2>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Implementations are responsible to replace placeholders in a message with the final value</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">interface</span> <span class="n">MessageInterpolator</span> <span class="k">extends</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * replaces the arguments of the given message with the given arguments</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param messageContext the current {@link org.apache.myfaces.extensions.cdi.message.api.MessageContext}</span>
+<span class="cm"> * instead of a MessageContextAware interface. we need it to avoid expensive operations like locking or deep cloning</span>
+<span class="cm"> * @param messageText the message text which has to be interpolated</span>
+<span class="cm"> * @param arguments a list of numbered and/or named arguments for the current message</span>
+<span class="cm"> * @return the final (interpolated) message text</span>
+<span class="cm"> * if it was possible to replace the parameters with the given arguments</span>
+<span class="cm"> * the unmodified messageText otherwise</span>
+<span class="cm"> */</span>
+ <span class="n">String</span> <span class="n">interpolate</span><span class="p">(</span><span class="n">MessageContext</span> <span class="n">messageContext</span><span class="p">,</span> <span class="n">String</span> <span class="n">messageText</span><span class="p">,</span> <span class="n">Serializable</span><span class="p">...</span> <span class="n">arguments</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="messageresolver">MessageResolver</h2>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Implementations have to resolve the text stored for a given key in the message-source they are aware of</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">interface</span> <span class="n">MessageResolver</span> <span class="k">extends</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="n">String</span> <span class="no">MISSING_RESOURCE_MARKER</span> <span class="o">=</span> <span class="s">"???"</span><span class="p">;</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @param messageContext the current {@link org.apache.myfaces.extensions.cdi.message.api.MessageContext}</span>
+<span class="cm"> * @param messageDescriptor the message key (or in-lined text) of the current message</span>
+<span class="cm"> * @param payload //TBD the payload of the message e.g. to use different message sources</span>
+<span class="cm"> * @return the final but not interpolated message text</span>
+<span class="cm"> */</span>
+ <span class="n">String</span> <span class="n">getMessage</span><span class="p">(</span><span class="n">MessageContext</span> <span class="n">messageContext</span><span class="p">,</span>
+ <span class="n">String</span> <span class="n">messageDescriptor</span><span class="p">,</span>
+ <span class="cm">/*TBD*/</span> <span class="n">Map</span><span class="o"><</span><span class="n">Class</span><span class="p">,</span> <span class="n">MessagePayload</span><span class="o">></span> <span class="n">payload</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="localeresolver">LocaleResolver</h2>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Implementations have to provide the current locale</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">interface</span> <span class="n">LocaleResolver</span> <span class="k">extends</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * @return the current locale</span>
+<span class="cm"> */</span>
+ <span class="n">Locale</span> <span class="n">getLocale</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="messagecontext">MessageContext</h2>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Central context for handling messages</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">interface</span> <span class="n">MessageContext</span> <span class="k">extends</span> <span class="n">LocaleResolver</span><span class="p">,</span> <span class="n">MessageHandler</span><span class="p">,</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * @return message builder to add and/or create a new message based on the current context via a fluent api</span>
+<span class="cm"> */</span>
+ <span class="n">MessageBuilder</span> <span class="n">message</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @return the current config to change it or create a new one base on the current config</span>
+<span class="cm"> */</span>
+ <span class="n">MessageContextConfig</span> <span class="k">config</span><span class="p">();</span>
+
+
+
+ <span class="cm">/*</span>
+<span class="cm"> * TBD:</span>
+<span class="cm"> */</span>
+
+
+ <span class="cm">/**</span>
+<span class="cm"> * @param contextType the type of the custom implementation</span>
+<span class="cm"> * @return the instance of the current message context to use the api of the concrete implementation</span>
+<span class="cm"> */</span>
+ <span class="o"><</span><span class="no">T</span> <span class="k">extends</span> <span class="n">MessageContext</span><span class="o">></span> <span class="no">T</span> <span class="n">typed</span><span class="p">(</span><span class="n">Class</span><span class="o"><</span><span class="no">T</span><span class="o">></span> <span class="n">contextType</span><span class="p">);</span>
+
+ <span class="cm">/*</span>
+<span class="cm"> * convenient methods</span>
+<span class="cm"> */</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @return creates a new context based on the current one</span>
+<span class="cm"> */</span>
+ <span class="n">MessageContext</span> <span class="n">cloneContext</span><span class="p">();</span>
+
+ <span class="c1">//the rest will be discussed later</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="messagecontextconfig">MessageContextConfig</h2>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Config for customizing a {@link MessageContext}</span>
+<span class="cm"> */</span>
+<span class="n">public</span> <span class="k">interface</span> <span class="n">MessageContextConfig</span> <span class="k">extends</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * create a new context based on the default context - the default context won't get modified</span>
+<span class="cm"> *</span>
+<span class="cm"> * @return a message context builder based on the current config</span>
+<span class="cm"> */</span>
+ <span class="n">MessageContextBuilder</span> <span class="k">use</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * change the default context</span>
+<span class="cm"> *</span>
+<span class="cm"> * @return a message context builder to change the current config</span>
+<span class="cm"> */</span>
+ <span class="n">MessageContextBuilder</span> <span class="n">change</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @return the current message interpolator</span>
+<span class="cm"> */</span>
+ <span class="n">MessageInterpolator</span> <span class="n">getMessageInterpolator</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @return the current message resolver</span>
+<span class="cm"> */</span>
+ <span class="n">MessageResolver</span> <span class="n">getMessageResolver</span><span class="p">();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @return the current locale resolver</span>
+<span class="cm"> */</span>
+ <span class="n">LocaleResolver</span> <span class="n">getLocaleResolver</span><span class="p">();</span>
+
+ <span class="c1">//the rest will be discussed later</span>
+
+ <span class="k">interface</span> <span class="n">MessageContextBuilder</span>
+ <span class="p">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * @param messageInterpolator a new message interpolator</span>
+<span class="cm"> * @return the instance of the current message context builder</span>
+<span class="cm"> */</span>
+ <span class="n">MessageContextBuilder</span> <span class="n">messageInterpolator</span><span class="p">(</span><span class="n">MessageInterpolator</span> <span class="n">messageInterpolator</span><span class="p">);</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @param messageResolver a new message resolver</span>
+<span class="cm"> * @return the instance of the current message context builder</span>
+<span class="cm"> */</span>
+ <span class="n">MessageContextBuilder</span> <span class="n">messageResolver</span><span class="p">(</span><span class="n">MessageResolver</span> <span class="n">messageResolver</span><span class="p">);</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @param localeResolver a new locale resolver</span>
+<span class="cm"> * @return the instance of the current message context builder</span>
+<span class="cm"> */</span>
+ <span class="n">MessageContextBuilder</span> <span class="n">localeResolver</span><span class="p">(</span><span class="n">LocaleResolver</span> <span class="n">localeResolver</span><span class="p">);</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * @return a new message context based on the current config</span>
+<span class="cm"> */</span>
+ <span class="n">MessageContext</span> <span class="n">create</span><span class="p">();</span>
+
+ <span class="c1">//the rest will be discussed later</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p># Security Module draft</p>
+<h1 id="agreed-api_2">Agreed API</h1>
+<ul>
+<li>@Secured</li>
+<li>@SecurityBindingType</li>
+<li>AccessDecisionVoter</li>
+<li>SecurityStrategy</li>
+</ul>
+<h1 id="agreed-api-and-spi-of-part-1">Agreed API and SPI of Part 1</h1>
+<p>commit: 1a2c7ffd0d0a1ad3dea34515a54958f0a6ce2932</p>
+<h2 id="api">API</h2>
+<h3 id="identity">Identity</h3>
+<p>Session scoped result of the authentication process.</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">interface</span> <span class="n">Identity</span> <span class="n">extends</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="n">public</span> <span class="n">enum</span> <span class="n">AuthenticationResult</span>
+ <span class="p">{</span>
+ <span class="n">SUCCESS</span><span class="p">,</span> <span class="n">FAILED</span>
+ <span class="p">}</span>
+
+ <span class="n">AuthenticationResult</span> <span class="n">login</span><span class="p">();</span>
+
+ <span class="n">void</span> <span class="n">logout</span><span class="p">();</span>
+
+ <span class="n">boolean</span> <span class="n">isLoggedIn</span><span class="p">();</span>
+
+ <span class="n">User</span> <span class="n">getUser</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h3 id="user">User</h3>
+<p>Depending on further use-cases it can be refactored to an interface</p>
+<p>The id is an unique identifier for an user. It isn't defined if it is an internal identifier or an identifier known by the user (like the user-name).
+If users login e.g. via their e-mail address, it's possible to lookup an internal id in a custom implementation of {{LoginCredential}} or a bean which is in between (and {{LoginCredential}} doesn't get called directly in the 2nd case).</p>
+<div class="codehilite"><pre><span class="p">@</span><span class="n">Typed</span><span class="p">()</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">User</span> <span class="n">implements</span> <span class="n">Serializable</span>
+<span class="p">{</span>
+ <span class="n">private</span> <span class="n">static</span> <span class="n">final</span> <span class="n">long</span> <span class="n">serialVersionUID</span> <span class="p">=</span> <span class="o">-</span>2234530384311026364<span class="n">L</span><span class="p">;</span>
+
+ <span class="n">private</span> <span class="n">final</span> <span class="n">String</span> <span class="n">id</span><span class="p">;</span>
+
+ <span class="n">public</span> <span class="n">User</span><span class="p">(</span><span class="n">String</span> <span class="n">id</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">this</span><span class="p">.</span><span class="n">id</span> <span class="p">=</span> <span class="n">id</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">String</span> <span class="n">getId</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="n">id</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h3 id="credential">Credential</h3>
+<p>Credential is a holder for the "secret key" like a password.</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">interface</span> <span class="n">Credential</span><span class="o"><</span><span class="n">T</span><span class="o">></span>
+<span class="p">{</span>
+ <span class="n">T</span> <span class="n">getValue</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h3 id="logincredential-former-credentials">LoginCredential (former Credentials)</h3>
+<p>Request scoped holder for the authentication process.</p>
+<p>[TODO] we need a better name for it</p>
+<ul>
+<li>LoginCredentialState</li>
+<li>LoginCredentialHolder</li>
+<li>
+<p>LoginCredentialProvider</p>
+<p>public interface LoginCredential
+{
+ String getUserId();</p>
+<div class="codehilite"><pre><span class="n">void</span> <span class="n">setUserId</span><span class="p">(</span><span class="n">String</span> <span class="n">userId</span><span class="p">);</span>
+
+<span class="n">Credential</span> <span class="n">getCredential</span><span class="p">();</span>
+
+<span class="n">void</span> <span class="n">setCredential</span><span class="p">(</span><span class="n">Credential</span> <span class="n">credential</span><span class="p">);</span>
+
+<span class="n">void</span> <span class="n">invalidate</span><span class="p">();</span>
+</pre></div>
+
+
+<p>}</p>
+</li>
+</ul>
+<h3 id="events">Events</h3>
+<ul>
+<li>LoggedInEvent</li>
+<li>LoginFailedEvent</li>
+<li>AlreadyLoggedInEvent</li>
+<li>PreLoggedOutEvent</li>
+<li>PostLoggedOutEvent</li>
+<li>PreAuthenticateEvent</li>
+<li>PostAuthenticateEvent</li>
+</ul>
+<h2 id="spi">SPI</h2>
+<h3 id="authenticatorselector">AuthenticatorSelector</h3>
+<p>Request scoped bean used to find the current {{Authenticator}} for the authentication process - e.g. to provide different login-types used by the same client (e.g. a component in an UI).</p>
+<p>[TODO] discuss default (internal) Authenticator if there is no custom implementation.</p>
+<div class="codehilite"><pre><span class="kr">public</span> <span class="kr">interface</span> <span class="nx">AuthenticatorSelector</span>
+<span class="p">{</span>
+ <span class="nx">Class</span><span class="cp"><?</span> <span class="k">extends</span> <span class="nx">Authenticator</span><span class="o">></span> <span class="nx">getAuthenticatorClass</span><span class="p">();</span>
+
+ <span class="nx">void</span> <span class="nx">setAuthenticatorClass</span><span class="p">(</span><span class="nx">Class</span><span class="o"><?</span> <span class="k">extends</span> <span class="nx">Authenticator</span><span class="o">></span> <span class="nx">authenticatorClass</span><span class="p">);</span>
+
+ <span class="nx">String</span> <span class="nx">getAuthenticatorName</span><span class="p">();</span>
+
+ <span class="nx">void</span> <span class="nx">setAuthenticatorName</span><span class="p">(</span><span class="nx">String</span> <span class="nx">authenticatorName</span><span class="p">);</span>
+
+ <span class="nx">Authenticator</span> <span class="nx">getSelectedAuthenticator</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h3 id="authenticator">Authenticator</h3>
+<p>Called by {{Identity}} and performs the final authentication based on the information in {{LoginCredential}} .</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">interface</span> <span class="n">Authenticator</span>
+<span class="p">{</span>
+ <span class="n">public</span> <span class="n">enum</span> <span class="n">AuthenticationStatus</span>
+ <span class="p">{</span>
+ <span class="n">SUCCESS</span><span class="p">,</span> <span class="n">FAILURE</span><span class="p">,</span> <span class="n">DEFERRED</span>
+ <span class="p">}</span>
+
+ <span class="n">void</span> <span class="n">authenticate</span><span class="p">();</span>
+
+ <span class="n">void</span> <span class="n">postAuthenticate</span><span class="p">();</span>
+
+ <span class="n">AuthenticationStatus</span> <span class="n">getStatus</span><span class="p">();</span>
+
+ <span class="n">User</span> <span class="n">getUser</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>b</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">abstract</span> <span class="n">class</span> <span class="n">BaseAuthenticator</span> <span class="n">implements</span> <span class="n">Authenticator</span>
+<span class="p">{</span>
+ <span class="n">private</span> <span class="n">AuthenticationStatus</span> <span class="n">status</span><span class="p">;</span>
+
+ <span class="n">public</span> <span class="n">AuthenticationStatus</span> <span class="n">getStatus</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="n">status</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">protected</span> <span class="n">void</span> <span class="n">setStatus</span><span class="p">(</span><span class="n">AuthenticationStatus</span> <span class="n">status</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">this</span><span class="p">.</span><span class="n">status</span> <span class="p">=</span> <span class="n">status</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">void</span> <span class="n">postAuthenticate</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="o">//</span> <span class="n">No</span><span class="o">-</span><span class="n">op</span><span class="p">,</span> <span class="n">override</span> <span class="k">if</span> <span class="n">any</span> <span class="n">post</span><span class="o">-</span><span class="n">authentication</span> <span class="n">processing</span> <span class="n">is</span> <span class="n">required</span><span class="p">.</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="usage">Usage</h2>
+<h3 id="simple-loginlogout-by-example-java-se">Simple Login/Logout by Example (Java-SE)</h3>
+<div class="codehilite"><pre><span class="p">@</span><span class="n">ApplicationScoped</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">LoginBean</span>
+<span class="p">{</span>
+ <span class="p">@</span><span class="n">Inject</span>
+ <span class="n">private</span> <span class="n">LoginCredential</span> <span class="n">loginCredential</span><span class="p">;</span>
+
+ <span class="p">@</span><span class="n">Inject</span>
+ <span class="n">private</span> <span class="n">Identity</span> <span class="n">identity</span><span class="p">;</span>
+
+ <span class="n">public</span> <span class="n">boolean</span> <span class="n">login</span><span class="p">(</span><span class="n">String</span> <span class="n">userName</span><span class="p">,</span> <span class="n">final</span> <span class="n">String</span> <span class="n">password</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">this</span><span class="p">.</span><span class="n">loginCredential</span><span class="p">.</span><span class="n">setUserId</span><span class="p">(</span><span class="n">userName</span><span class="p">);</span>
+ <span class="n">this</span><span class="p">.</span><span class="n">loginCredential</span><span class="p">.</span><span class="n">setCredential</span><span class="p">(</span><span class="n">new</span> <span class="n">Credential</span><span class="o"><</span><span class="n">String</span><span class="o">></span><span class="p">()</span> <span class="p">{</span>
+ <span class="p">@</span><span class="n">Override</span>
+ <span class="n">public</span> <span class="n">String</span> <span class="n">getValue</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="n">password</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">});</span>
+
+ <span class="n">this</span><span class="p">.</span><span class="n">identity</span><span class="p">.</span><span class="n">login</span><span class="p">();</span>
+ <span class="k">return</span> <span class="n">this</span><span class="p">.</span><span class="n">identity</span><span class="p">.</span><span class="n">isLoggedIn</span><span class="p">();</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">boolean</span> <span class="n">logout</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="n">this</span><span class="p">.</span><span class="n">identity</span><span class="p">.</span><span class="n">logout</span><span class="p">();</span>
+ <span class="k">return</span> !<span class="n">this</span><span class="p">.</span><span class="n">identity</span><span class="p">.</span><span class="n">isLoggedIn</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>b</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">CustomBean</span>
+<span class="p">{</span>
+ <span class="p">@</span><span class="n">Inject</span>
+ <span class="n">private</span> <span class="n">Identity</span> <span class="n">identity</span><span class="p">;</span>
+
+ <span class="p">@</span><span class="n">Inject</span>
+ <span class="n">private</span> <span class="n">LoginBean</span> <span class="n">loginBean</span><span class="p">;</span>
+
+ <span class="n">public</span> <span class="n">void</span> <span class="n">execute</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="k">if</span><span class="p">(</span><span class="n">this</span><span class="p">.</span><span class="n">loginBean</span><span class="p">.</span><span class="n">login</span><span class="p">(</span>"<span class="n">spike</span>"<span class="p">,</span> "<span class="n">apache</span>"<span class="p">))</span>
+ <span class="p">{</span>
+ <span class="n">User</span> <span class="n">user</span> <span class="p">=</span> <span class="n">this</span><span class="p">.</span><span class="n">identity</span><span class="p">.</span><span class="n">getUser</span><span class="p">();</span>
+ <span class="o">//</span><span class="p">...</span>
+ <span class="p">}</span>
+ <span class="k">else</span>
+ <span class="p">{</span>
+ <span class="o">//</span><span class="p">...</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h1 id="under-discussion_1">Under discussion</h1>
+<h2 id="apispi_1">API/SPI</h2>
+<h3 id="packages">Packages</h3>
+<ul>
+<li>*/authentication</li>
+<li>*/authentication/events</li>
+<li>*/authorization</li>
+<li>*/authorization/annotation</li>
+<li>*/credential or */authentication/credential</li>
+</ul>
+<h2 id="part-1_1">Part 1</h2>
+<p>|| Feature || Comments || Objections || Discussion finished ||
+| Login via Username/Password | | | (+) |
+| Logout | | | (+) |
+| Authentication API and SPI | Credentials vs Credential (one of it needs a better name) | | (+) |
+| Basic User/Identity API | | | (+) |
+| Duration of a valid authentication | ExpirationEvaluator SPI | | |</p>
+<h2 id="part-2_1">Part 2</h2>
+<p>|| Feature || Comments || Objections || Discussion finished ||
+| Object level permission | | | |
+| Grant or revoke permissions | | | |
+| Basic Roles and groups API | optional type-safe (-> static) groups (and roles) | | |
+| @SecurityMethodBinding | | | |
+| Super-users | | | |
+| User/Identity management | | | |
+| Password-Hash-Service | | | |
+| Group management | optional support for typ-safe groups/group-types | | |</p>
+<h2 id="part-3_1">Part 3</h2>
+<p>|| Feature || Comments || Objections || Discussion finished ||
+| Support for deputies (see Impersonalization) | | | |
+| Privileges concept | | | |
+| UI SPI (Component based authorization) | add optional type-safe authorization; integration with JSF | | |
+| Permissions of resources | Merge with CODI view-configs,... | | |
+| Persistence SPI | integration with JPA | | |
+| Identity Store SPI | | | |
+| Query API | | | |
+| Application roles | | | |</p>
+<h2 id="part-4_1">Part 4</h2>
+<p>|| Feature || Comments || Objections || Discussion finished ||
+| Support of alternative authentication concepts | Extend the Authentication SPI | | |
+| Integration with authentication concepts of (application-) servers | Extend the Authentication SPI | | |
+| Personalization | | | |
+| Alternatives for roles/groups | | | |
+| Permission for external applications | | | |</p>
+<h1 id="use-cases_1">Use-cases</h1>
+<h2 id="authentication">Authentication</h2>
+<h3 id="scenario_1">Scenario</h3>
+<p>The user must be able to log in by supplying a username and password</p>
+<p>Example JSF code:</p>
+<div class="codehilite"><pre><span class="n">Username</span><span class="p">:</span> <span class="o"><</span><span class="n">h</span><span class="p">:</span><span class="n">inputText</span> <span class="n">value</span><span class="p">=</span>"#<span class="p">{</span><span class="n">credentials</span><span class="p">.</span><span class="n">username</span><span class="p">}</span>"<span class="o">/></span>
+<span class="n">Password</span><span class="p">:</span> <span class="o"><</span><span class="n">h</span><span class="p">:</span><span class="n">inputSecret</span> <span class="n">id</span><span class="p">=</span>"<span class="n">password</span>" <span class="n">value</span><span class="p">=</span>"#<span class="p">{</span><span class="n">credentials</span><span class="p">.</span><span class="n">password</span><span class="p">}</span>"<span class="o">/></span>
+<span class="o"><</span><span class="n">h</span><span class="p">:</span><span class="n">commandButton</span> <span class="n">value</span><span class="p">=</span>"<span class="n">LOGIN</span>" <span class="n">action</span><span class="p">=</span>"#<span class="p">{</span><span class="n">identity</span><span class="p">.</span><span class="n">login</span><span class="p">}</span>"<span class="o">/></span>
+</pre></div>
+
+
+<h3 id="scenario_2">Scenario</h3>
+<p>The user must be able to log out</p>
+<p>Example JSF codee</p>
+<div class="codehilite"><pre><span class="o"><</span><span class="n">h</span><span class="p">:</span><span class="n">commandButton</span> <span class="n">value</span><span class="p">=</span>"<span class="n">LOGOUT</span>" <span class="n">action</span><span class="p">=</span>"#<span class="p">{</span><span class="n">identity</span><span class="p">.</span><span class="n">logout</span><span class="p">}</span>"<span class="o">/></span>
+</pre></div>
+
+
+<h3 id="scenario_3">Scenario</h3>
+<p>The developer must be able to easily implement their own custom authentication logic using a provided SPI</p>
+<p>Example</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">SimpleAuthenticator</span> <span class="n">extends</span> <span class="n">BaseAuthenticator</span> <span class="n">implements</span> <span class="n">Authenticator</span> <span class="p">{</span>
+ <span class="p">@</span><span class="n">Inject</span> <span class="n">Credentials</span> <span class="n">credentials</span><span class="p">;</span>
+
+ <span class="p">@</span><span class="n">Override</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">authenticate</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span>"<span class="n">demo</span>"<span class="p">.</span><span class="n">equals</span><span class="p">(</span><span class="n">credentials</span><span class="p">.</span><span class="n">getUsername</span><span class="p">())</span> <span class="o">&&</span>
+ <span class="n">credentials</span><span class="p">.</span><span class="n">getCredential</span><span class="p">()</span> <span class="n">instanceof</span> <span class="n">PasswordCredential</span> <span class="o">&&</span>
+ "<span class="n">demo</span>"<span class="p">.</span><span class="n">equals</span><span class="p">(((</span><span class="n">PasswordCredential</span><span class="p">)</span> <span class="n">credentials</span><span class="p">.</span><span class="n">getCredential</span><span class="p">()).</span><span class="n">getValue</span><span class="p">()))</span> <span class="p">{</span>
+ <span class="n">setStatus</span><span class="p">(</span><span class="n">AuthenticationStatus</span><span class="p">.</span><span class="n">SUCCESS</span><span class="p">);</span>
+ <span class="n">setUser</span><span class="p">(</span><span class="n">new</span> <span class="n">SimpleUser</span><span class="p">(</span>"<span class="n">demo</span>"<span class="p">));</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="n">setStatus</span><span class="p">(</span><span class="n">AuthenticationStatus</span><span class="p">.</span><span class="n">FAILURE</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>{code}</p>
+<h3 id="scenario_4">Scenario</h3>
+<p>It should be possible to provide an optional password service to create a password-hash based on the given password which will be stored instead of the real password.
+Maybe there should be different default implementations (provided via qualifiers).</p>
+<h3 id="scenario_5">Scenario</h3>
+<p>The developer needs to authenticate application users stored inside corporate LDAP server.</p>
+<h3 id="scenario_6">Scenario</h3>
+<p>The developer must be able to easily support alternative authentication providers, such as those supporting services such as OpenID or token based authentication. Those can be more complex then just âusername/passwordâ scenario and require redirects to or communication with specific external ISP (Identity Service Provider)</p>
+<p>Examples:</p>
+<ul>
+<li>Web SSO, Desktop SSO (SPNEGO), SAML...</li>
+<li>Open ID</li>
+<li>OAuth</li>
+<li>REST</li>
+<li>Token based</li>
+<li>Service authenticating to application</li>
+</ul>
+<p>Requirements:</p>
+<p>Well thought API and SPI that doesnât limit integration with those.
+For some of those technologies where authentication is token based identity model needs to be capable of persisting needed information - token and reference to specific identity provider.
+Ability to implement own authenticator that have access to IDM and Securtiy/Permissions API in it.
+Provide automatic mapping between attributes returned by the Identity provider, and attributes stored in the local Identity store.
+Allow authentication from alternative view technologies, (i.e. AJAX)</p>
+<h3 id="scenario_7">Scenario</h3>
+<p>The user must be able to authenticate automatically using a âRemember Meâ feature, based on a unique cookie value stored by the userâs browser. For authentication performed in this manner, it must be also possible for the developer to configure a validation policy, which determines whether the user is required to provide their actual credentials for critical application operations such as changing passwords or e-mail address, placing orders, etc.</p>
+<p>The validation policy should also determine how long the validation window lasts, with some possible options being:</p>
+<ul>
+<li>Validated for this request only</li>
+<li>Validated for X minutes</li>
+<li>Validated until end of session</li>
+</ul>
+<h3 id="scenario_8">Scenario</h3>
+<p>The developer must be able to easily integrate with AS security layer (JAAS/JAAC). Ideally by plugging DeltaSpike security into LoginModule stack.</p>
+<h2 id="impersonalization">Impersonalization</h2>
+<h3 id="scenario_9">Scenario</h3>
+<p>Administrator needs to verify assigned access, applied changes or exposed resources for specific user. He authenticates âas a userâ or access application imitating his identity - without knowing his password.</p>
+<p>Examples:</p>
+<ul>
+<li>Facebook, see your profile as user 'bob'</li>
+<li>Mary is away from the office and someone needs to execute something on her behalf</li>
+</ul>
+<h2 id="authorization">Authorization</h2>
+<h3 id="scenario_10">Scenario</h3>
+<p>The developer must be able to control which elements of the user interface are displayed to the user based on the user's privilege level</p>
+<p>Example JSF code:</p>
+<div class="codehilite"><pre><span class="nt"><div</span> <span class="na">class=</span><span class="s">"menu"</span><span class="nt">></span>
+ <span class="nt"><h:commandLink</span> <span class="na">value=</span><span class="s">"Admin functions"</span> <span class="na">rendered=</span><span class="s">"#{identity.hasRole('admin', 'APPLICATION')}"</span> <span class="na">action=</span><span class="s">"..."</span><span class="nt">/></span>
+<span class="nt"></div></span>
+</pre></div>
+
+
+<h3 id="scenario_11">Scenario</h3>
+<p>The developer must be able to control which elements of the user interface are displayed to the user based on their assigned permissions</p>
+<p>Example JSF code:</p>
+<div class="codehilite"><pre><span class="nt"><table</span> <span class="na">class=</span><span class="s">"customers"</span><span class="nt">></span>
+ <span class="nt"><ui:repeat</span> <span class="na">value=</span><span class="s">"#{customerSearch.customers}"</span> <span class="na">var=</span><span class="s">"#{customer}"</span><span class="nt">></span>
+ <span class="nt"><tr></span>
+ <span class="nt"><td></span>#{customer.firstName}<span class="nt"></td></span>
+ <span class="nt"><td></span>#{customer.lastName}<span class="nt"></td></span>
+ <span class="nt"><td><h:commandButton</span> <span class="na">value=</span><span class="s">"Edit"</span> <span class="na">rendered=</span><span class="s">"#{identity.hasPermission(customer, 'EDIT')}"</span> <span class="na">action=</span><span class="s">"..."</span><span class="nt">/></span>
+ <span class="nt"></tr></span>
+ <span class="nt"></ui:repeat></span>
+<span class="nt"></table></span>
+</pre></div>
+
+
+<h3 id="scenario_12">Scenario</h3>
+<p>Sometimes developer may not have available instance of resource, which he wants to protect. It may be useful to ask for permission without need to obtain object from DB. It might be useful to have method: identity.hasPermission(String resourceType, String resourceId, String permission) in addition to current identity.hasPermission(Object resource, String permission)</p>
+<p>Example JSF code:</p>
+<div class="codehilite"><pre> <span class="o"><</span><span class="n">h</span><span class="p">:</span><span class="n">commandButton</span> <span class="n">value</span><span class="p">=</span>"<span class="n">Edit</span> <span class="n">page</span>" <span class="n">rendered</span><span class="p">=</span>"#<span class="p">{</span><span class="n">identity</span><span class="p">.</span><span class="n">hasPermission</span><span class="p">(</span><span class="s">'PAGE'</span><span class="p">,</span> <span class="s">'AcmePage'</span><span class="p">,</span> <span class="s">'EDIT'</span><span class="p">)}</span>" <span class="n">action</span><span class="p">=</span>"<span class="p">...</span>"<span class="o">/></span>
+</pre></div>
+
+
+<h3 id="scenario_13">Scenario</h3>
+<p>The developer must be able to restrict method access based on the user's privilege level.
+Example:</p>
+<p>(Already addressed with typesafe security annotations, e.g. @SecurityBindingType)</p>
+<h3 id="scenario_14">Scenario</h3>
+<p>The framework must provide a system for resolving object permissions, and the developer must have access to an SPI for easily providing their own custom permission resolver logic.</p>
+<h3 id="scenario_15">Scenario</h3>
+<p>The user (with the necessary privileges) must be able assign permissions to individual objects within the applicationâs business domain (i.e. ACL style permissions) and have these permissions persisted. These permissions should:</p>
+<ul>
+<li>Be assignable to either the individual user, a group, or a role</li>
+<li>Be stored using an identifier that is unique for the object that the permission is being granted for</li>
+<li>Have configurable identifier policies, i.e. Entity beans will use an identifier based on the primary key value</li>
+<li>Have a configurable permission store, i.e. it must be possible to store permissions in a database using JPA, etc.</li>
+</ul>
+<h3 id="scenario_16">Scenario</h3>
+<p>Further to the previous requirement, there must be an API for managing persistent permissions. Operations performed by the user on this API (such as granting or revoking permissions to/from other users) may be subjected to an additional security check.</p>
+<h3 id="scenario_17">Scenario</h3>
+<p>The developer needs to perform authorization checks based on information stored in corporate LDAP server or dedicated database. This external store contains information about all company employees and maps hierarchy including groups present in the organization with information about their members.</p>
+<p>Company has a Windows domain and whole security model build around structure of group of users stored in Microsoft Active Directory. Application developer needs to integrate security with this information.
+Examples:</p>
+<ul>
+<li>Restrict access to employees: identityManager.getUser(userName).hasRole(âmemberâ, â/organization/employeesâ);</li>
+<li>Restrict access to publishing content only to marketing</li>
+<li>identityManager.hasRole(âmemberâ,âjohnâ,â/organization/departments/marketingâ);</li>
+<li>Restrict adding new members to a group only for its administrator</li>
+<li>identityManager.hasRole(âadministratorâ, âjohnâ, â/some/specific/groupâ);</li>
+</ul>
+<h3 id="scenario_18">Scenario</h3>
+<p>The developer needs to control access to application resources based on structure of groups and user roles</p>
+<h3 id="scenario_19">Scenario</h3>
+<p>Web application has a number of resources that needs to be secured with more fine grained security model. Invoking operations on a given resource needs to be restricted with a given permission. User can inherit set of permissions to the given resource from group to which he belongs or from role he posses.</p>
+<p>Examples:</p>
+<ul>
+<li>Application has a structure of pages and needs to restrict access to specific ones</li>
+<li>Application wants to only allow specific operations on given resource</li>
+<li>User can add new customers only if it has CREATE permission on Customer resource.</li>
+<li>User can review and approve new content pending to be published if he has VALIDATE permission assigned for Announcements resource. User inherits this permission because it is member of group â/organization/senior_managersâ
+*User belongs to group â/operators/content_creatorâ. Therefore he inherits a set of permissions (CREATE, EDIT, REMOVE) to add new content on specified page in the application.</li>
+</ul>
+<p>Requirements:</p>
+<h2 id="permissions-model">Permissions model</h2>
+<h3 id="scenario_20">Scenario</h3>
+<p>Application has a structure of resources. Permissions assigned to user for a given resource in the tree are inherited by other resources. User is able to edit all sub resources based on permissions assigned to parent resource.</p>
+<p>Example:</p>
+<ul>
+<li>Application has structure of pages.</li>
+<li>User assigned to manage specific page should also be able to manage all sub pages.</li>
+<li>Permissions are inherited.</li>
+</ul>
+<h3 id="scenario_21">Scenario</h3>
+<p>Application persists a structure of groups and users that have roles in those groups. Application developer needs to have some permissions related to one group be inherited by their sub groups.</p>
+<p>Example:</p>
+<ul>
+<li>Group â/organizationâ has assigned READ permission associated with âCorporate newsâ page</li>
+<li>Group â/organization/it_deptâ has assigned READ and CREATE permission associated with âIT Security Event Logsâ page in the application.</li>
+<li>All users with role in â/organizaiton/it_deptâ will be able to read âCorporate newsâ page because READ permission will be inherited from â/organizationâ group.</li>
+</ul>
+<h3 id="scenario_22">Scenario</h3>
+<p>The developer needs to define several types of contexts in which user is connected with a given group to enable flexible authorization of different types of performed operations</p>
+<p>Example:</p>
+<p>John is an âadministratorâ of â/communities/base_jumpingâ group and can perform administrative tasks on resources connected with this group
+John is a âmemberâ of â/communities/base_jumpingâ group and he can access and read resources connected with this group
+John is a âcontent validatorâ of â/communities/base_jumpingâ group and he will be asked to authorize any new content on pages related to this group before it gets published.</p>
+<p>In all examples described above single group can have several users with same role.</p>
+<h4 id="this-specifically-can-be-addressed-with-the-domain-acl-type-approach-as-prototyped-in-seam-security">This specifically can be addressed with the Domain ACL type approach, as prototyped in Seam Security:</h4>
+<p>One of the biggest problems of Java web app security to date, and what will also be a problem in our framework, is that Java EE, Seam Security have not been able to satisfy a very common type of Authentication, domain authentication, and have focused solely on global role-based security authorisation:</p>
+<p>E.g: Global authentication is "Is the user an Admin of the application," as opposed to domain authentication, which asks, "Is the user an Admin of this Domain Object,"</p>
+<p>Developers typically have to implement their own security system (via direct method calls, or etc...) for this type of business logic.</p>
+<p>REST endpoint or RPC: (Lincoln's prototyped API - functional in Seam Security)</p>
+<div class="codehilite"><pre><span class="err">@</span><span class="n">SecurityBinding</span>
+<span class="n">public</span> <span class="err">@</span><span class="n">interface</span> <span class="n">ProjectAdmin</span>
+<span class="p">{</span>
+ <span class="c1">// empty</span>
+<span class="p">}</span>
+
+<span class="err">@</span><span class="n">SecurityMethodBinding</span>
+<span class="n">public</span> <span class="err">@</span><span class="n">interface</span> <span class="n">ProjectBinding</span>
+<span class="p">{</span>
+ <span class="c1">// empty</span>
+<span class="p">}</span>
+
+<span class="err">@</span><span class="n">ProjectAdmin</span>
+<span class="n">public</span> <span class="kt">void</span> <span class="n">updateName</span><span class="p">(</span><span class="err">@</span><span class="n">ProjectBinding</span> <span class="n">Project</span> <span class="n">p</span><span class="p">,</span> <span class="n">String</span> <span class="n">name</span><span class="p">)</span>
+<span class="p">{</span>
+ <span class="c1">// save project name</span>
+<span class="p">}</span>
+
+<span class="err">@</span><span class="n">Secures</span>
+<span class="err">@</span><span class="n">ProjectAdmin</span>
+<span class="n">public</span> <span class="n">boolean</span> <span class="n">isProjectAdmin</span><span class="p">(</span><span class="err">@</span><span class="n">ProjectBinding</span> <span class="n">Project</span> <span class="n">p</span><span class="p">,</span> <span class="n">Identity</span> <span class="n">identity</span><span class="p">)</span>
+<span class="p">{</span>
+ <span class="k">if</span><span class="p">(</span><span class="n">identity</span><span class="p">.</span><span class="n">hasRole</span><span class="p">(</span><span class="s">"project"</span> <span class="o">+</span> <span class="n">p</span><span class="p">.</span><span class="n">getId</span><span class="p">()</span> <span class="o">+</span> <span class="s">"_admin"</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Note that the @Project annotation is not a CDI bean Qualifier / Stereotype annotation, it is a method parameter security binding annotation that tells Seam Security to use the value of the Project passed to the method call in the security binding check itself.</p>
+<h3 id="scenario_23">Scenario</h3>
+<p>The developer needs to define single user or group that will serve as super users (aka root users. Those will have any available permissions.</p>
+<p>Example:</p>
+<ul>
+<li>identity.isRootUser()</li>
+<li>identityManager.getRootUsers();</li>
+</ul>
+<h3 id="scenario_24">Scenario</h3>
+<p>Application needs to authorize access based on inherited group membership.</p>
+<p>Example:</p>
+<p>Access to information about new trips is restricted to members of â/communities/hikingâ group
+Users being members of â/communities/hiking/instructorsâ, â/communities/hiking/juniorsâ and /communities/hiking/seniorsâ will inherit membership in group â/communities/hikingâ and gain access to information about new trips.
+On the other hand, access to information about climbing trips should not be available to juniors. So in this case, we want to have it available only for â/communities/hikingâ but not for â/communities/hiking/juniorsâ. So it might be useful if group inheritance is configurable for individual resources.</p>
+<p>Example: You can configure that info about classic trips is available for â/communities/hiking*â which would mean /communities/hiking and all itâs subgroups. On the other hand info about climbing trips is available only for individual groups â/communities/hikingâ and â/communities/hiking/seniorsâ as we donât want to have group inheritance here.
+For this climbing usecase, it may be useful to DENY permission available from parent groups.</p>
+<p>Example: You can configure that info about climbing trips will be available for â/communities/hiking*â but permission is denied for members for â/communites/hiking/juniorsâ. In this case, groups â/commuinites/hikingâ, â/communities/hiking/instructorsâ, â/communities/hiking/seniorsâ will have permission. Members of group â/communities/hiking/juniorsâ wonât hav permission.</p>
+<h3 id="scenario_25">Scenario</h3>
+<p>The developer may want to have permissions based on other criterias than only roles/groups. Some of these requirements can be handled by XACML integration mentioned below.</p>
+<ul>
+<li>I want page "hobby" to be accessible for employees only after 6pm, to enforce that my employees won't go to hobby page during their working time.</li>
+<li>I want forum portlet with "Retiree forum" to be accessible only for users older than 60 years. Only exceptions can be "/platform/administrators" group, whose members can access page everytime regardless of their age.</li>
+</ul>
+<h3 id="scenario_26">Scenario</h3>
+<p>The developer needs to integrate application with more advanced security resolution mechanisms.</p>
+<p>Examples:</p>
+<ul>
+<li>Rules based engine to resolve permissions</li>
+<li>Integration with external services - XACML architecture with separate Policy Enforcement Point, Policy Decision Point and Policy Store.</li>
+<li>Simplified model where permissions are hardcoded and resolved based on information about group membership.</li>
+</ul>
+<p>Requirements:</p>
+<p>Well thought API/SPI that doesnât limit such integration.</p>
+<h3 id="scenario_27">Scenario</h3>
+<p>The developer needs to expose part of application features to be accessible by external services and authorize their access.</p>
+<h2 id="delegated-administration">Delegated Administration</h2>
+<h3 id="scenario_28">Scenario</h3>
+<p>Web application has a number of user groups or resources that needs to be managed. It is desired that management permission to only part of those are delegated to specific user</p>
+<p>Examples:</p>
+<ul>
+<li>User gets administration privileges for specific group of users</li>
+<li>User gets administration privileges for specific set of application resources (group of pages</li>
+<li>User gets administration privileges to all sub groups of specific group - can include all users belonging there</li>
+<li>User gets administration privileges to sub resources - all sub pages in navigation hierarchy</li>
+</ul>
+<p>Requirements:</p>
+<p>Advanced enough security and identity model to map required permissions</p>
+<h2 id="identity-management-idm">Identity Management (IDM)</h2>
+<p>All use cases with strong focus around concepts and operations on User, Group and Role</p>
+<h3 id="scenario_29">Scenario</h3>
+<p>Application needs to expose basic user management capabilities. To register new user, edit profile and remove old users. Basic provisioning and management API for user, group and role.</p>
+<p>Examples:</p>
[... 139 lines stripped ...]