Merge remote-tracking branch 'origin/master' into gh-2567-master-merge

2019-02-27 Merge of master branch (update of docs) into doc rewrite
branch

.github/ISSUE_REPLY_TEMPLATES.md

@@ -0,0 +1,7 @@
+
+### Complete and Minimal Sample
+
+It would be very helpful if you could provide a complete and minimal sample that reproduces the issue and share it via a GitHub repository. This will allow us to efficiently troubleshoot and help resolve the issue. The sample should contain the minimum amount of code to reproduce the issue along with detailed steps on how to reproduce. Please see the following references for what a complete and minimal sample should consist of.
+
+- http://sscce.org/
+- https://stackoverflow.com/help/mcve

CONTRIBUTING.md

@@ -47,7 +47,7 @@ Create your topic branch to be submitted as a pull request from master. The Spri
 # Use short branch names
 Branches used when submitting pull requests should preferably be named according to GitHub issues, e.g. 'gh-1234' or 'gh-1234-fix-npe'. Otherwise, use succinct, lower-case, dash (-) delimited names, such as 'fix-warnings', 'fix-typo', etc. This is important, because branch names show up in the merge commits that result from accepting pull requests, and should be as expressive and concise as possible.
 
-#Keep commits focused
+# Keep commits focused
 
 Remember each ticket should be focused on a single item of interest since the tickets are used to produce the changelog. Since each commit should be tied to a single GitHub issue, ensure that your commits are focused. For example, do not include an update to a transitive library in your commit unless the GitHub is to update the library. Reviewing your commits is essential before sending a pull request.
 
