Modified: shiro/site/publish/terminology.html URL: http://svn.apache.org/viewvc/shiro/site/publish/terminology.html?rev=1766414&r1=1766413&r2=1766414&view=diff ============================================================================== --- shiro/site/publish/terminology.html (original) +++ shiro/site/publish/terminology.html Mon Oct 24 14:33:52 2016 @@ -78,90 +78,81 @@ <div id="content"> - <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 > 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> - + <a name="Terminology-ApacheShiroTerminology"></a> +<h1><a href="#apache-shiro-terminology" name="apache-shiro-terminology">Apache Shiro Terminology</a></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> +<a name="Terminology-authentication"></a> +<ul> + <li><strong>Authentication</strong><br/>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.</li> +</ul> +<a name="Terminology-authorization"></a> +<ul> + <li><strong>Authorization</strong><br/>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.</li> +</ul> +<a name="Terminology-cipher"></a> +<ul> + <li><strong>Cipher</strong><br/>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. + <p>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.</p> + </li> +</ul> +<a name="Terminology-credential"></a> +<ul> + <li><strong>Credential</strong><br/>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. + <p>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 > password).</p> + </li> +</ul> +<a name="Terminology-cryptography"></a> +<ul> + <li><strong>Cryptography</strong><br/>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.</li> +</ul> +<a name="Terminology-hash"></a> +<ul> + <li><strong>Hash</strong><br/>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.</li> +</ul> +<a name="Terminology-permission"></a> +<ul> + <li><strong>Permission</strong><br/>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. + <p>Some examples of permissions:</p> + <ul> + <li>Open a file</li> + <li>View the ‘/user/list’ web page</li> + <li>Print documents</li> + <li>Delete the ‘jsmith’ user</li> + </ul> + </li> +</ul> +<a name="Terminology-principal"></a> +<ul> + <li><strong>Principal</strong><br/>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. + <p>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.</p> + </li> +</ul> +<a name="Terminology-realm"></a> +<ul> + <li><strong>Realm</strong><br/>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. + <p>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.</p> + </li> +</ul> +<a name="Terminology-role"></a> +<ul> + <li><strong>Role</strong><br/>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. + <p>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.</p> + </li> +</ul> +<a name="Terminology-session"></a> +<ul> + <li><strong>Session</strong><br/>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. + <p>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.</p> + </li> +</ul> +<a name="Terminology-subject"></a> +<ul> + <li><strong>Subject</strong><br/>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.</li> +</ul> +<a name="Terminology-Lendahandwithdocumentation"></a> +<h3><a href="#lend-a-hand-with-documentation" name="lend-a-hand-with-documentation">Lend a hand with documentation</a></h3> +<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> </div>
Modified: shiro/site/publish/testing.html URL: http://svn.apache.org/viewvc/shiro/site/publish/testing.html?rev=1766414&r1=1766413&r2=1766414&view=diff ============================================================================== --- shiro/site/publish/testing.html (original) +++ shiro/site/publish/testing.html Mon Oct 24 14:33:52 2016 @@ -78,48 +78,42 @@ <div id="content"> - <h1><a name="Testing-TestingwithApacheShiro"></a>Testing with Apache Shiro</h1> - + <a name="Testing-TestingwithApacheShiro"></a> +<h1><a href="#testing-with-apache-shiro" name="testing-with-apache-shiro">Testing with Apache Shiro</a></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> - +<a name="Testing-Whattoknowfortests"></a> +<h2><a href="#what-to-know-for-tests" name="what-to-know-for-tests">What to know for tests</a></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; +<ol> + <li>A <code>Subject</code> instance must be created</li> + <li>The <code>Subject</code> 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 <code>Throwable</code>), the <code>Subject</code> 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 href="http://shiro.apache.org/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> +<a name="Testing-TestSetup"></a> +<h2><a href="#test-setup" name="test-setup">Test Setup</a></h2> +<p>So we know after creating a <code>Subject</code> 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> +<a name="Testing-AbstractShiroTest"></a> +<h3><a href="#abstractshirotest" name="abstractshirotest">AbstractShiroTest</a></h3> +<pre><code class="java">import org.apache.shiro.SecurityUtils; +import org.apache.shiro.UnavailableSecurityManagerException; +import org.apache.shiro.mgt.SecurityManager; +import org.apache.shiro.subject.Subject; +import org.apache.shiro.subject.support.SubjectThreadState; +import org.apache.shiro.util.LifecycleUtils; +import org.apache.shiro.util.ThreadState; +import org.junit.AfterClass; /** - * Abstract test <span class="code-keyword">case</span> enabling Shiro in test environments. + * Abstract test case enabling Shiro in test environments. */ -<span class="code-keyword">public</span> <span class="code-keyword">abstract</span> class AbstractShiroTest { +public abstract class AbstractShiroTest { - <span class="code-keyword">private</span> <span class="code-keyword">static</span> ThreadState subjectThreadState; + private static ThreadState subjectThreadState; - <span class="code-keyword">public</span> AbstractShiroTest() { + public AbstractShiroTest() { } /** @@ -127,60 +121,58 @@ * * @param subject the Subject instance */ - <span class="code-keyword">protected</span> void setSubject(Subject subject) { + protected 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(); + protected Subject getSubject() { + return 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); + protected ThreadState createThreadState(Subject subject) { + return new 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. + * Clears Shiro's thread state, ensuring the thread remains clean for future test execution. */ - <span class="code-keyword">protected</span> void clearSubject() { + protected 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>) { + private static void doClearSubject() { + if (subjectThreadState != null) { subjectThreadState.clear(); - subjectThreadState = <span class="code-keyword">null</span>; + subjectThreadState = null; } } - <span class="code-keyword">protected</span> <span class="code-keyword">static</span> void setSecurityManager(<span class="code-object">SecurityManager</span> securityManager) { + protected static void setSecurityManager(SecurityManager 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(); + protected static SecurityManager getSecurityManager() { + return SecurityUtils.getSecurityManager(); } @AfterClass - <span class="code-keyword">public</span> <span class="code-keyword">static</span> void tearDownShiro() { + public static void tearDownShiro() { doClearSubject(); - <span class="code-keyword">try</span> { - <span class="code-object">SecurityManager</span> securityManager = getSecurityManager(); + try { + SecurityManager 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>); + } catch (UnavailableSecurityManagerException e) { + //we don't care about this when cleaning up the test environment + //(for example, maybe the subclass is a unit test and it didn't + // need a SecurityManager instance because it was using only + // mock Subject instances) + } + setSecurityManager(null); } } -</pre> -</div></div> - +</code></pre> <div class="panelMacro"> <table class="noteMacro"> <colgroup span="1"> @@ -196,149 +188,123 @@ <td colspan="1" rowspan="1"> <b>Testing & 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> + The code in the <code>AbstractShiroTest</code> class uses Shiro's <code>ThreadState</code> 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 `Subject.associateWith` and the `Subject.execute` methods. These methods are covered in the reference on <a href="subject.html#Subject-ThreadAssociation">Subject thread association</a>).</p> </td> </tr> </tbody> </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://site.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> - +<a name="Testing-UnitTesting"></a> +<h2><a href="#unit-testing" name="unit-testing">Unit Testing</a></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> +<a name="Testing-ExampleShiroUnitTest"></a> +<h3><a href="#exampleshirounittest" name="exampleshirounittest">ExampleShiroUnitTest</a></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 <code>Subject</code> interface and have it reflect whatever conditions you want your code under test to react to. We can leverage modern mock frameworks like <a href="http://easymock.org/";>EasyMock</a> and <a href="http://site.mockito.org";>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; +<pre><code class="java">import org.apache.shiro.subject.Subject; +import org.junit.After; +import org.junit.Test; -<span class="code-keyword">import</span> <span class="code-keyword">static</span> org.easymock.EasyMock.*; +import static 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. + * Simple example test class showing how one may perform unit tests for + * code that requires Shiro APIs. */ -<span class="code-keyword">public</span> class ExampleShiroUnitTest <span class="code-keyword">extends</span> AbstractShiroTest { +public class ExampleShiroUnitTest extends AbstractShiroTest { @Test - <span class="code-keyword">public</span> void testSimple() { + public 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> } + //1. Create a mock authenticated Subject instance for the test to run: + Subject subjectUnderTest = createNiceMock(Subject.class); + expect(subjectUnderTest.isAuthenticated()).andReturn(true); + + //2. Bind the subject to the current thread: + setSubject(subjectUnderTest); + + //perform test logic here. Any call to + //SecurityUtils.getSubject() directly (or nested in the + //call stack) will work properly. + } @After - <span class="code-keyword">public</span> void tearDownSubject() { - <span class="code-comment">//3. Unbind the subject from the current thread: -</span> clearSubject(); + public void tearDownSubject() { + //3. Unbind the subject from the current thread: + 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> - +</code></pre> +<p>As you can see, we’re not setting up a Shiro <code>SecurityManager</code> instance or configuring a <code>Realm</code> or anything like that. We’re simply creating a mock <code>Subject</code> instance and binding it to the thread via the <code>setSubject</code> method call. This will ensure that any calls in our test code or in the code we’re testing to <code>SecurityUtils.getSubject()</code> will work correctly.</p> +<p>Note that the <code>setSubject</code> method implementation will bind your mock Subject to the thread and it will remain there until you call <code>setSubject</code> with a different <code>Subject</code> instance or until you explicitly clear it from the thread via the <code>clearSubject()</code> 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> +<a name="Testing-tearDownSubject%28%29"></a> +<h4>tearDownSubject()</h4> +<p>The <code>tearDownSubject()</code> 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 <code>Subject</code> instance and set it (via <code>setSubject</code>) for every test that executes.</p> +<p>This is not strictly necessary however. For example, you could just bind a new Subject instance (via <code>setSujbect</code>) at the beginning of every test, say, in an <code>@Before</code>-annotated method. But if you’re going to do that, you might as well have the <code>@After tearDownSubject()</code> 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 <code>AbstractShiroTest</code> super class will however unbind the Subject from the thread after all tests because of the <code>@AfterClass</code> annotation in its <code>tearDownShiro()</code> method.</p> +<a name="Testing-IntegrationTesting"></a> +<h2><a href="#integration-testing" name="integration-testing">Integration Testing</a></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 <code>SecurityManager</code> 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 <code>SecurityManager</code> instance for every test class you execute. When your integration tests run, they will be using ‘real’ <code>SecurityManager</code> and <code>Subject</code> instances like your application will be using at runtime.</p> +<a name="Testing-ExampleShiroIntegrationTest"></a> +<h3><a href="#exampleshirointegrationtest" name="exampleshirointegrationtest">ExampleShiroIntegrationTest</a></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> - - +<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 <code>Subject.Builder</code> 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> +<pre><code class="java">import org.apache.shiro.config.IniSecurityManagerFactory; +import org.apache.shiro.mgt.SecurityManager; +import org.apache.shiro.subject.Subject; +import org.apache.shiro.util.Factory; +import org.junit.After; +import org.junit.BeforeClass; +import org.junit.Test; -<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 { +public class ExampleShiroIntegrationTest extends 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<<span class="code-object">SecurityManager</span>> factory = <span class="code-keyword">new</span> IniSecurityManagerFactory(<span class="code-quote">"classpath:test.shiro.ini"</span>); + public static void beforeClass() { + //0. Build and set the SecurityManager used to build Subject instances used in your tests + // This typically only needs to be done once per class if your shiro.ini doesn't change, + // otherwise, you'll need to do this logic in each test that is different + Factory<SecurityManager> factory = new IniSecurityManagerFactory("classpath:test.shiro.ini"); 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> } + public void testSimple() { + //1. Build the Subject instance for the test to run: + Subject subjectUnderTest = new Subject.Builder(getSecurityManager()).buildSubject(); + + //2. Bind the subject to the current thread: + setSubject(subjectUnderTest); + + //perform test logic here. Any call to + //SecurityUtils.getSubject() directly (or nested in the + //call stack) will work properly. + } @AfterClass - <span class="code-keyword">public</span> void tearDownSubject() { - <span class="code-comment">//3. Unbind the subject from the current thread: -</span> clearSubject(); + public void tearDownSubject() { + //3. Unbind the subject from the current thread: + 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> - +</code></pre> +<p>As you can see, a concrete <code>SecurityManager</code> implementation is instantiated and made accessible for the remainder of the test via the <code>setSecurityManager</code> method. Test methods can then use this <code>SecurityManager</code> when using the <code>Subject.Builder</code> later via the <code>getSecurityManager()</code> method.</p> +<p>Also note that the <code>SecurityManager</code> instance is set up once in a <code>@BeforeClass</code> setup method - a fairly common practice for most test classes. But if you wanted to, you could create a new <code>SecurityManager</code> instance and set it via <code>setSecurityManager</code> at any time from any test method - for example, you might reference two different .ini files to build a new <code>SecurityManager</code> depending on your test requirements.</p> +<p>Finally, just as with the Unit Test example, the <code>AbstractShiroTest</code> super class will clean up all Shiro artifacts (any remaining <code>SecurityManager</code> and <code>Subject</code> instance) via its <code>@AfterClass tearDownShiro()</code> method to ensure the thread is ‘clean’ for the next test class to run.</p> +<a name="Testing-Lendahandwithdocumentation"></a> +<h2><a href="#lend-a-hand-with-documentation" name="lend-a-hand-with-documentation">Lend a hand with documentation</a></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 href="http://shiro-user.582556.n2.nabble.com/";>User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p> </div> Modified: shiro/site/publish/tools.html URL: http://svn.apache.org/viewvc/shiro/site/publish/tools.html?rev=1766414&r1=1766413&r2=1766414&view=diff ============================================================================== --- shiro/site/publish/tools.html (original) +++ shiro/site/publish/tools.html Mon Oct 24 14:33:52 2016 @@ -78,7 +78,7 @@ <div id="content"> - <p><a href="command-line-hasher.html" title="Command Line Hasher">Command Line Hasher</a></p> + <p><a href="command-line-hasher.html">Command Line Hasher</a></p> </div>
