From c9ab463af79b80525aee82cc09529848b0b1640b Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Fri, 27 Nov 2009 19:04:35 +0000 Subject: [PATCH] Minor docbook updates and fixes to class/interface index generation script and xsl --- docs/manual/src/docbook/class-index-html.xsl | 36 ++++++++---- docs/manual/{ => src/docbook}/classindex.pl | 38 ++++++++++--- docs/manual/src/docbook/el-access.xml | 56 +++++++++++++++++-- docs/manual/src/docbook/namespace-config.xml | 15 +++-- .../manual/src/docbook/technical-overview.xml | 4 +- 5 files changed, 117 insertions(+), 32 deletions(-) rename docs/manual/{ => src/docbook}/classindex.pl (66%) diff --git a/docs/manual/src/docbook/class-index-html.xsl b/docs/manual/src/docbook/class-index-html.xsl index 92d17342b9..d8ccc27c7f 100644 --- a/docs/manual/src/docbook/class-index-html.xsl +++ b/docs/manual/src/docbook/class-index-html.xsl @@ -1,27 +1,43 @@ - http://static.springframework.org/spring-security/site/xref/ - http://static.springframework.org/spring-security/site/reference/html/ + + + http://static.springsource.org/spring-security/site/docs/3.0.x/apidocs/ + http://static.springsource.org/spring-security/site/docs/3.0.x/reference/ + + Spring Security Class and Interface Index + -

Class and Interface Index

+

Class and Interface Index

+

An list of classes and interfaces used in Spring Security with links to the sections in the Spring Security manual which + refer to them.

+
+
-

- -

Source

- +
+ + +

+ + +

+ + + -