@@ -125,7 +125,7 @@ Update the [RELAX NG](http://www.relaxng.org) schema `spring-security-x.y.rnc` i
 Changes to the XML schema will be overwritten by the Gradle build task.
 
 # Squash commits
-Use git rebase --interactive, git add --patch and other tools to "squash" multiple commits into atomic changes. In addition to the man pages for git, there are many resources online to help you understand how these tools work. Here is one: http://book.git-scm.com/4_interactive_rebasing.html.
+Use `git rebase --interactive`, `git add --patch` and other tools to "squash" multiple commits into atomic changes. In addition to the man pages for git, there are many resources online to help you understand how these tools work. Here from the [Git SCM Book](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
 
 # Use real name in git commits
 Please configure git to use your real first and last name for any commits you intend to submit as pull requests. For example, this is not acceptable:

Jenkinsfile

@@ -13,7 +13,126 @@ try {
 		stage('Deploy Docs') {
 			node {
 				checkout scm
-				withEnv(["JAVA_HOME=${ tool 'jdk8' }"]) {
+				try {
+					sh "./gradlew clean check  --refresh-dependencies --no-daemon --stacktrace"
+				} catch(Exception e) {
+					currentBuild.result = 'FAILED: check'
+					throw e
+				} finally {
+					junit '**/build/test-results/*/*.xml'
+				}
+			}
+		}
+	},
+	sonar: {
+		stage('Sonar') {
+			node {
+				checkout scm
+				withCredentials([string(credentialsId: 'spring-sonar.login', variable: 'SONAR_LOGIN')]) {
+					try {
+						if ("master" == env.BRANCH_NAME) {
+							sh "./gradlew sonarqube -PexcludeProjects='**/samples/**' -Dsonar.host.url=$SPRING_SONAR_HOST_URL -Dsonar.login=$SONAR_LOGIN --refresh-dependencies --no-daemon --stacktrace"
+						} else {
+							sh "./gradlew sonarqube -PexcludeProjects='**/samples/**' -Dsonar.projectKey='spring-security-${env.BRANCH_NAME}' -Dsonar.projectName='spring-security-${env.BRANCH_NAME}' -Dsonar.host.url=$SPRING_SONAR_HOST_URL -Dsonar.login=$SONAR_LOGIN --refresh-dependencies --no-daemon --stacktrace"
+						}
+					} catch(Exception e) {
+						currentBuild.result = 'FAILED: sonar'
+						throw e
+					}
+				}
+			}
+		}
+	},
+	snapshots: {
+		stage('Snapshot Tests') {
+			node {
+				checkout scm
+				try {
+					sh "./gradlew clean test -PforceMavenRepositories=snapshot -PspringVersion='5.+' -PreactorVersion=Californium-BUILD-SNAPSHOT -PspringDataVersion=Lovelace-BUILD-SNAPSHOT --refresh-dependencies --no-daemon --stacktrace"
+				} catch(Exception e) {
+					currentBuild.result = 'FAILED: snapshots'
+					throw e
+				}
+			}
+		}
+	},
+	jdk9: {
+		stage('JDK 9') {
+			node {
+				checkout scm
+				try {
+					withEnv(["JAVA_HOME=${ tool 'jdk9' }"]) {
+						sh "./gradlew clean test --refresh-dependencies --no-daemon --stacktrace"
+					}
+				} catch(Exception e) {
+					currentBuild.result = 'FAILED: jdk9'
+					throw e
+				}
+			}
+		}
+	},
+	jdk10: {
+		stage('JDK 10') {
+			node {
+				checkout scm
+				try {
+					withEnv(["JAVA_HOME=${ tool 'jdk10' }"]) {
+						sh "./gradlew clean test --refresh-dependencies --no-daemon --stacktrace"
+					}
+				} catch(Exception e) {
+					currentBuild.result = 'FAILED: jdk10'
+					throw e
+				}
+			}
+		}
+	},
+	jdk11: {
+		stage('JDK 11') {
+			node {
+				checkout scm
+				try {
+					withEnv(["JAVA_HOME=${ tool 'jdk11' }"]) {
+						sh "./gradlew clean test --refresh-dependencies --no-daemon --stacktrace"
+					}
+				} catch(Exception e) {
+					currentBuild.result = 'FAILED: jdk11'
+					throw e
+				}
+			}
+		}
+	}
+
+	if(currentBuild.result == 'SUCCESS') {
+		parallel artifacts: {
+			stage('Deploy Artifacts') {
+				node {
+					checkout scm
+					withCredentials([file(credentialsId: 'spring-signing-secring.gpg', variable: 'SIGNING_KEYRING_FILE')]) {
+						withCredentials([string(credentialsId: 'spring-gpg-passphrase', variable: 'SIGNING_PASSWORD')]) {
+							withCredentials([usernamePassword(credentialsId: 'oss-token', passwordVariable: 'OSSRH_PASSWORD', usernameVariable: 'OSSRH_USERNAME')]) {
+								withCredentials([usernamePassword(credentialsId: '02bd1690-b54f-4c9f-819d-a77cb7a9822c', usernameVariable: 'ARTIFACTORY_USERNAME', passwordVariable: 'ARTIFACTORY_PASSWORD')]) {
+									sh "./gradlew deployArtifacts finalizeDeployArtifacts -Psigning.secretKeyRingFile=$SIGNING_KEYRING_FILE -Psigning.keyId=$SPRING_SIGNING_KEYID -Psigning.password='$SIGNING_PASSWORD' -PossrhUsername=$OSSRH_USERNAME -PossrhPassword=$OSSRH_PASSWORD -PartifactoryUsername=$ARTIFACTORY_USERNAME -PartifactoryPassword=$ARTIFACTORY_PASSWORD --refresh-dependencies --no-daemon --stacktrace"
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		docs: {
+			stage('Deploy Docs') {
+				node {
+					checkout scm
+					withCredentials([file(credentialsId: 'docs.spring.io-jenkins_private_ssh_key', variable: 'DEPLOY_SSH_KEY')]) {
+						sh "./gradlew deployDocs -PdeployDocsSshKeyPath=$DEPLOY_SSH_KEY -PdeployDocsSshUsername=$SPRING_DOCS_USERNAME --refresh-dependencies --no-daemon --stacktrace"
+					}
+				}
+			}
+		},
+		schema: {
+			stage('Deploy Schema') {
+				node {
+					checkout scm
 					withCredentials([file(credentialsId: 'docs.spring.io-jenkins_private_ssh_key', variable: 'DEPLOY_SSH_KEY')]) {
 						sh "./gradlew deployDocs -PdeployDocsSshKeyPath=$DEPLOY_SSH_KEY -PdeployDocsSshUsername=$SPRING_DOCS_USERNAME --no-daemon --stacktrace"
 					}

README.adoc

@@ -18,7 +18,7 @@ See https://github.com/spring-projects/spring-framework/wiki/Downloading-Spring-
 
 == Documentation
 Be sure to read the http://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/[Spring Security Reference].
-Extensive JavaDoc for the Spring Security code is also available in the http://docs.spring.io/spring-security/site/docs/current/apidocs/[Spring Security API Documentation].
+Extensive JavaDoc for the Spring Security code is also available in the https://docs.spring.io/spring-security/site/docs/current/api/[Spring Security API Documentation].
 
 == Quick Start
 We recommend you visit http://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/[Spring Security Reference] and read the "Getting Started" page.
@@ -59,7 +59,7 @@ Check out the http://stackoverflow.com/questions/tagged/spring-security[Spring S
 http://spring.io/services[Commercial support] is available too.
 
 == Contributing
-http://help.github.com/send-pull-requests[Pull requests] are welcome; see the https://github.com/spring-projects/spring-security/blob/master/CONTRIBUTING.md[contributor guidelines] for details.
+https://help.github.com/articles/creating-a-pull-request[Pull requests] are welcome; see the https://github.com/spring-projects/spring-security/blob/master/CONTRIBUTING.md[contributor guidelines] for details.
 
 == License
 Spring Security is Open Source software released under the

acl/src/main/java/org/springframework/security/acls/jdbc/AclClassIdUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,11 +18,17 @@
 import java.io.Serializable;
 import java.sql.ResultSet;
 import java.sql.SQLException;
+import java.util.UUID;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.springframework.core.convert.ConversionFailedException;
 import org.springframework.core.convert.ConversionService;
+import org.springframework.core.convert.TypeDescriptor;
+import org.springframework.core.convert.converter.Converter;
+import org.springframework.core.convert.support.GenericConversionService;
 import org.springframework.security.acls.model.ObjectIdentity;
+import org.springframework.util.Assert;
 
 /**
  * Utility class for helping convert database representations of {@link ObjectIdentity#getIdentifier()} into
@@ -36,6 +42,15 @@ class AclClassIdUtils {
 	private ConversionService conversionService;
 
 	public AclClassIdUtils() {
+		GenericConversionService genericConversionService = new GenericConversionService();
+		genericConversionService.addConverter(String.class, Long.class, new StringToLongConverter());
+		genericConversionService.addConverter(String.class, UUID.class, new StringToUUIDConverter());
+		this.conversionService = genericConversionService;
+	}
+
+	public AclClassIdUtils(ConversionService conversionService) {
+		Assert.notNull(conversionService, "conversionService must not be null");
+		this.conversionService = conversionService;
 	}
 
 	/**
@@ -86,17 +101,13 @@ private <T extends Serializable> Class<T> classIdTypeFrom(String className) {
 	}
 
 	private <T> boolean canConvertFromStringTo(Class<T> targetType) {
-		return hasConversionService() && conversionService.canConvert(String.class, targetType);
+		return conversionService.canConvert(String.class, targetType);
 	}
 
 	private <T extends Serializable> T convertFromStringTo(String identifier, Class<T> targetType) {
 		return conversionService.convert(identifier, targetType);
 	}
 
-	private boolean hasConversionService() {
-		return conversionService != null;
-	}
-
 	/**
 	 * Converts to a {@link Long}, attempting to use the {@link ConversionService} if available.
 	 * @param identifier    The identifier
@@ -107,7 +118,7 @@ private boolean hasConversionService() {
 	 */
 	private Long convertToLong(Serializable identifier) {
 		Long idAsLong;
-		if (hasConversionService()) {
+		if (canConvertFromStringTo(Long.class)) {
 			idAsLong = conversionService.convert(identifier, Long.class);
 		} else {
 			idAsLong = Long.valueOf(identifier.toString());
@@ -120,6 +131,31 @@ private boolean isString(Serializable object) {
 	}
 
 	public void setConversionService(ConversionService conversionService) {
+		Assert.notNull(conversionService, "conversionService must not be null");
 		this.conversionService = conversionService;
 	}
+
+	private static class StringToLongConverter implements Converter<String, Long> {
+		@Override
+		public Long convert(String identifierAsString) {
+			if (identifierAsString == null) {
+				throw new ConversionFailedException(TypeDescriptor.valueOf(String.class),
+						TypeDescriptor.valueOf(Long.class), null, null);
+
+			}
+			return Long.parseLong(identifierAsString);
+		}
+	}
+
+	private static class StringToUUIDConverter implements Converter<String, UUID> {
+		@Override
+		public UUID convert(String identifierAsString) {
+			if (identifierAsString == null) {
+				throw new ConversionFailedException(TypeDescriptor.valueOf(String.class),
+						TypeDescriptor.valueOf(UUID.class), null, null);
+
+			}
+			return UUID.fromString(identifierAsString);
+		}
+	}
 }

acl/src/main/java/org/springframework/security/acls/jdbc/BasicLookupStrategy.java

@@ -31,6 +31,7 @@
 import javax.sql.DataSource;
 
 import org.springframework.core.convert.ConversionException;
+import org.springframework.core.convert.ConversionService;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.jdbc.core.PreparedStatementSetter;
 import org.springframework.jdbc.core.ResultSetExtractor;
@@ -553,8 +554,8 @@ public final void setAclClassIdSupported(boolean aclClassIdSupported) {
 		}
 	}
 
-	public final void setAclClassIdUtils(AclClassIdUtils aclClassIdUtils) {
-		this.aclClassIdUtils = aclClassIdUtils;
+	public final void setConversionService(ConversionService conversionService) {
+		this.aclClassIdUtils = new AclClassIdUtils(conversionService);
 	}
 
 	// ~ Inner Classes

acl/src/main/java/org/springframework/security/acls/jdbc/JdbcAclService.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2004, 2005, 2006, 2017 Acegi Technology Pty Limited
+ * Copyright 2004, 2005, 2006, 2017, 2018 Acegi Technology Pty Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,6 +26,8 @@
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.springframework.core.convert.ConversionService;
+import org.springframework.jdbc.core.JdbcOperations;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.jdbc.core.RowMapper;
 import org.springframework.security.acls.domain.ObjectIdentityImpl;
@@ -66,7 +68,7 @@ public class JdbcAclService implements AclService {
 	// ~ Instance fields
 	// ================================================================================================
 
-	protected final JdbcTemplate jdbcTemplate;
+	protected final JdbcOperations jdbcOperations;
 	private final LookupStrategy lookupStrategy;
 	private boolean aclClassIdSupported;
 	private String findChildrenSql = DEFAULT_SELECT_ACL_WITH_PARENT_SQL;
@@ -76,9 +78,13 @@ public class JdbcAclService implements AclService {
 	// ===================================================================================================
 
 	public JdbcAclService(DataSource dataSource, LookupStrategy lookupStrategy) {
-		Assert.notNull(dataSource, "DataSource required");
+		this(new JdbcTemplate(dataSource), lookupStrategy);
+	}
+
+	public JdbcAclService(JdbcOperations jdbcOperations, LookupStrategy lookupStrategy) {
+		Assert.notNull(jdbcOperations, "JdbcOperations required");
 		Assert.notNull(lookupStrategy, "LookupStrategy required");
-		this.jdbcTemplate = new JdbcTemplate(dataSource);
+		this.jdbcOperations = jdbcOperations;
 		this.lookupStrategy = lookupStrategy;
 		this.aclClassIdUtils = new AclClassIdUtils();
 	}
@@ -87,15 +93,14 @@ public JdbcAclService(DataSource dataSource, LookupStrategy lookupStrategy) {
 	// ========================================================================================================
 
 	public List<ObjectIdentity> findChildren(ObjectIdentity parentIdentity) {
-		Object[] args = { parentIdentity.getIdentifier(), parentIdentity.getType() };
-		List<ObjectIdentity> objects = jdbcTemplate.query(findChildrenSql, args,
+		Object[] args = { parentIdentity.getIdentifier().toString(), parentIdentity.getType() };
+		List<ObjectIdentity> objects = jdbcOperations.query(findChildrenSql, args,
 				new RowMapper<ObjectIdentity>() {
 					public ObjectIdentity mapRow(ResultSet rs, int rowNum)
 							throws SQLException {
 						String javaType = rs.getString("class");
 						Serializable identifier = (Serializable) rs.getObject("obj_id");
 						identifier = aclClassIdUtils.identifierFrom(identifier, rs);
-
 						return new ObjectIdentityImpl(javaType, identifier);
 					}
 				});
@@ -163,8 +168,8 @@ public void setAclClassIdSupported(boolean aclClassIdSupported) {
 		}
 	}
 
-	public void setAclClassIdUtils(AclClassIdUtils aclClassIdUtils) {
-		this.aclClassIdUtils = aclClassIdUtils;
+	public void setConversionService(ConversionService conversionService) {
+		this.aclClassIdUtils = new AclClassIdUtils(conversionService);
 	}
 
 	protected boolean isAclClassIdSupported() {