Google Git
Sign in
apache / shiro-site / 01016f43374d9b054f3ea1e568b015d5d69428f9 / . / src / site / assets / static / 1.2.1 / apidocs / org / apache / shiro / realm / Realm.html
blob: c803123602a084125d21a60d0fd66d963a07b4a3 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (version 1.7.0_21) on Thu May 30 14:51:26 PDT 2013 -->
<meta http-equiv="Content-Type" content="text/html" charset="UTF-8">
<title>Realm (Apache Shiro 1.2.1 API)</title>
<meta name="date" content="2013-05-30">
<link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
</head>
<body>
<script type="text/javascript"><!--
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="Realm (Apache Shiro 1.2.1 API)";
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar_top">
<!-- -->
</a><a href="#skip-navbar_top" title="Skip navigation links"></a><a name="navbar_top_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/Realm.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../org/apache/shiro/realm/CachingRealm.html" title="class in org.apache.shiro.realm"><span class="strong">Prev Class</span></a></li>
<li><a href="../../../../org/apache/shiro/realm/RealmFactory.html" title="interface in org.apache.shiro.realm"><span class="strong">Next Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?org/apache/shiro/realm/Realm.html" target="_top">Frames</a></li>
<li><a href="Realm.html" target="_top">No Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../allclasses-noframe.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_detail">Method</a></li>
</ul>
</div>
<a name="skip-navbar_top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">org.apache.shiro.realm</div>
<h2 title="Interface Realm" class="title">Interface Realm</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<dl>
<dt>All Known Implementing Classes:</dt>
<dd><a href="../../../../org/apache/shiro/realm/ldap/AbstractLdapRealm.html" title="class in org.apache.shiro.realm.ldap">AbstractLdapRealm</a>, <a href="../../../../org/apache/shiro/realm/activedirectory/ActiveDirectoryRealm.html" title="class in org.apache.shiro.realm.activedirectory">ActiveDirectoryRealm</a>, <a href="../../../../org/apache/shiro/realm/AuthenticatingRealm.html" title="class in org.apache.shiro.realm">AuthenticatingRealm</a>, <a href="../../../../org/apache/shiro/realm/AuthorizingRealm.html" title="class in org.apache.shiro.realm">AuthorizingRealm</a>, <a href="../../../../org/apache/shiro/realm/CachingRealm.html" title="class in org.apache.shiro.realm">CachingRealm</a>, <a href="../../../../org/apache/shiro/cas/CasRealm.html" title="class in org.apache.shiro.cas">CasRealm</a>, <a href="../../../../org/apache/shiro/realm/text/IniRealm.html" title="class in org.apache.shiro.realm.text">IniRealm</a>, <a href="../../../../org/apache/shiro/realm/jdbc/JdbcRealm.html" title="class in org.apache.shiro.realm.jdbc">JdbcRealm</a>, <a href="../../../../org/apache/shiro/realm/ldap/JndiLdapRealm.html" title="class in org.apache.shiro.realm.ldap">JndiLdapRealm</a>, <a href="../../../../org/apache/shiro/realm/text/PropertiesRealm.html" title="class in org.apache.shiro.realm.text">PropertiesRealm</a>, <a href="../../../../org/apache/shiro/realm/SimpleAccountRealm.html" title="class in org.apache.shiro.realm">SimpleAccountRealm</a>, <a href="../../../../org/apache/shiro/realm/text/TextConfigurationRealm.html" title="class in org.apache.shiro.realm.text">TextConfigurationRealm</a></dd>
</dl>
<hr>
<br>
<pre>public interface <a href="../../../../src-html/org/apache/shiro/realm/Realm.html#line.63">Realm</a></pre>
<div class="block">A <tt>Realm</tt> is a security component that can access application-specific security entities
such as users, roles, and permissions to determine authentication and authorization operations.
<p><tt>Realm</tt>s usually have a 1-to-1 correspondance with a datasource such as a relational database,
file sysetem, or other similar resource. As such, implementations of this interface use datasource-specific APIs to
determine authorization data (roles, permissions, etc), such as JDBC, File IO, Hibernate or JPA, or any other
Data Access API. They are essentially security-specific
<a href="http://en.wikipedia.org/wiki/Data_Access_Object" target="_blank">DAO</a>s.
<p>Because most of these datasources usually contain Subject (a.k.a. User) information such as usernames and
passwords, a Realm can act as a pluggable authentication module in a
<a href="http://en.wikipedia.org/wiki/Pluggable_Authentication_Modules">PAM</a> configuration. This allows a Realm to
perform <i>both</i> authentication and authorization duties for a single datasource, which caters to the large
majority of applications. If for some reason you don't want your Realm implementation to perform authentication
duties, you should override the <a href="../../../../org/apache/shiro/realm/Realm.html#supports(org.apache.shiro.authc.AuthenticationToken)"><code>supports(org.apache.shiro.authc.AuthenticationToken)</code></a> method to always
return <tt>false</tt>.
<p>Because every application is different, security data such as users and roles can be
represented in any number of ways. Shiro tries to maintain a non-intrusive development philosophy whenever
possible - it does not require you to implement or extend any <tt>User</tt>, <tt>Group</tt> or <tt>Role</tt>
interfaces or classes.
<p>Instead, Shiro allows applications to implement this interface to access environment-specific datasources
and data model objects. The implementation can then be plugged in to the application's Shiro configuration.
This modular technique abstracts away any environment/modeling details and allows Shiro to be deployed in
practically any application environment.
<p>Most users will not implement the <tt>Realm</tt> interface directly, but will extend one of the subclasses,
<a href="../../../../org/apache/shiro/realm/AuthenticatingRealm.html" title="class in org.apache.shiro.realm"><code>AuthenticatingRealm</code></a> or <a href="../../../../org/apache/shiro/realm/AuthorizingRealm.html" title="class in org.apache.shiro.realm"><code>AuthorizingRealm</code></a>, greatly reducing the effort requird
to implement a <tt>Realm</tt> from scratch.</p></div>
<dl><dt><span class="strong">Since:</span></dt>
<dd>0.1</dd>
<dt><span class="strong">See Also:</span></dt><dd><a href="../../../../org/apache/shiro/realm/CachingRealm.html" title="class in org.apache.shiro.realm"><code>CachingRealm</code></a>,
<a href="../../../../org/apache/shiro/realm/AuthenticatingRealm.html" title="class in org.apache.shiro.realm"><code>AuthenticatingRealm</code></a>,
<a href="../../../../org/apache/shiro/realm/AuthorizingRealm.html" title="class in org.apache.shiro.realm"><code>AuthorizingRealm</code></a>,
<a href="../../../../org/apache/shiro/authc/pam/ModularRealmAuthenticator.html" title="class in org.apache.shiro.authc.pam"><code>ModularRealmAuthenticator</code></a></dd></dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method_summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span>Methods</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code><a href="../../../../org/apache/shiro/authc/AuthenticationInfo.html" title="interface in org.apache.shiro.authc">AuthenticationInfo</a></code></td>
<td class="colLast"><code><strong><a href="../../../../org/apache/shiro/realm/Realm.html#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)">getAuthenticationInfo</a></strong>(<a href="../../../../org/apache/shiro/authc/AuthenticationToken.html" title="interface in org.apache.shiro.authc">AuthenticationToken</a>&nbsp;token)</code>
<div class="block">Returns an account's authentication-specific information for the specified <tt>token</tt>,
or <tt>null</tt> if no account could be found based on the <tt>token</tt>.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="http://java.sun.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>
<td class="colLast"><code><strong><a href="../../../../org/apache/shiro/realm/Realm.html#getName()">getName</a></strong>()</code>
<div class="block">Returns the (application-unique) name assigned to this <code>Realm</code>.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><strong><a href="../../../../org/apache/shiro/realm/Realm.html#supports(org.apache.shiro.authc.AuthenticationToken)">supports</a></strong>(<a href="../../../../org/apache/shiro/authc/AuthenticationToken.html" title="interface in org.apache.shiro.authc">AuthenticationToken</a>&nbsp;token)</code>
<div class="block">Returns <tt>true</tt> if this realm wishes to authenticate the Subject represented by the given
<a href="../../../../org/apache/shiro/authc/AuthenticationToken.html" title="interface in org.apache.shiro.authc"><code>AuthenticationToken</code></a> instance, <tt>false</tt> otherwise.</div>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method_detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="getName()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>getName</h4>
<pre><a href="http://java.sun.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&nbsp;<a href="../../../../src-html/org/apache/shiro/realm/Realm.html#line.71">getName</a>()</pre>
<div class="block">Returns the (application-unique) name assigned to this <code>Realm</code>. All realms configured for a single
application must have a unique name.</div>
<dl><dt><span class="strong">Returns:</span></dt><dd>the (application-unique) name assigned to this <code>Realm</code>.</dd></dl>
</li>
</ul>
<a name="supports(org.apache.shiro.authc.AuthenticationToken)">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>supports</h4>
<pre>boolean&nbsp;<a href="../../../../src-html/org/apache/shiro/realm/Realm.html#line.85">supports</a>(<a href="../../../../org/apache/shiro/authc/AuthenticationToken.html" title="interface in org.apache.shiro.authc">AuthenticationToken</a>&nbsp;token)</pre>
<div class="block">Returns <tt>true</tt> if this realm wishes to authenticate the Subject represented by the given
<a href="../../../../org/apache/shiro/authc/AuthenticationToken.html" title="interface in org.apache.shiro.authc"><code>AuthenticationToken</code></a> instance, <tt>false</tt> otherwise.
<p>If this method returns <tt>false</tt>, it will not be called to authenticate the Subject represented by
the token - more specifically, a <tt>false</tt> return value means this Realm instance's
<a href="../../../../org/apache/shiro/realm/Realm.html#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)"><code>getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)</code></a> method will not be invoked for that token.</div>
<dl><dt><span class="strong">Parameters:</span></dt><dd><code>token</code> - the AuthenticationToken submitted for the authentication attempt</dd>
<dt><span class="strong">Returns:</span></dt><dd><tt>true</tt> if this realm can/will authenticate Subjects represented by specified token,
<tt>false</tt> otherwise.</dd></dl>
</li>
</ul>
<a name="getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>getAuthenticationInfo</h4>
<pre><a href="../../../../org/apache/shiro/authc/AuthenticationInfo.html" title="interface in org.apache.shiro.authc">AuthenticationInfo</a>&nbsp;<a href="../../../../src-html/org/apache/shiro/realm/Realm.html#line.103">getAuthenticationInfo</a>(<a href="../../../../org/apache/shiro/authc/AuthenticationToken.html" title="interface in org.apache.shiro.authc">AuthenticationToken</a>&nbsp;token)
throws <a href="../../../../org/apache/shiro/authc/AuthenticationException.html" title="class in org.apache.shiro.authc">AuthenticationException</a></pre>
<div class="block">Returns an account's authentication-specific information for the specified <tt>token</tt>,
or <tt>null</tt> if no account could be found based on the <tt>token</tt>.
<p>This method effectively represents a login attempt for the corresponding user with the underlying EIS datasource.
Most implementations merely just need to lookup and return the account data only (as the method name implies)
and let Shiro do the rest, but implementations may of course perform eis specific login operations if so
desired.</div>
<dl><dt><span class="strong">Parameters:</span></dt><dd><code>token</code> - the application-specific representation of an account principal and credentials.</dd>
<dt><span class="strong">Returns:</span></dt><dd>the authentication information for the account associated with the specified <tt>token</tt>,
or <tt>null</tt> if no account could be found.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="../../../../org/apache/shiro/authc/AuthenticationException.html" title="class in org.apache.shiro.authc">AuthenticationException</a></code> - if there is an error obtaining or constructing an AuthenticationInfo object based on the
specified <tt>token</tt> or implementation-specifc login behavior fails.</dd></dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar_bottom">
<!-- -->
</a><a href="#skip-navbar_bottom" title="Skip navigation links"></a><a name="navbar_bottom_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/Realm.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../org/apache/shiro/realm/CachingRealm.html" title="class in org.apache.shiro.realm"><span class="strong">Prev Class</span></a></li>
<li><a href="../../../../org/apache/shiro/realm/RealmFactory.html" title="interface in org.apache.shiro.realm"><span class="strong">Next Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?org/apache/shiro/realm/Realm.html" target="_top">Frames</a></li>
<li><a href="Realm.html" target="_top">No Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../allclasses-noframe.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_detail">Method</a></li>
</ul>
</div>
<a name="skip-navbar_bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small>Copyright &#169; 2004-2013 <a href="http://www.apache.org/">The Apache Software Foundation</a>. All Rights Reserved.</small></p>
</body>
</html>