Cwikius-Spring/spring-security
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-security.git synced 2025-07-01 08:12:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Minor docbook updates and fixes to class/interface index generation script and xsl

Browse Source
This commit is contained in:
Luke Taylor 2009-11-27 19:04:35 +00:00
parent 6688d41705
commit c9ab463af7
5 changed files with 117 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/manual/src/docbook/class-index-html.xsl
View File

@ -1,27 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:variable name="src-xref-base">http://static.springframework.org/spring-security/site/xref/</xsl:variable> <!-- Run with xsltproc class-index-html.xsl classindex.xml > class-index.html -->
<xsl:variable name="ref-man-base">http://static.springframework.org/spring-security/site/reference/html/</xsl:variable>
<xsl:variable name="src-xref-base">http://static.springsource.org/spring-security/site/docs/3.0.x/apidocs/</xsl:variable>
<xsl:variable name="ref-man-base">http://static.springsource.org/spring-security/site/docs/3.0.x/reference/</xsl:variable>
<xsl:template match="index"> <xsl:template match="index">
<html> <html>
<head>
<title>Spring Security Class and Interface Index</title>
</head>
<body> <body>
<h1>Class and Interface Index</h1> <h2>Class and Interface Index</h2>
<p>An list of classes and interfaces used in Spring Security with links to the sections in the Spring Security manual which
refer to them.</p>
<div id="classindex">
<xsl:apply-templates /> <xsl:apply-templates />
</div>
</body> </body>
</html> </html>
</xsl:template> </xsl:template>
<xsl:template match="class"> <xsl:template match="class">
<h3><xsl:value-of select="@name"/></h3> <div class="index-class">
<xsl:if test="@src-xref"> <xsl:choose>
<p><xsl:element name="a"><xsl:attribute name="href"><xsl:value-of select="concat($src-xref-base, @src-xref)"/></xsl:attribute>Source</xsl:element></p> <xsl:when test="@src-xref">
</xsl:if> <h4><xsl:element name="a"><xsl:attribute name="href"><xsl:value-of select="concat($src-xref-base, @src-xref)"/></xsl:attribute><xsl:value-of select="@name"/></xsl:element></h4>
</xsl:when>
<xsl:otherwise>
<h4><span class="classname"><xsl:value-of select="@name"/></span></h4>
</xsl:otherwise>
</xsl:choose>
<table>
<xsl:for-each select="link"> <xsl:for-each select="link">
<p><xsl:element name="a"><xsl:attribute name="href"><xsl:value-of select="concat($ref-man-base, @href)"/></xsl:attribute><xsl:value-of select="@title"/></xsl:element></p> <tr><td><xsl:element name="a"><xsl:attribute name="href"><xsl:value-of select="concat($ref-man-base, @href)"/></xsl:attribute><xsl:value-of select="@title"/></xsl:element></td>
</tr>
</xsl:for-each> </xsl:for-each>
</table>
</div>
</xsl:template> </xsl:template>
</xsl:stylesheet> </xsl:stylesheet>

38
docs/manual/classindex.pl → docs/manual/src/docbook/classindex.pl
View File

