shiro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lhazlew...@apache.org
Subject svn commit: r1481417 [11/13] - in /shiro/site: ./ 2010/ 2011/ 2012/ assets/ templates/ trunk/ trunk/2010/ trunk/2010/03/ trunk/2010/03/18/ trunk/2010/06/ trunk/2010/06/01/ trunk/2010/09/ trunk/2010/09/14/ trunk/2010/09/20/ trunk/2010/09/24/ trunk/2010/...
Date Sat, 11 May 2013 21:10:45 GMT
Added: shiro/site/trunk/spring.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/spring.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/spring.html (added)
+++ shiro/site/trunk/spring.html Sat May 11 21:10:40 2013
@@ -0,0 +1,208 @@
+<h1><a name="Spring-IntegratingApacheShirointoSpringbasedApplications"></a>Integrating Apache Shiro into Spring based Applications</h1>
+
+<p>This page covers the ways to integrate Shiro into <a class="external-link" href="http://www.springframework.org" rel="nofollow">Spring</a>-based applications.</p>
+
+<p>Shiro's JavaBeans compatibility makes it perfectly suited to be configured via Spring XML or other Spring-based configuration mechanisms.  Shiro applications need an application singleton <tt>SecurityManager</tt> instance.  Note that this does not have to be a <em>static</em> singleton, but there should only be a single instance used by the application, whether its a static singleton or not.</p>
+
+<h2><a name="Spring-StandaloneApplications"></a>Standalone Applications</h2>
+
+<p>Here is the simplest way to enable an application singleton <tt>SecurityManager</tt> in Spring applications:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag"><span class="code-comment">&lt;!-- Define the realm you want to use to connect to your back-end security datasource: --&gt;</span></span>
+<span class="code-tag">&lt;bean id=<span class="code-quote">"myRealm"</span> class=<span class="code-quote">"..."</span>&gt;</span>
+...
+<span class="code-tag">&lt;/bean&gt;</span>
+
+<span class="code-tag">&lt;bean id=<span class="code-quote">"securityManager"</span> class=<span class="code-quote">"org.apache.shiro.mgt.DefaultSecurityManager"</span>&gt;</span>
+    <span class="code-tag"><span class="code-comment">&lt;!-- Single realm app.  If you have multiple realms, use the 'realms' property instead. --&gt;</span></span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"realm"</span> ref=<span class="code-quote">"myRealm"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+<span class="code-tag">&lt;bean id=<span class="code-quote">"lifecycleBeanPostProcessor"</span> class=<span class="code-quote">"org.apache.shiro.spring.LifecycleBeanPostProcessor"</span>/&gt;</span>
+
+<span class="code-tag"><span class="code-comment">&lt;!-- For simplest integration, so that all SecurityUtils.* methods work in all cases, --&gt;</span></span>
+<span class="code-tag"><span class="code-comment">&lt;!-- make the securityManager bean a static singleton.  DO NOT do this in web         --&gt;</span></span>
+<span class="code-tag"><span class="code-comment">&lt;!-- applications - see the 'Web Applications' section below instead.                 --&gt;</span></span>
+<span class="code-tag">&lt;bean class=<span class="code-quote">"org.springframework.beans.factory.config.MethodInvokingFactoryBean"</span>&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"staticMethod"</span> value=<span class="code-quote">"org.apache.shiro.SecurityUtils.setSecurityManager"</span>/&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"arguments"</span> ref=<span class="code-quote">"securityManager"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+</pre>
+</div></div>
+
+
+<h2><a name="Spring-WebApplications"></a>Web Applications</h2>
+
+<p>Shiro has first-rate support for Spring web applications.  In a web application, all Shiro-accessible web requests must go through a master Shiro Filter.  This filter itself is extremely powerful, allowing for <br clear="none">
+ad-hoc custom filter chains to be executed based on any URL path expression.</p>
+
+<p>Prior to Shiro 1.0, you had to use a hybrid approach in Spring web applications, defining the Shiro filter and<br clear="none">
+all of its configuration properties in web.xml but define the <tt>SecurityManager</tt> in Spring XML.  This was a little frustrating since you couldn't 1) consolidate your configuration in one place and 2) leverage the configuration power of the more advanced Spring features, like the <tt>PropertyPlaceholderConfigurer</tt> or abstract beans to consolidate common configuration.</p>
+
+<p>Now in Shiro 1.0 and later, all Shiro configuration is done in Spring XML providing access to the more robust Spring configuration mechanisms.</p>
+
+<p>Here is how to configure Shiro in a Spring-based web application:</p>
+
+<h3><a name="Spring-web.xml"></a>web.xml</h3>
+
+<p>In addition to your other Spring web.xml elements (<tt>ContextLoaderListener</tt>, <tt>Log4jConfigListener</tt>, etc), define the following filter and filter mapping:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag"><span class="code-comment">&lt;!-- The filter-name matches name of a 'shiroFilter' bean inside applicationContext.xml --&gt;</span></span>
+<span class="code-tag">&lt;filter&gt;</span>
+    <span class="code-tag">&lt;filter-name&gt;</span>shiroFilter<span class="code-tag">&lt;/filter-name&gt;</span>
+    <span class="code-tag">&lt;filter-class&gt;</span>org.springframework.web.filter.DelegatingFilterProxy<span class="code-tag">&lt;/filter-class&gt;</span>
+    <span class="code-tag">&lt;init-param&gt;</span>
+        <span class="code-tag">&lt;param-name&gt;</span>targetFilterLifecycle<span class="code-tag">&lt;/param-name&gt;</span>
+        <span class="code-tag">&lt;param-value&gt;</span>true<span class="code-tag">&lt;/param-value&gt;</span>
+    <span class="code-tag">&lt;/init-param&gt;</span>
+<span class="code-tag">&lt;/filter&gt;</span>
+
+...
+
+<span class="code-tag"><span class="code-comment">&lt;!-- Make sure any request you want accessible to Shiro is filtered. /* catches all --&gt;</span></span>
+<span class="code-tag"><span class="code-comment">&lt;!-- requests.  Usually this filter mapping is defined first (before all others) to --&gt;</span></span>
+<span class="code-tag"><span class="code-comment">&lt;!-- ensure that Shiro works in subsequent filters in the filter chain:             --&gt;</span></span>
+<span class="code-tag">&lt;filter-mapping&gt;</span>
+    <span class="code-tag">&lt;filter-name&gt;</span>shiroFilter<span class="code-tag">&lt;/filter-name&gt;</span>
+    <span class="code-tag">&lt;url-pattern&gt;</span>/*<span class="code-tag">&lt;/url-pattern&gt;</span>
+<span class="code-tag">&lt;/filter-mapping&gt;</span>
+</pre>
+</div></div>
+
+<h3><a name="Spring-applicationContext.xml"></a>applicationContext.xml</h3>
+
+<p>In your applicationContext.xml file, define the web-enabled <tt>SecurityManager</tt> and the 'shiroFilter' bean that will be referenced from <tt>web.xml</tt>.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag">&lt;bean id=<span class="code-quote">"shiroFilter"</span> class=<span class="code-quote">"org.apache.shiro.spring.web.ShiroFilterFactoryBean"</span>&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"securityManager"</span> ref=<span class="code-quote">"securityManager"</span>/&gt;</span>
+    &lt;!-- override these for application-specific URLs if you like:
+    <span class="code-tag">&lt;property name=<span class="code-quote">"loginUrl"</span> value=<span class="code-quote">"/login.jsp"</span>/&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"successUrl"</span> value=<span class="code-quote">"/home.jsp"</span>/&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"unauthorizedUrl"</span> value=<span class="code-quote">"/unauthorized.jsp"</span>/&gt;</span> --&gt;
+    <span class="code-tag"><span class="code-comment">&lt;!-- The 'filters' property is not necessary since any declared javax.servlet.Filter bean  --&gt;</span></span>
+    <span class="code-tag"><span class="code-comment">&lt;!-- defined will be automatically acquired and available via its beanName in chain        --&gt;</span></span>
+    <span class="code-tag"><span class="code-comment">&lt;!-- definitions, but you can perform instance overrides or name aliases here if you like: --&gt;</span></span>
+    <span class="code-tag">&lt;!-- &lt;property name=<span class="code-quote">"filters"</span>&gt;</span>
+        <span class="code-tag">&lt;util:map&gt;</span>
+            <span class="code-tag">&lt;entry key=<span class="code-quote">"anAlias"</span> value-ref=<span class="code-quote">"someFilter"</span>/&gt;</span>
+        <span class="code-tag">&lt;/util:map&gt;</span>
+    <span class="code-tag">&lt;/property&gt;</span> --&gt;
+    <span class="code-tag">&lt;property name=<span class="code-quote">"filterChainDefinitions"</span>&gt;</span>
+        <span class="code-tag">&lt;value&gt;</span>
+            # some example chain definitions:
+            /admin/** = authc, roles[admin]
+            /docs/** = authc, perms[document:read]
+            /** = authc
+            # more URL-to-FilterChain definitions here
+        <span class="code-tag">&lt;/value&gt;</span>
+    <span class="code-tag">&lt;/property&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+
+<span class="code-tag"><span class="code-comment">&lt;!-- Define any javax.servlet.Filter beans you want anywhere in this application context.   --&gt;</span></span>
+<span class="code-tag"><span class="code-comment">&lt;!-- They will automatically be acquired by the 'shiroFilter' bean above and made available --&gt;</span></span>
+<span class="code-tag"><span class="code-comment">&lt;!-- to the 'filterChainDefinitions' property.  Or you can manually/explicitly add them     --&gt;</span></span>
+<span class="code-tag"><span class="code-comment">&lt;!-- to the shiroFilter's 'filters' Map if desired. See its JavaDoc for more details.       --&gt;</span></span>
+<span class="code-tag">&lt;bean id=<span class="code-quote">"someFilter"</span> class=<span class="code-quote">"..."</span>/&gt;</span>
+<span class="code-tag">&lt;bean id=<span class="code-quote">"anotherFilter"</span> class=<span class="code-quote">"..."</span>&gt;</span> ... <span class="code-tag">&lt;/bean&gt;</span>
+...
+
+<span class="code-tag">&lt;bean id=<span class="code-quote">"securityManager"</span> class=<span class="code-quote">"org.apache.shiro.web.mgt.DefaultWebSecurityManager"</span>&gt;</span>
+    <span class="code-tag"><span class="code-comment">&lt;!-- Single realm app.  If you have multiple realms, use the 'realms' property instead. --&gt;</span></span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"realm"</span> ref=<span class="code-quote">"myRealm"</span>/&gt;</span>
+    &lt;!-- By default the servlet container sessions will be used.  Uncomment this line
+         to use shiro's native sessions (see the JavaDoc for more): --&gt;
+    <span class="code-tag"><span class="code-comment">&lt;!-- &lt;property name=<span class="code-quote">"sessionMode"</span> value=<span class="code-quote">"native"</span>/&gt;</span> --&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+<span class="code-tag">&lt;bean id=<span class="code-quote">"lifecycleBeanPostProcessor"</span> class=<span class="code-quote">"org.apache.shiro.spring.LifecycleBeanPostProcessor"</span>/&gt;</span>
+
+<span class="code-tag"><span class="code-comment">&lt;!-- Define the Shiro Realm implementation you want to use to connect to your back-end --&gt;</span></span>
+<span class="code-tag"><span class="code-comment">&lt;!-- security datasource: --&gt;</span></span>
+<span class="code-tag">&lt;bean id=<span class="code-quote">"myRealm"</span> class=<span class="code-quote">"..."</span>&gt;</span>
+...
+<span class="code-tag">&lt;/bean&gt;</span>
+</pre>
+</div></div>
+
+<h2><a name="Spring-EnablingShiroAnnotations"></a>Enabling Shiro Annotations</h2>
+
+<p>In both standalone and web applications, you might want to use Shiro's Annotations for security checks (for example, <tt>@RequiresRoles</tt>, <tt>@RequiresPermissions</tt>, etc.  This requires Shiro's Spring AOP integration to scan for the appropriate annotated classes and perform security logic as necessary. </p>
+
+<p>Here is how to enable these annotations.  Just add these two bean definitions to <tt>applicationContext.xml</tt>:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag"><span class="code-comment">&lt;!-- Enable Shiro Annotations for Spring-configured beans.  Only run after --&gt;</span></span>
+<span class="code-tag"><span class="code-comment">&lt;!-- the lifecycleBeanProcessor has run: --&gt;</span></span>
+<span class="code-tag">&lt;bean class=<span class="code-quote">"org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator"</span> depends-on=<span class="code-quote">"lifecycleBeanPostProcessor"</span>/&gt;</span>
+<span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.shiro.spring.security.interceptor.AuthorizationAttributeSourceAdvisor"</span>&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"securityManager"</span> ref=<span class="code-quote">"securityManager"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+</pre>
+</div></div>
+
+<h2><a name="Spring-SecureSpringRemoting"></a>Secure Spring Remoting</h2>
+
+<p>There are two parts to Shiro's Spring remoting support: Configuration for the client making the remoting call and configuration for the server receiving and processing the remoting call.</p>
+
+<h3><a name="Spring-ServersideConfiguration"></a>Server-side Configuration</h3>
+
+<p>When a remote method invocation comes in to a Shiro-enabled server, the <a href="subject.html" title="Subject">Subject</a> associated with that RPC call must be bound to the receiving thread for access during the thread's execution.  This is done by defining Shiro's <tt>SecureRemoteInvocationExecutor</tt> bean in <tt>applicationContext.xml</tt>:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag"><span class="code-comment">&lt;!-- Secure Spring remoting:  Ensure any Spring Remoting method invocations --&gt;</span></span>
+<span class="code-tag"><span class="code-comment">&lt;!-- can be associated with a Subject for security checks. --&gt;</span></span>
+<span class="code-tag">&lt;bean id=<span class="code-quote">"secureRemoteInvocationExecutor"</span> class=<span class="code-quote">"org.apache.shiro.spring.remoting.SecureRemoteInvocationExecutor"</span>&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"securityManager"</span> ref=<span class="code-quote">"securityManager"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+</pre>
+</div></div>
+
+<p>Once you have defined this bean, you must plug it in to whatever remoting <tt>Exporter</tt> you are using to export/expose your services.  <tt>Exporter</tt> implementations are defined according to the remoting mechanism/protocol in use.  See Spring's <a class="external-link" href="http://static.springsource.org/spring/docs/2.5.x/reference/remoting.html" rel="nofollow">Remoting chapter</a> on defining <tt>Exporter</tt> beans.</p>
+
+<p>For example, if using HTTP-based remoting (notice the property reference to the <tt>secureRemoteInvocationExecutor</tt> bean):</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag">&lt;bean name=<span class="code-quote">"/someService"</span> class=<span class="code-quote">"org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter"</span>&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"service"</span> ref=<span class="code-quote">"someService"</span>/&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"serviceInterface"</span> value=<span class="code-quote">"com.pkg.service.SomeService"</span>/&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"remoteInvocationExecutor"</span> ref=<span class="code-quote">"secureRemoteInvocationExecutor"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+</pre>
+</div></div>
+
+<h3><a name="Spring-ClientsideConfiguration"></a>Client-side Configuration</h3>
+
+<p>When a remote call is being executed, the <tt>Subject</tt> identifying information must be attached to the remoting payload to let the server know who is making the call.  If the client is a Spring-based client, that association is done via Shiro's <tt>SecureRemoteInvocationFactory</tt>:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag">&lt;bean id=<span class="code-quote">"secureRemoteInvocationFactory"</span> class=<span class="code-quote">"org.apache.shiro.spring.remoting.SecureRemoteInvocationFactory"</span>/&gt;</span>
+</pre>
+</div></div>
+
+<p>Then after you've defined this bean, you need to plug it in to the protocol-specific Spring remoting <tt>ProxyFactoryBean</tt> you're using.</p>
+
+<p>For example, if you were using HTTP-based remoting (notice the property reference to the <tt>secureRemoteInvocationFactory</tt> bean defined above):</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag">&lt;bean id=<span class="code-quote">"someService"</span> class=<span class="code-quote">"org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean"</span>&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"serviceUrl"</span> value=<span class="code-quote">"http://host:port/remoting/someService"</span>/&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"serviceInterface"</span> value=<span class="code-quote">"com.pkg.service.SomeService"</span>/&gt;</span>
+    <span class="code-tag">&lt;property name=<span class="code-quote">"remoteInvocationFactory"</span> ref=<span class="code-quote">"secureRemoteInvocationFactory"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+</pre>
+</div></div>
+
+<h2><a name="Spring-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2>
+
+<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time.  If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p>
+
+<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/" rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>
\ No newline at end of file

Added: shiro/site/trunk/subject.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/subject.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/subject.html (added)
+++ shiro/site/trunk/subject.html Sat May 11 21:10:40 2013
@@ -0,0 +1,356 @@
+<h1><a name="Subject-UnderstandingSubjectsinApacheShiro"></a>Understanding Subjects in Apache Shiro</h1>
+
+<p>Without question, the most important concept in Apache Shiro is the <tt>Subject</tt>.  'Subject' is just a security term that means a security-specific 'view' of an application user.  A Shiro <tt>Subject</tt> instance represents both security state and operations for a <em>single</em> application user.</p>
+
+<p>These operations include:</p>
+<ul><li>authentication (login)</li><li>authorization (access control)</li><li>session access</li><li>logout</li></ul>
+
+
+<p>We originally wanted to call it 'User' since that "just makes sense", but we decided against it: too many applications have existing APIs that already have their own User classes/frameworks, and we didn't want to conflict with those. Also, in the security world, the term 'Subject' is actually the recognized nomenclature.</p>
+
+<p>Shiro's API encourages a <tt>Subject</tt>-centric programming paradigm for applications.  When coding application logic, most application developers want to know who the <em>currently executing</em> user is.  While the application can usually look up any user via their own mechanisms (UserService, etc), when it comes to security, the most important question is <b>"Who is the <em>current</em> user?"</b></p>
+
+<p>While any Subject can be acquired by using the <tt>SecurityManager</tt>, application code based on only the current user/<tt>Subject</tt> is much more natural and intuitive.</p>
+
+<h2><a name="Subject-TheCurrentlyExecutingSubject"></a>The Currently Executing Subject</h2>
+
+<p>In almost all environments, you can obtain the currently executing <tt>Subject</tt> by using <tt>org.apache.shiro.SecurityUtils</tt>:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Subject currentUser = SecurityUtils.getSubject();
+</pre>
+</div></div>
+
+<p>The <tt>getSubject()</tt> call in a standalone application might return a <tt>Subject</tt> based on user data in an application-specific location, and in a server environment (e.g. web app), it acquires the Subject based on user data associated with current thread or incoming request.</p>
+
+<p>After you acquire the current <tt>Subject</tt>, what can you do with it?</p>
+
+<p>If you want to make things available to the user during their current session with the application, you can get their session:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Session session = currentUser.getSession();
+session.setAttribute( <span class="code-quote">"someKey"</span>, <span class="code-quote">"aValue"</span> );
+</pre>
+</div></div>
+
+<p>The <tt>Session</tt> is a Shiro-specific instance that provides most of what you're used to with regular HttpSessions but with some extra goodies and one <b>big</b> difference:  it does not require an HTTP environment!</p>
+
+<p>If deploying inside a web application, by default the <tt>Session</tt> will be <tt>HttpSession</tt> based.  But, in a non-web environment, like this simple Quickstart, Shiro will automatically use its Enterprise Session Management by default.  This means you get to use the same API in your applications, in any tier, regardless of deployment environment.  This opens a whole new world of applications since any application requiring sessions does not need to be forced to use the <tt>HttpSession</tt> or EJB Stateful Session Beans.  And, any client technology can now share session data.</p>
+
+<p>So now you can acquire a <tt>Subject</tt> and their <tt>Session</tt>.  What about the <em>really</em> useful stuff like checking if they are allowed to do things, like checking against roles and permissions?</p>
+
+<p>Well, we can only do those checks for a known user.  Our <tt>Subject</tt> instance above represents the current user, but <em>who</em> is actually the current user?  Well, they're anonymous - that is, until they log in at least once.  So, let's do that:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">if</span> ( !currentUser.isAuthenticated() ) {
+    <span class="code-comment">//collect user principals and credentials in a gui specific manner
+</span>    <span class="code-comment">//such as username/password html form, X509 certificate, OpenID, etc.
+</span>    <span class="code-comment">//We'll use the username/password example here since it is the most common.
+</span>    <span class="code-comment">//(<span class="code-keyword">do</span> you know what movie <span class="code-keyword">this</span> is from? ;)
+</span>    UsernamePasswordToken token = <span class="code-keyword">new</span> UsernamePasswordToken(<span class="code-quote">"lonestarr"</span>, <span class="code-quote">"vespa"</span>);
+    <span class="code-comment">//<span class="code-keyword">this</span> is all you have to <span class="code-keyword">do</span> to support 'remember me' (no config - built in!):
+</span>    token.setRememberMe(<span class="code-keyword">true</span>);
+    currentUser.login(token);
+}
+</pre>
+</div></div>
+
+<p>That's it!  It couldn't be easier.</p>
+
+<p>But what if their login attempt fails?  You can catch all sorts of specific exceptions that tell you exactly what happened:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">try</span> {
+    currentUser.login( token );
+    <span class="code-comment">//<span class="code-keyword">if</span> no exception, that's it, we're done!
+</span>} <span class="code-keyword">catch</span> ( UnknownAccountException uae ) {
+    <span class="code-comment">//username wasn't in the system, show them an error message?
+</span>} <span class="code-keyword">catch</span> ( IncorrectCredentialsException ice ) {
+    <span class="code-comment">//password didn't match, <span class="code-keyword">try</span> again?
+</span>} <span class="code-keyword">catch</span> ( LockedAccountException lae ) {
+    <span class="code-comment">//account <span class="code-keyword">for</span> that username is locked - can't login.  Show them a message?
+</span>} 
+    ... more types exceptions to check <span class="code-keyword">if</span> you want ...
+} <span class="code-keyword">catch</span> ( AuthenticationException ae ) {
+    <span class="code-comment">//unexpected condition - error?
+</span>}
+</pre>
+</div></div>
+
+<p>You, as the application/GUI developer can choose to show the end-user messages based on exceptions or not (for example, <tt>"There is no account in the system with that username."</tt>).  There are many different types of exceptions you can check, or throw your own for custom conditions Shiro might not account for.  See the <a class="external-link" href="http://www.jsecurity.org/api/org/jsecurity/authc/AuthenticationException.html" rel="nofollow">AuthenticationException JavaDoc</a> for more.</p>
+
+<p>Ok, so by now, we have a logged in user.  What else can we do?</p>
+
+<p>Let's say who they are:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-comment">//print their identifying principal (in <span class="code-keyword">this</span> <span class="code-keyword">case</span>, a username):
+</span>log.info( <span class="code-quote">"User ["</span> + currentUser.getPrincipal() + <span class="code-quote">"] logged in successfully."</span> );
+</pre>
+</div></div>
+
+<p>We can also test to see if they have specific role or not:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">if</span> ( currentUser.hasRole( <span class="code-quote">"schwartz"</span> ) ) {
+    log.info(<span class="code-quote">"May the Schwartz be with you!"</span> );
+} <span class="code-keyword">else</span> {
+    log.info( <span class="code-quote">"Hello, mere mortal."</span> );
+}
+</pre>
+</div></div>
+
+<p>We can also see if they have a <a href="permissions.html" title="Permissions">permission</a> to act on a certain type of entity:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">if</span> ( currentUser.isPermitted( <span class="code-quote">"lightsaber:weild"</span> ) ) {
+    log.info(<span class="code-quote">"You may use a lightsaber ring.  Use it wisely."</span>);
+} <span class="code-keyword">else</span> {
+    log.info(<span class="code-quote">"Sorry, lightsaber rings are <span class="code-keyword">for</span> schwartz masters only."</span>);
+}
+</pre>
+</div></div>
+
+<p>Also, we can perform an extremely powerful <em>instance-level</em> <a href="permissions.html" title="Permissions">permission</a> check - the ability to see if the user has the ability to access a specific instance of a type:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">if</span> ( currentUser.isPermitted( <span class="code-quote">"winnebago:drive:eagle5"</span> ) ) {
+    log.info(<span class="code-quote">"You are permitted to 'drive' the 'winnebago' with license plate (id) 'eagle5'.  "</span> +
+                <span class="code-quote">"Here are the keys - have fun!"</span>);
+} <span class="code-keyword">else</span> {
+    log.info(<span class="code-quote">"Sorry, you aren't allowed to drive the 'eagle5' winnebago!"</span>);
+}
+</pre>
+</div></div>
+
+<p>Piece of cake, right?</p>
+
+<p>Finally, when the user is done using the application, they can log out:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+currentUser.logout(); <span class="code-comment">//removes all identifying information and invalidates their session too.</span>
+</pre>
+</div></div>
+
+<p>This simple API constitutes 90% of what Shiro end-users will ever have to deal with when using Shiro.</p>
+
+<h2><a name="Subject-CustomSubjectInstances"></a>Custom Subject Instances</h2>
+
+<p>A new feature added in Shiro 1.0 is the ability to construct custom/ad-hoc subject instances for use in special situations.</p>
+
+<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Special Use Only!</b><br clear="none">You should almost always acquire the currently executing Subject by calling <tt>SecurityUtils.getSubject();</tt><br clear="none">
+Creating custom <tt>Subject</tt> instances should only be done in special cases.</td></tr></table></div>
+
+<p>Some 'special cases' when this can be useful:</p>
+
+<ul><li>System startup/bootstrap - when there are no users interacting with the system, but code should execute as a 'system' or daemon user.  It is desirable to create Subject instances representing a particular user so bootstrap code executes as that user (e.g. as the <tt>admin</tt> user).
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+This practice is encouraged because it ensures that utility/system code executes in the same way as a normal user, ensuring code is consistent.  This makes code easier to maintain since you don't have to worry about custom code blocks just for system/daemon scenarios.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li><li>Integration <a href="testing.html" title="Testing">Testing</a> - you might want to create <tt>Subject</tt> instances as necessary to be used in integration tests.  See the <a href="testing.html" title="Testing">testing documentation</a> for more.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li><li>Daemon/background process work - when a daemon or background process executes, it might need to execute as a particular user.</li></ul>
+
+
+<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1">If you already have access to a <tt>Subject</tt> instance and want it to be available to other threads, you should use the <tt>Subject.associateWith</tt>* methods instead of creating a new Subject instance.</td></tr></table></div> 
+
+<p>Ok, so assuming you still need to create custom subject instances, let's see how to do it:</p>
+
+<h3><a name="Subject-Subject.Builder"></a>Subject.Builder</h3>
+
+<p>The <tt>Subject.Builder</tt> class is provided to build <tt>Subject</tt> instances easily without needing to know construction details.</p>
+
+<p>The simplest usage of the Builder is to construct an anonymous, session-less <tt>Subject</tt> instance:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Subject subject = <span class="code-keyword">new</span> Subject.Builder().buildSubject()
+</pre>
+</div></div>
+
+<p>The default, no-arg <tt>Subject.Builder()</tt> constructor shown above will use the application's currently accessible <tt>SecurityManager</tt> via the <tt>SecurityUtils.getSecurityManager()</tt> method.  You may also specify the <tt>SecurityManager</tt> instance to be used by the additional constructor if desired:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-object">SecurityManager</span> securityManager = <span class="code-comment">//acquired from somewhere
+</span>Subject subject = <span class="code-keyword">new</span> Subject.Builder(securityManager).buildSubject();
+</pre>
+</div></div>
+
+<p>All other <tt>Subject.Builder</tt> methods may be called before the <tt>buildSubject()</tt> method to provide context on how to construct the <tt>Subject</tt> instance.  For example, if you have a session ID and want to acquire the <tt>Subject</tt> that 'owns' that session (assuming the session exists and is not expired):</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Serializable sessionId = <span class="code-comment">//acquired from somewhere
+</span>Subject subject = <span class="code-keyword">new</span> Subject.Builder().sessionId(sessionId).buildSubject();
+</pre>
+</div></div>
+
+<p>Similarly, if you want to create a <tt>Subject</tt> instance that reflects a certain identity:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-object">Object</span> userIdentity = <span class="code-comment">//a <span class="code-object">long</span> ID or <span class="code-object">String</span> username, or whatever the <span class="code-quote">"myRealm"</span> requires
+</span><span class="code-object">String</span> realmName = <span class="code-quote">"myRealm"</span>;
+PrincipalCollection principals = <span class="code-keyword">new</span> SimplePrincipalCollection(userIdentity, realmName);
+Subject subject = <span class="code-keyword">new</span> Subject.Builder().principals(principals).buildSubject();
+</pre>
+</div></div>
+
+<p>You can then use the built <tt>Subject</tt> instance and make calls on it as expected. But <b>note</b>:  </p>
+
+<p>The built <tt>Subject</tt> instance is <b>not</b> automatically bound to the application (thread) for further use.  If you want it to be available to any code that calls <tt>SecurityUtils.getSubject()</tt>, you must ensure a Thread is associated with the constructed <tt>Subject</tt>.</p>
+
+<h3><a name="Subject-ThreadAssociation"></a>Thread Association <a name="Subject-ThreadAssociation"></a></h3>
+
+<p>As stated above, just building a <tt>Subject</tt> instance does not associate it with a thread - a usual requirement if any calls to <tt>SecurityUtils.getSubject()</tt> during thread execution are to work properly.  There are three ways of ensuring a thread is associated with a <tt>Subject</tt>:</p>
+
+<ul><li><b>Automatic Association</b> - A <tt>Callable</tt> or <tt>Runnable</tt> executed via the <tt>Subject.execute</tt>* methods will automatically bind and unbind the Subject to the thread before and after <tt>Callable</tt>/<tt>Runnable</tt> execution.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li><li><b>Manual Association</b> - You manually bind and unbind the <tt>Subject</tt> instance to the currently executing thread.  This is usually useful for framework developers.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li><li><b>Different Thread</b> - A <tt>Callable</tt> or <tt>Runnable</tt> is associated with a <tt>Subject</tt> by calling the <tt>Subject.associateWith</tt>* methods and then the returned <tt>Callable</tt>/<tt>Runnable</tt> is executed by another thread.  This is the preferred approach if you need to execute work on another thread as the <tt>Subject</tt>.</li></ul>
+
+
+<p>The important thing to know about thread association is that 2 things must always occur:</p>
+
+<ol><li>The Subject is <em>bound</em> to the thread so it is available at all points of the thread's execution.  Shiro does this via its <tt>ThreadState</tt> mechanism which is an abstraction on top of a <tt>ThreadLocal</tt>.</li><li>The Subject is <em>unbound</em> at some point later, even if the thread execution results in an error.  This ensures the thread remains clean and clear of any previous <tt>Subject</tt> state in a pooled/reusable thread environment.</li></ol>
+
+
+<p>These principles are guaranteed to occur in the 3 mechanisms listed above.  Their usage is elaborated next.</p>
+
+<h4><a name="Subject-AutomaticAssociation"></a>Automatic Association </h4>
+
+<p>If you only need a <tt>Subject</tt> to be temporarily associated with the current thread, and you want the thread binding and cleanup to occur automatically, a <tt>Subject</tt>'s direct execution of a <tt>Callable</tt> or <tt>Runnable</tt> is the way to go.  After the <tt>Subject.execute</tt> call returns, the current thread is guaranteed to be in the same state as it was before the execution.  This mechanism is the most widely used of the three.</p>
+
+<p>For example, let's say that you had some logic to perform when the system starts up.  You want to execute a chunk of code as a particular user, but once the logic is finished, you want to ensure the thread/environment goes back to normal automatically.  You would do that by calling the <tt>Subject.execute</tt>* methods:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Subject subject = <span class="code-comment">//build or acquire subject
+</span>subject.execute( <span class="code-keyword">new</span> <span class="code-object">Runnable</span>() {
+    <span class="code-keyword">public</span> void run() {
+        <span class="code-comment">//subject is 'bound' to the current thread now
+</span>        <span class="code-comment">//any SecurityUtils.getSubject() calls in any
+</span>        <span class="code-comment">//code called from here will work
+</span>    }
+});
+<span class="code-comment">//At <span class="code-keyword">this</span> point, the Subject is no longer associated
+</span><span class="code-comment">//with the current thread and everything is as it was before</span>
+</pre>
+</div></div>
+
+<p>Of course <tt>Callable</tt> instances are supported as well so you can have return values and catch exceptions:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Subject subject = <span class="code-comment">//build or acquire subject
+</span>MyResult result = subject.execute( <span class="code-keyword">new</span> Callable&lt;MyResult&gt;() {
+    <span class="code-keyword">public</span> MyResult call() <span class="code-keyword">throws</span> Exception {
+        <span class="code-comment">//subject is 'bound' to the current thread now
+</span>        <span class="code-comment">//any SecurityUtils.getSubject() calls in any
+</span>        <span class="code-comment">//code called from here will work
+</span>        ...
+        <span class="code-comment">//finish logic as <span class="code-keyword">this</span> Subject
+</span>        ...
+        <span class="code-keyword">return</span> myResult;        
+    }
+});
+<span class="code-comment">//At <span class="code-keyword">this</span> point, the Subject is no longer associated
+</span><span class="code-comment">//with the current thread and everything is as it was before</span>
+</pre>
+</div></div>
+
+<p>This approach is also useful in framework development.  For example, Shiro's support for secure Spring remoting ensures the remote invocation is executed as a particular subject:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Subject.Builder builder = <span class="code-keyword">new</span> Subject.Builder();
+<span class="code-comment">//populate the builder's attributes based on the incoming RemoteInvocation
+</span>...
+Subject subject = builder.buildSubject();
+
+<span class="code-keyword">return</span> subject.execute(<span class="code-keyword">new</span> Callable() {
+    <span class="code-keyword">public</span> <span class="code-object">Object</span> call() <span class="code-keyword">throws</span> Exception {
+        <span class="code-keyword">return</span> invoke(invocation, targetObject);
+    }
+});
+</pre>
+</div></div>
+
+<h4><a name="Subject-ManualAssociation"></a>Manual Association</h4>
+
+<p>While the <tt>Subject.execute</tt>* methods automatically clean up the thread state after they return, there might be some scenarios where you want to manage the <tt>ThreadState</tt> yourself.  This is almost always done in framework-level development when integrating w/ Shiro and is rarely used even in bootstrap/daemon scenarios (where the <tt>Subject.execute(callable)</tt> example above is more frequent).</p>
+
+<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Guarantee Cleanup</b><br clear="none">The most important thing about this mechanism is that you must <em>always</em> guarantee the current thread is cleaned up after logic is executed to ensure there is no thread state corruption in a reusable or pooled thread environment.</td></tr></table></div>
+
+<p>Guaranteeing cleanup is best done in a <tt>try/finally</tt> block:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Subject subject = <span class="code-keyword">new</span> Subject.Builder()...
+ThreadState threadState = <span class="code-keyword">new</span> SubjectThreadState(subject);
+threadState.bind();
+<span class="code-keyword">try</span> {
+    <span class="code-comment">//execute work as the built Subject
+</span>} <span class="code-keyword">finally</span> {
+    <span class="code-comment">//ensure any state is cleaned so the thread won't be 
+</span>    <span class="code-comment">//corrupt in a reusable or pooled thread environment
+</span>    threadState.clear();
+}
+</pre>
+</div></div>
+
+<p>Interestingly enough, this is exactly what the <tt>Subject.execute</tt>* methods do - they just perform this logic automatically before and after <tt>Callable</tt> or <tt>Runnable</tt> execution.  It is also nearly identical logic performed by Shiro's <tt>ShiroFilter</tt> for web applications (<tt>ShiroFilter</tt> uses web-specific <tt>ThreadState</tt> implementations outside the scope of this section).</p>
+
+<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Web Use</b><br clear="none">Don't use the above <tt>ThreadState</tt> code example in a thread that is processing a web request.  Web-specific ThreadState implementations are used during web requests instead.  Instead, ensure the <tt>ShiroFilter</tt> intercepts web requests to ensure Subject building/binding/cleanup is done properly.</td></tr></table></div>
+
+<h4><a name="Subject-ADifferentThread"></a>A Different Thread</h4>
+
+<p>If you have a <tt>Callable</tt> or <tt>Runnable</tt> instance that should execute as a <tt>Subject</tt> and you will execute the <tt>Callable</tt> or <tt>Runnable</tt> yourself (or hand it off to a thread pool or <tt>Executor</tt> or <tt>ExecutorService</tt> for example), you should use the <tt>Subject.associateWith</tt>* methods.  These methods ensure that the Subject is retained and accessible on the thread that eventually executes.</p>
+
+<p>Callable example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Subject subject = <span class="code-keyword">new</span> Subject.Builder()...
+Callable work = <span class="code-comment">//build/acquire a Callable instance.
+</span><span class="code-comment">//associate the work with the built subject so SecurityUtils.getSubject() calls works properly:
+</span>work = subject.associateWith(work);
+ExecutorService executorService = <span class="code-keyword">new</span> java.util.concurrent.Executors.newCachedThreadPool();
+<span class="code-comment">//execute the work on a different thread as the built Subject:
+</span>executor.execute(work);
+</pre>
+</div></div>
+
+<p>Runnable example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Subject subject = <span class="code-keyword">new</span> Subject.Builder()...
+<span class="code-object">Runnable</span> work = <span class="code-comment">//build/acquire a <span class="code-object">Runnable</span> instance.
+</span><span class="code-comment">//associate the work with the built subject so SecurityUtils.getSubject() calls works properly:
+</span>work = subject.associateWith(work);
+Executor executor = <span class="code-keyword">new</span> java.util.concurrent.Executors.newCachedThreadPool();
+<span class="code-comment">//execute the work on a different thread as the built Subject:
+</span>executor.execute(work);
+</pre>
+</div></div>
+
+<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Automatic Cleanup</b><br clear="none">The <tt>associateWith</tt>* methods perform necessary thread cleanup automatically to ensure threads remain clean in a pooled environment.</td></tr></table></div>
+
+<h2><a name="Subject-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2>
+
+<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time.  If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p>
+
+<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/" rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>
\ No newline at end of file

Added: shiro/site/trunk/support.md
URL: http://svn.apache.org/viewvc/shiro/site/trunk/support.md?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/support.md (added)
+++ shiro/site/trunk/support.md Sat May 11 21:10:40 2013
@@ -0,0 +1,16 @@
+title: Apache Shiro Community Support
+
+# a name="Support-ApacheShiroCommunitySupport">Apache Shiro Community Support
+
+The Shiro project offers support through its community of users, contributors, and project committers.
+
+We encourage everyone to participate and use the available community support tools below.
+
+* [Mailing Lists](mailing-lists.html "Mailing Lists")
+* [Forums](forums.html "Forums")
+
+<a href="mailing-lists.html" title="Mailing Lists">Mailing Lists</a></li><li><a href="forums.html" title="Forums">Forums</a></li><li><a href="issues.html" title="Issues">Issue &amp; Bug Tracking</a></li></ul>
+
+
+<h2><a name="Support-CommericalSupport"></a>Commerical Support</h2>
+<p><b><a href="commercial-support.html" title="Commercial Support">Commercial support and consulting</a></b> for Apache Shiro is offered by outside organizations who are actively involved with the project.</p>
\ No newline at end of file

Added: shiro/site/trunk/tags.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/tags.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/tags.html (added)
+++ shiro/site/trunk/tags.html Sat May 11 21:10:40 2013
@@ -0,0 +1,5 @@
+<script type="text/javascript">
+<!--
+window.location = "http://svn.apache.org/repos/asf/shiro/trunk/web/src/main/resources/META-INF/shiro.tld"
+//-->
+</script>

Added: shiro/site/trunk/team.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/team.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/team.html (added)
+++ shiro/site/trunk/team.html Sat May 11 21:10:40 2013
@@ -0,0 +1,3 @@
+<h1><a name="Team-ApacheShiroTeam"></a>Apache Shiro Team</h1>
+
+<p>TODO: list dev team members here</p>
\ No newline at end of file

Added: shiro/site/trunk/templates/default.vtl
URL: http://svn.apache.org/viewvc/shiro/site/trunk/templates/default.vtl?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/templates/default.vtl (added)
+++ shiro/site/trunk/templates/default.vtl Sat May 11 21:10:40 2013
@@ -0,0 +1,110 @@
+<!--
+   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.
+-->
+<html>
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <meta name="description" content="Apache Shiro is a powerful and easy-to-use Java security framework that performs authentication, authorization, cryptography, and session management.">
+    <meta name="google-site-verification" content="QIax6uT5UX3enoU0G8Pz2pXbQ45KaQuHZ3nCh9V27mw">
+    <meta name="msvalidate.01" content="0B57EB46CBFAD8FD45008D2DB6B6C68C">
+    <meta name="y_key" content="e47896cd6bae4920">
+
+    ## Only render a <title> element if the page specifies a title:
+    #if ($title)
+        <title>
+        #if($title.contains("|"))
+            ## specifying a custom title, just render it directly:
+            $title
+        #else
+            ## standard title, append the project name appended for SEO:
+            $title | Apache Shiro
+        #end
+        </title>
+    #end
+
+    <link rel="icon" type="image/vnd.microsoft.icon" href="$root/assets/images/favicon.ico">
+
+    <link rel="stylesheet" type="text/css" href="$root/assets/css/normalize.css">
+    <link rel="stylesheet" type="text/css" href="$root/assets/css/confluence.css" media="screen">
+    <link rel="stylesheet" type="text/css" href="$root/assets/css/style.css">
+
+    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.0/jquery.min.js"></script>
+    <script type="text/javascript" src="$root/assets/js/jquery_googleanalytics/jquery.google-analytics.js"></script>
+    <script type="text/javascript">
+        // initialize plugins
+        jQuery(function() {
+            //Google Analytics
+            jQuery.trackPage('UA-11551827-1');
+        });
+    </script>
+</head>
+
+<body>
+    <div id="top-bar"></div>
+
+    <div class="wrapper">
+
+        <div id="header">
+            <a href="$root/index.html"><div id="logo"></div></a>
+            <div id="navigation">
+                <a href="$root/download.html">
+                    <div class="navigation-button">Get Started</div>
+                </a>
+                <a href="$root/documentation.html">
+                    <div class="navigation-button">Get Smart</div>
+                </a>
+                <a href="$root/support.html">
+                    <div class="navigation-button">Get Help</div>
+                </a>
+                <a href="$root/commercial-support.html">
+                    <div class="navigation-button">Get Support</div>
+                </a>
+            </div> <!--END NAVIGATION-->
+            <div id="secondary-navigation">
+                <ul>
+                    <li><a href="$root/documentation.html">Documentation</a></li>
+                    <li><a href="$root/news.html">News</a></li>
+                    <li><a href="$root/events.html">Events</a></li>
+                    <li><a href="http://twitter.com/ApacheShiro/">Twitter</a></li>
+                    <li><a href="$root/mailing-lists.html">Mailing lists</a></li>
+                    <li><a href="$root/contribute.html">Contribute</a></li>
+                </ul>
+            </div> <!--END SECONDARY NAVIGATION-->
+        </div>
+
+        <div id="content">
+
+            $content
+
+        </div>
+
+    </div><!--END WRAPPER-->
+
+    <div id="footer">
+
+        <div class="wrapper">
+
+            <a href="http://www.apache.org/foundation/contributing.html">Donate to the ASF</a> |
+            <a href="http://www.apache.org/licenses/LICENSE-2.0.html">License</a>
+            <p>Copyright &copy; 2008-$year The Apache Software Foundation</p>
+            <div class="footer-shield"></div>
+
+        </div> <!--END FOOTER WRAPPER-->
+
+    </div> <!--END FOOTER-->
+
+</body>
+</html>
\ No newline at end of file

Added: shiro/site/trunk/terminology.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/terminology.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/terminology.html (added)
+++ shiro/site/trunk/terminology.html Sat May 11 21:10:40 2013
@@ -0,0 +1,85 @@
+<h1><a name="Terminology-ApacheShiroTerminology"></a>Apache Shiro Terminology</h1>
+
+<p>Please just take 2 minutes to read and understand this - it is <em>really</em> important.  Really.  The terms and concepts here are referred to everywhere in the documentation and it will <em>greatly</em> simplify your understanding of Shiro and security in general.</p>
+
+<p>Security can be really confusing because of the terminology used.  We'll make life easier by clarifying some core concepts and you'll see how nicely the Shiro API reflects them:</p>
+
+<p><a name="Terminology-authentication"></a></p>
+<ul><li><b>Authentication</b><br clear="none">
+Authentication is the process of verifying a Subject's identity - essentially proving that someone really is who they say they are.  When an authentication attempt is successful the application can trust that the subject is guaranteed to be who the application expects.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-authorization"></a></li><li><b>Authorization</b><br clear="none">
+Authorization, also known as Access Control, is the process of determining if a user/Subject is allowed to do something or not.  It is usually accomplished by inspecting and interpreting a Subject's roles and permissions (see below) and then allowing or denying access to a requested resource or function.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-cipher"></a></li><li><b>Cipher</b><br clear="none">
+A cipher is an algorithm for performing encryption or decryption.  The algorithm generally relies on a piece of information called a key. And the encryption varies based on the key so decyrption is extremely difficult without it.  
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Ciphers come in different variations.  Block Ciphers work on blocks of symbols usually of a fixed size while Stream Ciphers work on a continuous stream of symbols.  Symmetric Ciphers use the same key for encryption and decryption while Asymmetric Ciphers use different keys.  And if a key in an asymmetric cipher cannot be derived from the other, then one can be shared publicly creating public/private key pairs.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-credential"></a></li><li><b>Credential</b><br clear="none">
+A <em>Credential</em> is a piece of information that verifies the identity of a user/Subject.  One (or more) credentials are submitted along with Principal(s) during an authentication attempt to verify that the user/Subject submitting them is actually the associated user.  Credentials are usually very secret things that only a particular user/Subject would know, such as a password or a PGP key or biometric attribute or similar mechanism.  
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+The idea is that for a principal, only one person would know the correct credential to 'pair' with that principal.  If the current user/Subject provides the correct credential matching the one stored in the system, then the system can assume and trust that the current user/Subject is really who they say they are.  The degree of trust increases with more secure credential types (e.g. biometric signature &gt; password).
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-cryptography"></a></li><li><b>Cryptography</b><br clear="none">
+Cryptography is the practice of protecting information from undesired access by hiding it or converting it into nonsense so know one else can read it. Shiro focuses on two core elements of Cryptography: ciphers that encrypt data like email using a public or private key, and hashes (aka message digests) that irreversibly encrypt data like passwords.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-hash"></a></li><li><b>Hash</b><br clear="none">
+A Hash function is a one-way, irreversible conversion of an input source, sometimes called the message, into an encoded hash value, sometimes called the message digest. It is often used for passwords, digital fingerprints, or data with an underlying byte array.  
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-permission"></a></li><li><b>Permission</b><br clear="none">
+A Permission, at least as Shiro interprets it, is a statement that describes raw functionality in an application and nothing more.  Permissions are the lowest-level constructs in security policies.  They define only "What" the application can do.  They do not describe "Who" is able to perform the actions.  A Permission is only a statement of behavior, nothing more.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Some examples of permissions:
+	<ul><li>Open a file</li><li>View the '/user/list' web page</li><li>Print documents</li><li>Delete the 'jsmith' user
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-principal"></a></li></ul>
+	</li><li><b>Principal</b><br clear="none">
+A <em>Principal</em> is any identifying attribute of an application user (Subject).  An 'identifying attribute' can be anything that makes sense to your application - a username, a surname, a given name, a social security number, a user ID, etc.  That's it - nothing crazy.  
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Shiro also references something we call a <tt>Subject</tt>'s <em>primary</em> principal.  A <em>Primary</em> principal is any principal that uniquely identifies the <tt>Subject</tt> across the entire application.  Ideal primary principals are things like a username or a user ID that is a RDBMS user table primary key.  There is only one primary principal for users (Subjects) in an application.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-realm"></a></li><li><b>Realm</b><br clear="none">
+A Realm is a component that can access application-specific security data such as users, roles, and permissions. It can be thought of as a security-specific DAO (Data Access Object).  The Realm translates this application-specific data into a format that Shiro understands so Shiro can in turn provide a single easy-to-understand Subject programming API no matter how many data sources exist or how application-specific your data might be.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Realms usually have a 1-to-1 correlation with a data source such as a relational database, LDAP directory, file system, or other similar resource. As such, implementations of the Realm interface use data source-specific APIs to discover authorization data (roles, permissions, etc), such as JDBC, File IO, Hibernate or JPA, or any other Data Access API.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-role"></a></li><li><b>Role</b><br clear="none">
+The definition of a Role can vary based on who you talk to.  In many applications it is nebulous concept at best that people use to implicitly define security policies.  Shiro prefers to interpret a Role as simply a named collection of Permissions.  That's it - an application unique name aggregating one or more Permission declarations.  
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+This is a more concrete definition than the implicit one used by many applications.  If you choose to have your data model reflect Shiro's assumption, you'll find you will have much more power in controlling security policies.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-session"></a></li><li><b>Session</b><br clear="none">
+A Session is a stateful data context associated with a single user/Subject who interacts with a software system over a period of time.  Data can be added/read/removed from the Session while the subject uses the application and the application can use this data later where necessary.  Sessions are terminated when the user/Subject logs out of the application or when it times out due to inactivity.  
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+For those familiar with the HttpSession, a Shiro <tt>Session</tt> serves the same purpose, except Shiro sessions can be used in any environment even if there is no Servlet container or EJB container available.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<a name="Terminology-subject"></a></li><li><b>Subject</b><br clear="none">
+A <em>Subject</em> is just fancy security term that basically means a security-specific 'view' of an application user.  A Subject does not always need to reflect a human being though - it can represent an external process calling your application, or perhaps a daemon system account that executes something intermittently over a period of time (such as a cron job).  It is basically a representation of any entity that is doing something with the application.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li></ul>
+
+
+<h2><a name="Terminology-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2>
+
+<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time.  If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p>
+
+<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/" rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>
\ No newline at end of file

Added: shiro/site/trunk/testing.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/testing.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/testing.html (added)
+++ shiro/site/trunk/testing.html Sat May 11 21:10:40 2013
@@ -0,0 +1,241 @@
+<h1><a name="Testing-TestingwithApacheShiro"></a>Testing with Apache Shiro</h1>
+
+<p>This part of the documentation explains how to enable Shiro in unit tests.</p>
+
+<h2><a name="Testing-Whattoknowfortests"></a>What to know for tests</h2>
+
+<p>As we've already covered in the <a href="subject.html" title="Subject">Subject reference</a>, we know that a Subject is security-specific view of the 'currently executing' user, and that Subject instances are always bound to a thread to ensure we know <em>who</em> is executing logic at any time during the thread's execution.</p>
+
+<p>This means three basic things must always occur in order to support being able to access the currently executing Subject:</p>
+
+<ol><li>A <tt>Subject</tt> instance must be created</li><li>The <tt>Subject</tt> instance must be <em>bound</em> to the currently executing thread.</li><li>After the thread is finished executing (or if the thread's execution results in a <tt>Throwable</tt>), the <tt>Subject</tt> must be <em>unbound</em> to ensure that the thread remains 'clean' in any thread-pooled environment.</li></ol>
+
+
+<p>Shiro has architectural components that perform this bind/unbind logic automatically for a running application.  For example, in a web application, the root Shiro Filter performs this logic when <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/servlet/AbstractShiroFilter.html#doFilterInternal(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain)">filtering a request</a>.  But as test environments and frameworks differ, we need to perform this bind/unbind logic ourselves for our chosen test framework.</p>
+
+<h2><a name="Testing-TestSetup"></a>Test Setup</h2>
+
+<p>So we know after creating a <tt>Subject</tt> instance, it must be <em>bound</em> to thread.  After the thread (or in this case, a test) is finished executing, we must <em>unbind</em> the Subject to keep the thread 'clean'.</p>
+
+<p>Luckily enough, modern test frameworks like JUnit and TestNG natively support this notion of 'setup' and 'teardown' already.  We can leverage this support to simulate what Shiro would do in a 'complete' application.  We've created a base abstract class that you can use in your own testing below - feel free to copy and/or modify as you see fit.  It can be used in both unit testing and integration testing (we're using JUnit in this example, but TestNG works just as well):</p>
+
+<h3><a name="Testing-AbstractShiroTest"></a>AbstractShiroTest</h3>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">import</span> org.apache.shiro.SecurityUtils;
+<span class="code-keyword">import</span> org.apache.shiro.UnavailableSecurityManagerException;
+<span class="code-keyword">import</span> org.apache.shiro.mgt.<span class="code-object">SecurityManager</span>;
+<span class="code-keyword">import</span> org.apache.shiro.subject.Subject;
+<span class="code-keyword">import</span> org.apache.shiro.subject.support.SubjectThreadState;
+<span class="code-keyword">import</span> org.apache.shiro.util.LifecycleUtils;
+<span class="code-keyword">import</span> org.apache.shiro.util.ThreadState;
+<span class="code-keyword">import</span> org.junit.AfterClass;
+
+/**
+ * Abstract test <span class="code-keyword">case</span> enabling Shiro in test environments.
+ */
+<span class="code-keyword">public</span> <span class="code-keyword">abstract</span> class AbstractShiroTest {
+
+    <span class="code-keyword">private</span> <span class="code-keyword">static</span> ThreadState subjectThreadState;
+
+    <span class="code-keyword">public</span> AbstractShiroTest() {
+    }
+
+    /**
+     * Allows subclasses to set the currently executing {@link Subject} instance.
+     *
+     * @param subject the Subject instance
+     */
+    <span class="code-keyword">protected</span> void setSubject(Subject subject) {
+        clearSubject();
+        subjectThreadState = createThreadState(subject);
+        subjectThreadState.bind();
+    }
+
+    <span class="code-keyword">protected</span> Subject getSubject() {
+        <span class="code-keyword">return</span> SecurityUtils.getSubject();
+    }
+
+    <span class="code-keyword">protected</span> ThreadState createThreadState(Subject subject) {
+        <span class="code-keyword">return</span> <span class="code-keyword">new</span> SubjectThreadState(subject);
+    }
+
+    /**
+     * Clears Shiro's thread state, ensuring the thread remains clean <span class="code-keyword">for</span> <span class="code-keyword">future</span> test execution.
+     */
+    <span class="code-keyword">protected</span> void clearSubject() {
+        doClearSubject();
+    }
+
+    <span class="code-keyword">private</span> <span class="code-keyword">static</span> void doClearSubject() {
+        <span class="code-keyword">if</span> (subjectThreadState != <span class="code-keyword">null</span>) {
+            subjectThreadState.clear();
+            subjectThreadState = <span class="code-keyword">null</span>;
+        }
+    }
+
+    <span class="code-keyword">protected</span> <span class="code-keyword">static</span> void setSecurityManager(<span class="code-object">SecurityManager</span> securityManager) {
+        SecurityUtils.setSecurityManager(securityManager);
+    }
+
+    <span class="code-keyword">protected</span> <span class="code-keyword">static</span> <span class="code-object">SecurityManager</span> getSecurityManager() {
+        <span class="code-keyword">return</span> SecurityUtils.getSecurityManager();
+    }
+
+    @AfterClass
+    <span class="code-keyword">public</span> <span class="code-keyword">static</span> void tearDownShiro() {
+        doClearSubject();
+        <span class="code-keyword">try</span> {
+            <span class="code-object">SecurityManager</span> securityManager = getSecurityManager();
+            LifecycleUtils.destroy(securityManager);
+        } <span class="code-keyword">catch</span> (UnavailableSecurityManagerException e) {
+            <span class="code-comment">//we don't care about <span class="code-keyword">this</span> when cleaning up the test environment
+</span>            <span class="code-comment">//(<span class="code-keyword">for</span> example, maybe the subclass is a unit test and it didn't
+</span>            <span class="code-comment">// need a <span class="code-object">SecurityManager</span> instance because it was using only 
+</span>            <span class="code-comment">// mock Subject instances)
+</span>        }
+        setSecurityManager(<span class="code-keyword">null</span>);
+    }
+}
+</pre>
+</div></div>
+
+<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Testing &amp; Frameworks</b><br clear="none">The code in the <tt>AbstractShiroTest</tt> class uses Shiro's <tt>ThreadState</tt> concept and a static SecurityManager.  These techniques are useful in tests and in framework code, but rarely ever used in application code.  
+
+<p>Most end-users working with Shiro who need to ensure thread-state consistency will almost always use Shiro's automatic management mechanisms, namely the <tt>Subject.associateWith</tt> and the <tt>Subject.execute</tt> methods.  These methods are covered in the reference on <a href="subject.html#Subject-ThreadAssociation">Subject thread association</a>.</p></td></tr></table></div>
+
+<h2><a name="Testing-UnitTesting"></a>Unit Testing</h2>
+
+<p>Unit testing is mostly about testing your code and only your code in a limited scope.  When you take Shiro into account, what you really want to focus on is that your code works correctly with Shiro's <em>API</em> - you don't want to necessarily test that Shiro's implementation is working correctly (that's something that the Shiro development team must ensure in Shiro's code base).</p>
+
+<p>Testing to see if Shiro's implementations work in conjunction with your implementations is really integration testing (discussed below).</p>
+
+<h3><a name="Testing-ExampleShiroUnitTest"></a>ExampleShiroUnitTest</h3>
+
+<p>Because unit tests are better suited for testing your own logic (and not any implementations your logic might call), it is a great idea to <em>mock</em> any APIs that your logic depends on.  This works very well with Shiro - you can mock the <tt>Subject</tt> interface and have it reflect whatever conditions you want your code under test to react to.  We can leverage modern mock frameworks like <a class="external-link" href="http://easymock.org/" rel="nofollow">EasyMock</a> and <a class="external-link" href="http://mockito.org/" rel="nofollow">Mockito</a> to do this for us.  </p>
+
+<p>But as stated above, the key in Shiro tests is to remember that any Subject instance (mock or real) must be bound to the thread during test execution.  So all we need to do is bind the mock Subject to ensure things work as expected.</p>
+
+<p>(this example uses EasyMock, but Mockito works equally as well):</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">import</span> org.apache.shiro.subject.Subject;
+<span class="code-keyword">import</span> org.junit.After;
+<span class="code-keyword">import</span> org.junit.Test;
+
+<span class="code-keyword">import</span> <span class="code-keyword">static</span> org.easymock.EasyMock.*;
+
+/**
+ * Simple example test class showing how one may perform unit tests <span class="code-keyword">for</span> code that requires Shiro APIs.
+ */
+<span class="code-keyword">public</span> class ExampleShiroUnitTest <span class="code-keyword">extends</span> AbstractShiroTest {
+
+    @Test
+    <span class="code-keyword">public</span> void testSimple() {
+
+        <span class="code-comment">//1.  Create a mock authenticated Subject instance <span class="code-keyword">for</span> the test to run:
+</span>        Subject subjectUnderTest = createNiceMock(Subject.class);
+        expect(subjectUnderTest.isAuthenticated()).andReturn(<span class="code-keyword">true</span>);
+
+        <span class="code-comment">//2. Bind the subject to the current thread:
+</span>        setSubject(subjectUnderTest);
+
+        <span class="code-comment">//perform test logic here.  Any call to 
+</span>        <span class="code-comment">//SecurityUtils.getSubject() directly (or nested in the 
+</span>        <span class="code-comment">//call stack) will work properly.
+</span>    }
+
+    @After
+    <span class="code-keyword">public</span> void tearDownSubject() {
+        <span class="code-comment">//3. Unbind the subject from the current thread:
+</span>        clearSubject();
+    }
+
+}
+</pre>
+</div></div>
+
+<p>As you can see, we're not setting up a Shiro <tt>SecurityManager</tt> instance or configuring a <tt>Realm</tt> or anything like that.  We're simply creating a mock <tt>Subject</tt> instance and binding it to the thread via the <tt>setSubject</tt> method call.  This will ensure that any calls in our test code or in the code we're testing to <tt>SecurityUtils.getSubject()</tt> will work correctly.</p>
+
+<p>Note that the <tt>setSubject</tt> method implementation will bind your mock Subject to the thread and it will remain there until you call <tt>setSubject</tt> with a different <tt>Subject</tt> instance or until you explicitly clear it from the thread via the <tt>clearSubject()</tt> call.</p>
+
+<p>How long you keep the subject bound to the thread (or swap it out for a new instance in a different test) is up to you and your testing requirements.  </p>
+
+<h4><a name="Testing-tearDownSubject%28%29"></a>tearDownSubject()</h4>
+
+<p>The <tt>tearDownSubject()</tt> method in the example uses a Junit 4 annotation to ensure that the Subject is cleared from the thread after every test method is executed, no matter what.  This requires you to set up a new <tt>Subject</tt> instance and set it (via <tt>setSubject</tt>) for every test that executes.</p>
+
+<p>This is not strictly necessary however.  For example, you could just bind a new Subject instance (via <tt>setSujbect</tt>) at the beginning of every test, say, in an <tt>@Before</tt>-annotated method.  But if you're going to do that, you might as well have the <tt>@After tearDownSubject()</tt> method to keep things symmetrical and 'clean'.</p>
+
+<p>You can mix and match this setup/teardown logic in each method manually or use the @Before and @After annotations as you see fit.  The <tt>AbstractShiroTest</tt> super class will however unbind the Subject from the thread after all tests because of the <tt>@AfterClass</tt> annotation in its <tt>tearDownShiro()</tt> method.</p>
+
+<h2><a name="Testing-IntegrationTesting"></a>Integration Testing</h2>
+
+<p>Now that we've covered unit test setup, let's talk a bit about integration testing.  Integration testing is testing implementations across API boundaries.  For example, testing that implementation A works when calling implementation B and that implementation B does what it is supposed to.</p>
+
+<p>You can easily perform integration testing in Shiro as well.  Shiro's <tt>SecurityManager</tt> instance and things it wraps (like Realms and SessionManager, etc) are all very lightweight POJOs that use very little memory.  This means you can create and tear down a <tt>SecurityManager</tt> instance for every test class you execute.  When your integration tests run, they will be using 'real' <tt>SecurityManager</tt> and <tt>Subject</tt> instances like your application will be using at runtime.</p>
+
+<h3><a name="Testing-ExampleShiroIntegrationTest"></a>ExampleShiroIntegrationTest</h3>
+
+<p>The example code below looks almost identical to the Unit Test example above, but the 3 step process is slightly different:</p>
+
+<ol><li>There is now a step '0', which sets up a 'real' SecurityManager instance.</li><li>Step 1 now constructs a 'real' Subject instance with the <tt>Subject.Builder</tt> and binds it to the thread.</li></ol>
+
+
+<p>Thread binding and unbinding (steps 2 and 3) function the same as the Unit Test example.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">import</span> org.apache.shiro.config.IniSecurityManagerFactory;
+<span class="code-keyword">import</span> org.apache.shiro.mgt.<span class="code-object">SecurityManager</span>;
+<span class="code-keyword">import</span> org.apache.shiro.subject.Subject;
+<span class="code-keyword">import</span> org.apache.shiro.util.Factory;
+<span class="code-keyword">import</span> org.junit.After;
+<span class="code-keyword">import</span> org.junit.BeforeClass;
+<span class="code-keyword">import</span> org.junit.Test;
+
+<span class="code-keyword">public</span> class ExampleShiroIntegrationTest <span class="code-keyword">extends</span> AbstractShiroTest {
+
+    @BeforeClass
+    <span class="code-keyword">public</span> <span class="code-keyword">static</span> void beforeClass() {
+        <span class="code-comment">//0.  Build and set the <span class="code-object">SecurityManager</span> used to build Subject instances used in your tests
+</span>        <span class="code-comment">//    This typically only needs to be done once per class <span class="code-keyword">if</span> your shiro.ini doesn't change,
+</span>        <span class="code-comment">//    otherwise, you'll need to <span class="code-keyword">do</span> <span class="code-keyword">this</span> logic in each test that is different
+</span>        Factory&lt;<span class="code-object">SecurityManager</span>&gt; factory = <span class="code-keyword">new</span> IniSecurityManagerFactory(<span class="code-quote">"classpath:test.shiro.ini"</span>);
+        setSecurityManager(factory.getInstance());
+    }
+
+    @Test
+    <span class="code-keyword">public</span> void testSimple() {
+        <span class="code-comment">//1.  Build the Subject instance <span class="code-keyword">for</span> the test to run:
+</span>        Subject subjectUnderTest = <span class="code-keyword">new</span> Subject.Builder(getSecurityManager()).buildSubject();
+
+        <span class="code-comment">//2. Bind the subject to the current thread:
+</span>        setSubject(subjectUnderTest);
+
+        <span class="code-comment">//perform test logic here.  Any call to 
+</span>        <span class="code-comment">//SecurityUtils.getSubject() directly (or nested in the 
+</span>        <span class="code-comment">//call stack) will work properly.
+</span>    }
+
+    @AfterClass
+    <span class="code-keyword">public</span> void tearDownSubject() {
+        <span class="code-comment">//3. Unbind the subject from the current thread:
+</span>        clearSubject();
+    }
+}
+</pre>
+</div></div>
+
+<p>As you can see, a concrete <tt>SecurityManager</tt> implementation is instantiated and made accessible for the remainder of the test via the <tt>setSecurityManager</tt> method.  Test methods can then use this <tt>SecurityManager</tt> when using the <tt>Subject.Builder</tt> later via the <tt>getSecurityManager()</tt> method.</p>
+
+<p>Also note that the <tt>SecurityManager</tt> instance is set up once in a <tt>@BeforeClass</tt> setup method - a fairly common practice for most test classes.  But if you wanted to, you could create a new <tt>SecurityManager</tt> instance and set it via <tt>setSecurityManager</tt> at any time from any test method - for example, you might reference two different .ini files to build a new <tt>SecurityManager</tt> depending on your test requirements.  </p>
+
+<p>Finally, just as with the Unit Test example, the <tt>AbstractShiroTest</tt> super class will clean up all Shiro artifacts (any remaining <tt>SecurityManager</tt> and <tt>Subject</tt> instance) via its <tt>@AfterClass tearDownShiro()</tt> method to ensure the thread is 'clean' for the next test class to run.</p>
+
+<h2><a name="Testing-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2>
+
+<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time.  If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p>
+
+<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/" rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>

Added: shiro/site/trunk/tools.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/tools.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/tools.html (added)
+++ shiro/site/trunk/tools.html Sat May 11 21:10:40 2013
@@ -0,0 +1 @@
+<p><a href="command-line-hasher.html" title="Command Line Hasher">Command Line Hasher</a></p>
\ No newline at end of file



Mime
View raw message