+ + +
+
- - diff --git a/docs/manual/classindex.pl b/docs/manual/src/docbook/classindex.pl similarity index 66% rename from docs/manual/classindex.pl rename to docs/manual/src/docbook/classindex.pl index 9e6692f5d4..c317e3e4a9 100755 --- a/docs/manual/classindex.pl +++ b/docs/manual/src/docbook/classindex.pl @@ -1,9 +1,22 @@ #! /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; # 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"); +# 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`; $#all_classes > 0 || die "No lines in Javadoc"; @@ -16,12 +29,17 @@ $#all_classes > 0 || die "No lines in Javadoc"; my %classnames_to_src; while ($_ = pop @all_classes) { - next unless $_ =~ /(([a-zA-Z0-9_]+?))<\/A>/; - print "Adding class $1, $2\n"; + chomp; +# Get rid of the italic tags round interface names + $_ =~ s///; + $_ =~ s/<\/I>//; + next unless $_ =~ /(([a-zA-Z0-9_]+?))<\/A>.*/; +# print "Adding class $1, $2\n"; $classnames_to_src{$2} = $1; } #my @docbook = glob("*.xml"); +# The list of docbook files xincluded in the manual my @docbook; # Read the includes rather than using globbing to get the ordering right for the index. @@ -34,12 +52,11 @@ while() { # Hash of xml:id (i.e. anchor) to filename.html#anchor my %id_to_html; -my %class_index; # Build map of html pages links while (my $file = pop @docbook) { open FILE, $file or die "$!"; - print "\nProcessing: $file\n\n"; +# print "\nProcessing: $file\n\n"; my $file_id; while() { 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 () { next unless /.* xml:id="([a-z0-9-]+?)"/; - print "$1\n"; +# print "$1\n"; $id_to_html{$1} = "$file_id.html#$1"; } close FILE; @@ -84,11 +101,16 @@ foreach my $class (sort keys %classnames_to_ids) { } print INDEX ">\n"; foreach my $id (@{$classnames_to_ids{$class}}) { - print INDEX " \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 " \n"; } print INDEX "\n" - } print INDEX "\n"; close INDEX; diff --git a/docs/manual/src/docbook/el-access.xml b/docs/manual/src/docbook/el-access.xml index a3102dea4c..d7f0df4955 100644 --- a/docs/manual/src/docbook/el-access.xml +++ b/docs/manual/src/docbook/el-access.xml @@ -15,7 +15,7 @@ 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 principal. -
+
Common Built-In Expressions The base class for expression root objects is SecurityExpressionRoot. This provides some common @@ -121,7 +121,7 @@ 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 the use of expressions. -
+
<literal>@Pre</literal> and <literal>@Post</literal> Annotations There are four annotations which support expression attributes to allow pre and 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 whether the current user has the adminpermission for the given contact. The built-in hasPermission() expression is linked - into the Spring Security ACL module through the application context. You can - access any of the method arguments by name as expression variables, provided + into the Spring Security ACL module through the application context, as we'll + see + below. 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 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 @@ -189,5 +190,52 @@ the entries then this is likely to be inefficient.
+
+ Built-In Expressions + There are some built-in expressions which are specific to method security, which + we have already seen in use above. The filterTarget and + returnValue values are simple enough, but the use of the + hasPermission() expression warrants a closer look. +
+ The <interfacename>PermissionEvaluator</interfacename> interface + hasPermission() expressions are delegated to an instance of + PermissionEvaluator. 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: + boolean hasPermission(Authentication authentication, Object targetDomainObject, Object permission); + + boolean hasPermission(Authentication authentication, Serializable targetId, String targetType, Object permission);which + map directly to the available versions of the expression, with the exception + that the first argument (the Authentication + 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 type 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. + To use hasPermission() expressions, you have to explicitly + configure a PermissionEvaluator in your + application context. This would look something like + this: + + + + + + ]]>Where + myPermissionEvaluator is the bean which implements + PermissionEvaluator. Usually this will be the + implementation from the ACL module which is called + AclPermissionEvaluator. See the + Contacts sample application configuration for more + details. +
+
diff --git a/docs/manual/src/docbook/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml index e25200d38d..f6bac69d6b 100644 --- a/docs/manual/src/docbook/namespace-config.xml +++ b/docs/manual/src/docbook/namespace-config.xml @@ -16,12 +16,12 @@ 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 element from the security namespace to an application context will start up an embedded LDAP - server for testing use within the application: ]]> This is much simpler than wiring up the equivalent Apache Directory Server beans. The most common alternative configuration requirements are supported by attributes on the ldap-server element and the user is isolated from worrying about which - beans they need create and what the bean property names are. You can find out + beans they need to create and what the bean property names are. You can find out more about the use of the ldap-server element in the chapter on LDAP.. Use of a good XML editor while editing the application context file should provide information on the attributes and elements @@ -380,11 +380,11 @@ Detecting Timeouts 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 - session-management element:session-management element: ... - ]]> + ]]>
Concurrent Session Control @@ -392,13 +392,13 @@ application, Spring Security supports this out of the box with the following simple additions. First you need to add the following listener to your web.xml file to keep Spring Security updated about session - lifecycle events: org.springframework.security.web.session.HttpSessionEventPublisher -]]> Then add the following lines to your application context: Then add the following lines to your application context: ... @@ -457,7 +457,7 @@ ]]> You should then register yourself with an OpenID provider (such as myopenid.com), and add the user information to your in-memory - <user-service>: <user-service>: ]]> You should be able to login using the myopenid.com site to @@ -689,7 +689,6 @@ - ... ]]> diff --git a/docs/manual/src/docbook/technical-overview.xml b/docs/manual/src/docbook/technical-overview.xml index 9e2a4d8f03..5278c89d9a 100644 --- a/docs/manual/src/docbook/technical-overview.xml +++ b/docs/manual/src/docbook/technical-overview.xml @@ -284,7 +284,7 @@ Successfully authenticated. Security context contains: \ 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 SecurityContextHolder contains a fully populated - Authentiation object. + Authentication object.
Setting the SecurityContextHolder Contents Directly In fact, Spring Security doesn't mind how you put the @@ -424,7 +424,7 @@ Successfully authenticated. Security context contains: \
Access-Control (Authorization) in Spring Security The main interface resposible for making access-control decisions in Spring Security is - the AccessDecisionMananger. It has a + the AccessDecisionManager. It has a decide method which takes an Authentication object representing the principal requesting access, a secure object (see below) and a list of security metadata attributes