@ -1,9 +1,22 @@
#! /usr/bin/perl #! /usr/bin/perl
# Intended to generate an index of classnames to references in the manual (using the interfacename and classname elements).
#
# Builds an index of classnames to Javadoc (or src xref) links, from the allclasses-frame.html file.
# Processes the ref manual docbook files, building an index of classname to section ids where the class is referenced
#
#
# $Id$
use strict; use strict;
# Get list of links to class src packages from Javadoc # Get list of links to class src packages from Javadoc
#system("curl http://static.springsource.org/spring-security/site/docs/3.0.x/apidocs/allclasses-frame.html > allclasses-frame.html"); #system("curl http://static.springsource.org/spring-security/site/docs/3.0.x/apidocs/allclasses-frame.html > allclasses-frame.html");
# Manual front page gives us section numbers
#system("curl http://static.springsource.org/spring-security/site/docs/3.0.x/reference/springsecurity.html > springsecurity.html");
my $index_page = `cat springsecurity.html`;
my @all_classes = `cat allclasses-frame.html`; my @all_classes = `cat allclasses-frame.html`;
$#all_classes > 0 || die "No lines in Javadoc"; $#all_classes > 0 || die "No lines in Javadoc";
@ -16,12 +29,17 @@ $#all_classes > 0 || die "No lines in Javadoc";
my %classnames_to_src; my %classnames_to_src;
while ($_ = pop @all_classes) { while ($_ = pop @all_classes) {
next unless $_ =~ /<A HREF="(.*)" title.*>(([a-zA-Z0-9_]+?))<\/A>/; chomp;
print "Adding class $1, $2\n"; # Get rid of the italic tags round interface names
$_ =~ s/<I>//;
$_ =~ s/<\/I>//;
next unless $_ =~ /<A HREF="(.*)" title=.*>(([a-zA-Z0-9_]+?))<\/A>.*/;
# print "Adding class $1, $2\n";
$classnames_to_src{$2} = $1; $classnames_to_src{$2} = $1;
} }
#my @docbook = glob("*.xml"); #my @docbook = glob("*.xml");
# The list of docbook files xincluded in the manual
my @docbook; my @docbook;
# Read the includes rather than using globbing to get the ordering right for the index. # Read the includes rather than using globbing to get the ordering right for the index.
@ -34,12 +52,11 @@ while(<MAINDOC>) {
# Hash of xml:id (i.e. anchor) to filename.html#anchor # Hash of xml:id (i.e. anchor) to filename.html#anchor
my %id_to_html; my %id_to_html;
my %class_index;
# Build map of html pages links # Build map of html pages links
while (my $file = pop @docbook) { while (my $file = pop @docbook) {
open FILE, $file or die "$!"; open FILE, $file or die "$!";
print "\nProcessing: $file\n\n"; # print "\nProcessing: $file\n\n";
my $file_id; my $file_id;
while(<FILE>) { while(<FILE>) {
if (/.* xml:id="([a-z0-9-]+?)"/) { if (/.* xml:id="([a-z0-9-]+?)"/) {
@ -48,11 +65,11 @@ while (my $file = pop @docbook) {
} }
} }
$id_to_html{$file_id} = "$file_id.html#$file_id"; $id_to_html{$file_id} = "$file_id.html";
while (<FILE>) { while (<FILE>) {
next unless /.* xml:id="([a-z0-9-]+?)"/; next unless /.* xml:id="([a-z0-9-]+?)"/;
print "$1\n"; # print "$1\n";
$id_to_html{$1} = "$file_id.html#$1"; $id_to_html{$1} = "$file_id.html#$1";
} }
close FILE; close FILE;
@ -84,11 +101,16 @@ foreach my $class (sort keys %classnames_to_ids) {
} }
print INDEX ">\n"; print INDEX ">\n";
foreach my $id (@{$classnames_to_ids{$class}}) { foreach my $id (@{$classnames_to_ids{$class}}) {
print INDEX " <link href='$id_to_html{$id}' title='$id_to_title{$id}'/>\n"; my $href = $id_to_html{$id};
$index_page =~ /$href">([AB0-9\.]* )/;
my $section = $1 ? "$1" : "";
print "$id $href $section\n";
my $title = $id_to_title{$id};
# print "$section$title\n";
print INDEX " <link href='$href' title='$section$title'/>\n";
} }
print INDEX "</class>\n" print INDEX "</class>\n"
} }
print INDEX "</index>\n"; print INDEX "</index>\n";
close INDEX; close INDEX;

56
docs/manual/src/docbook/el-access.xml
View File

@ -15,7 +15,7 @@
Security uses specific classes for web and method security as the root object, in order Security uses specific classes for web and method security as the root object, in order
to provide built-in expressions and access to values such as the current to provide built-in expressions and access to values such as the current
principal.</para> principal.</para>
<section> <section xml:id="el-common-built-in">
<title>Common Built-In Expressions</title> <title>Common Built-In Expressions</title>
<para>The base class for expression root objects is <para>The base class for expression root objects is
<classname>SecurityExpressionRoot</classname>. This provides some common <classname>SecurityExpressionRoot</classname>. This provides some common
@ -121,7 +121,7 @@
<para>Method security is a bit more complicated than a simple allow or deny rule. Spring <para>Method security is a bit more complicated than a simple allow or deny rule. Spring
Security 3.0 introduced some new annotations in order to allow comprehensive support for Security 3.0 introduced some new annotations in order to allow comprehensive support for
the use of expressions.</para> the use of expressions.</para>
<section> <section xml:id="el-pre-post-annotations">
<title><literal>@Pre</literal> and <literal>@Post</literal> Annotations</title> <title><literal>@Pre</literal> and <literal>@Post</literal> Annotations</title>
<para>There are four annotations which support expression attributes to allow pre and <para>There are four annotations which support expression attributes to allow pre and
post-invocation authorization checks and also to support filtering of submitted post-invocation authorization checks and also to support filtering of submitted
@ -147,8 +147,9 @@
we're actually using a method argument as part of the expression to decide we're actually using a method argument as part of the expression to decide
whether the current user has the <quote>admin</quote>permission for the given whether the current user has the <quote>admin</quote>permission for the given
contact. The built-in <literal>hasPermission()</literal> expression is linked contact. The built-in <literal>hasPermission()</literal> expression is linked
into the Spring Security ACL module through the application context. You can into the Spring Security ACL module through the application context, as we'll
access any of the method arguments by name as expression variables, provided <link xlink:href="#el-permission-evaluator">see
below</link>. You can access any of the method arguments by name as expression variables, provided
your code has debug information compiled in. Any Spring-EL functionality is your code has debug information compiled in. Any Spring-EL functionality is
available within the expression, so you can also access properties on the available within the expression, so you can also access properties on the
arguments. For example, if you wanted a particular method to only allow access arguments. For example, if you wanted a particular method to only allow access
@ -189,5 +190,52 @@
the entries then this is likely to be inefficient.</para> the entries then this is likely to be inefficient.</para>
</section> </section>
</section> </section>
<section xml:id="el-method-built-in">
<title>Built-In Expressions</title>
<para>There are some built-in expressions which are specific to method security, which
we have already seen in use above. The <literal>filterTarget</literal> and
<literal>returnValue</literal> values are simple enough, but the use of the
<literal>hasPermission()</literal> expression warrants a closer look.</para>
<section xml:id="el-permission-evaluator">
<title>The <interfacename>PermissionEvaluator</interfacename> interface</title>
<para><literal>hasPermission()</literal> expressions are delegated to an instance of
<interfacename>PermissionEvaluator</interfacename>. It is intended to bridge
between the expression system and Spring Security's ACL system, allowing you to
specify authorization constraints on domain objects, based on abstract
permissions. It has no explicit dependencies on the ACL module, so you could
swap that out for an alternative implementation if required. The interface has
two methods:
<programlisting language="java"> boolean hasPermission(Authentication authentication, Object targetDomainObject, Object permission);
boolean hasPermission(Authentication authentication, Serializable targetId, String targetType, Object permission);</programlisting>which
map directly to the available versions of the expression, with the exception
that the first argument (the <interfacename>Authentication</interfacename>
object) is not supplied. The first is used in situations where the domain
object, to which access is being controlled, is already loaded. Then expression
will return true if the current user has the given permission for that object.
The second version is used in cases where the object is not loaded, but its
identifier is known. An abstract <quote>type</quote> specifier for the domain
object is also required, allowing the correct ACL permissions to be loaded. This
has traditionally been the Java class of the object, but does not have to be as
long as it is consistent with how the permissions are loaded.</para>
<para>To use <literal>hasPermission()</literal> expressions, you have to explicitly
configure a <interfacename>PermissionEvaluator</interfacename> in your
application context. This would look something like
this:<programlisting language="xml"> <![CDATA[ <security:global-method-security pre-post-annotations="enabled">
<security:expression-handler ref="expressionHandler"/>
</security:global-method-security>
<bean id="expressionHandler"
class="org.springframework.security.access.expression.method.DefaultMethodSecurityExpressionHandler">
<property name="permissionEvaluator" ref="myPermissionEvaluator"/>
</bean>]]></programlisting>Where
<literal>myPermissionEvaluator</literal> is the bean which implements
<interfacename>PermissionEvaluator</interfacename>. Usually this will be the
implementation from the ACL module which is called
<classname>AclPermissionEvaluator</classname>. See the
<quote>Contacts</quote> sample application configuration for more
details.</para>
</section>
</section>
</section> </section>
</chapter> </chapter>

15
docs/manual/src/docbook/namespace-config.xml
View File

@ -16,12 +16,12 @@
complexity from the user. A simple element may conceal the fact that multiple beans and complexity from the user. A simple element may conceal the fact that multiple beans and
processing steps are being added to the application context. For example, adding the following processing steps are being added to the application context. For example, adding the following
element from the security namespace to an application context will start up an embedded LDAP element from the security namespace to an application context will start up an embedded LDAP
server for testing use within the application: <programlisting><![CDATA[ server for testing use within the application: <programlisting language="xml"><![CDATA[
<security:ldap-server /> <security:ldap-server />
]]></programlisting> This is much simpler than wiring up the equivalent Apache Directory Server ]]></programlisting> This is much simpler than wiring up the equivalent Apache Directory Server
beans. The most common alternative configuration requirements are supported by attributes on beans. The most common alternative configuration requirements are supported by attributes on
the <literal>ldap-server</literal> element and the user is isolated from worrying about which the <literal>ldap-server</literal> element and the user is isolated from worrying about which
beans they need create and what the bean property names are. <footnote><para>You can find out beans they need to create and what the bean property names are. <footnote><para>You can find out
more about the use of the <literal>ldap-server</literal> element in the chapter on <link more about the use of the <literal>ldap-server</literal> element in the chapter on <link
xlink:href="#ldap">LDAP</link>.</para></footnote>. Use of a good XML editor while xlink:href="#ldap">LDAP</link>.</para></footnote>. Use of a good XML editor while
editing the application context file should provide information on the attributes and elements editing the application context file should provide information on the attributes and elements
@ -380,11 +380,11 @@
<title>Detecting Timeouts</title> <title>Detecting Timeouts</title>
<para> You can configure Spring Security to detect the submission of an invalid session ID <para> You can configure Spring Security to detect the submission of an invalid session ID
and redirect the user to an appropriate URL. This is achieved through the and redirect the user to an appropriate URL. This is achieved through the
<literal>session-management</literal> element:<![CDATA[ <literal>session-management</literal> element: <programlisting language="xml"><![CDATA[
<http> <http>
... ...
<session-management invalid-session-url="/sessionTimeout.htm" /> <session-management invalid-session-url="/sessionTimeout.htm" />
</http>]]></para> </http>]]></programlisting></para>
</section> </section>
<section xml:id="ns-concurrent-sessions"> <section xml:id="ns-concurrent-sessions">
<title>Concurrent Session Control</title> <title>Concurrent Session Control</title>
@ -392,13 +392,13 @@
application, Spring Security supports this out of the box with the following simple application, Spring Security supports this out of the box with the following simple
additions. First you need to add the following listener to your additions. First you need to add the following listener to your
<filename>web.xml</filename> file to keep Spring Security updated about session <filename>web.xml</filename> file to keep Spring Security updated about session
lifecycle events: <![CDATA[ lifecycle events: <programlisting language="xml"><![CDATA[
<listener> <listener>
<listener-class> <listener-class>
org.springframework.security.web.session.HttpSessionEventPublisher org.springframework.security.web.session.HttpSessionEventPublisher
</listener-class> </listener-class>
</listener> </listener>
]]> Then add the following lines to your application context: <programlisting language="xml"><![CDATA[ ]]></programlisting> Then add the following lines to your application context: <programlisting language="xml"><![CDATA[
<http> <http>
... ...
<session-management> <session-management>
@ -457,7 +457,7 @@
</http> </http>
]]></programlisting> You should then register yourself with an OpenID provider (such as ]]></programlisting> You should then register yourself with an OpenID provider (such as
myopenid.com), and add the user information to your in-memory myopenid.com), and add the user information to your in-memory
<literal>&lt;user-service&gt;</literal>: <programlisting><![CDATA[ <literal>&lt;user-service&gt;</literal>: <programlisting language="xml"><![CDATA[
<user name="http://jimi.hendrix.myopenid.com/" password="notused" <user name="http://jimi.hendrix.myopenid.com/" password="notused"
authorities="ROLE_USER" /> authorities="ROLE_USER" />
]]></programlisting> You should be able to login using the <literal>myopenid.com</literal> site to ]]></programlisting> You should be able to login using the <literal>myopenid.com</literal> site to
@ -689,7 +689,6 @@
</authentication-manager> </authentication-manager>
<bean id="casAuthenticationProvider" <bean id="casAuthenticationProvider"
class="org.springframework.security.cas.authentication.CasAuthenticationProvider"> class="org.springframework.security.cas.authentication.CasAuthenticationProvider">
<security:custom-authentication-provider />
... ...
</bean> </bean>
]]></programlisting></para> ]]></programlisting></para>

4
docs/manual/src/docbook/technical-overview.xml
View File

@ -284,7 +284,7 @@ Successfully authenticated. Security context contains: \
here to show that the question of what actually constitutes authentication in Spring here to show that the question of what actually constitutes authentication in Spring
Security has quite a simple answer. A user is authenticated when the Security has quite a simple answer. A user is authenticated when the
<classname>SecurityContextHolder</classname> contains a fully populated <classname>SecurityContextHolder</classname> contains a fully populated
<interfacename>Authentiation</interfacename> object.</para> <interfacename>Authentication</interfacename> object.</para>
<section> <section>
<title>Setting the SecurityContextHolder Contents Directly</title> <title>Setting the SecurityContextHolder Contents Directly</title>
<para>In fact, Spring Security doesn't mind how you put the <para>In fact, Spring Security doesn't mind how you put the
@ -424,7 +424,7 @@ Successfully authenticated. Security context contains: \
<section xml:id="tech-intro-access-control"> <section xml:id="tech-intro-access-control">
<title>Access-Control (Authorization) in Spring Security</title> <title>Access-Control (Authorization) in Spring Security</title>
<para> The main interface resposible for making access-control decisions in Spring Security is <para> The main interface resposible for making access-control decisions in Spring Security is
the <interfacename>AccessDecisionMananger</interfacename>. It has a the <interfacename>AccessDecisionManager</interfacename>. It has a
<methodname>decide</methodname> method which takes an <methodname>decide</methodname> method which takes an
<interfacename>Authentication</interfacename> object representing the principal requesting <interfacename>Authentication</interfacename> object representing the principal requesting
access, a <quote>secure object</quote> (see below) and a list of security metadata attributes access, a <quote>secure object</quote> (see below) and a list of security metadata attributes