Polishing

spring-core/src/main/java/org/springframework/util/unit/DataSize.java

@@ -25,8 +25,8 @@ import org.springframework.util.StringUtils;
 
 /**
  * A data size, such as '12MB'.
- * <p>
+ *
- * This class models a size in terms of bytes and is immutable and thread-safe.
+ * <p>This class models a size in terms of bytes and is immutable and thread-safe.
  *
  * @author Stephane Nicoll
  * @since 5.1
@@ -61,6 +61,7 @@ public final class DataSize implements Comparable<DataSize> {
 
 	private final long bytes;
 
+
 	private DataSize(long bytes) {
 		this.bytes = bytes;
 	}
@@ -113,13 +114,13 @@ public final class DataSize implements Comparable<DataSize> {
 
 	/**
 	 * Obtain a {@link DataSize} representing an amount in the specified {@link DataUnit}.
-	 * @param amount the amount of the size, measured in terms of the unit, positive or
+	 * @param amount the amount of the size, measured in terms of the unit,
-	 * negative
+	 * positive or negative
-	 * @return a {@link DataSize}
+	 * @return a corresponding {@link DataSize}
 	 */
 	public static DataSize of(long amount, DataUnit unit) {
 		Assert.notNull(unit, "Unit must not be null");
-		return new DataSize(Math.multiplyExact(amount, unit.getSize().toBytes()));
+		return new DataSize(Math.multiplyExact(amount, unit.size().toBytes()));
 	}
 
 	/**
@@ -162,20 +163,17 @@ public final class DataSize implements Comparable<DataSize> {
 			Matcher matcher = PATTERN.matcher(text);
 			Assert.state(matcher.matches(), "Does not match data size pattern");
 			DataUnit unit = determineDataUnit(matcher.group(2), defaultUnit);
-			Long amount = Long.parseLong(matcher.group(1));
+			long amount = Long.parseLong(matcher.group(1));
 			return DataSize.of(amount, unit);
 		}
 		catch (Exception ex) {
-			throw new IllegalArgumentException(
+			throw new IllegalArgumentException("'" + text + "' is not a valid data size", ex);
-					"'" + text + "' is not a valid data size", ex);
 		}
 	}
 
-	private static DataUnit determineDataUnit(String suffix,
+	private static DataUnit determineDataUnit(String suffix, @Nullable DataUnit defaultUnit) {
-			@Nullable DataUnit defaultUnit) {
+		DataUnit defaultUnitToUse = (defaultUnit != null ? defaultUnit : DataUnit.BYTES);
-		defaultUnit = (defaultUnit != null ? defaultUnit : DataUnit.BYTES);
+		return (StringUtils.hasLength(suffix) ? DataUnit.fromSuffix(suffix) : defaultUnitToUse);
-		return (StringUtils.hasLength(suffix) ? DataUnit.fromSuffix(suffix)
-				: defaultUnit);
 	}
 
 	/**
@@ -236,16 +234,17 @@ public final class DataSize implements Comparable<DataSize> {
 		return String.format("%dB", this.bytes);
 	}
 
+
 	@Override
-	public boolean equals(Object o) {
+	public boolean equals(Object other) {
-		if (this == o) {
+		if (this == other) {
 			return true;
 		}
-		if (o == null || getClass() != o.getClass()) {
+		if (other == null || getClass() != other.getClass()) {
 			return false;
 		}
-		DataSize that = (DataSize) o;
+		DataSize otherSize = (DataSize) other;
-		return this.bytes == that.bytes;
+		return (this.bytes == otherSize.bytes);
 	}
 
 	@Override
@@ -254,4 +253,3 @@ public final class DataSize implements Comparable<DataSize> {
 	}
 
 }
-

spring-core/src/main/java/org/springframework/util/unit/DataUnit.java

@@ -32,35 +32,37 @@ public enum DataUnit {
 	BYTES("B", DataSize.ofBytes(1)),
 
 	/**
-	 * KiloByte.
+	 * KiloBytes.
 	 */
 	KILOBYTES("KB", DataSize.ofKiloBytes(1)),
 
 	/**
-	 * MegaByte.
+	 * MegaBytes.
 	 */
 	MEGABYTES("MB", DataSize.ofMegaBytes(1)),
 
 	/**
-	 * TeraByte.
+	 * GigaBytes.
 	 */
 	GIGABYTES("GB", DataSize.ofGigaBytes(1)),
 
 	/**
-	 * TeraByte.
+	 * TeraBytes.
 	 */
 	TERABYTES("TB", DataSize.ofTeraBytes(1));
 
+
 	private final String suffix;
 
 	private final DataSize size;
 
+
 	DataUnit(String suffix, DataSize size) {
 		this.suffix = suffix;
 		this.size = size;
 	}
 
-	protected DataSize getSize() {
+	DataSize size() {
 		return this.size;
 	}
 
@@ -68,7 +70,8 @@ public enum DataUnit {
 	 * Return the {@link DataUnit} matching the specified {@code suffix}.
 	 * @param suffix one of the standard suffix
 	 * @return the {@link DataUnit} matching the specified {@code suffix}
-	 * @throws IllegalArgumentException if the suffix does not match any instance
+	 * @throws IllegalArgumentException if the suffix does not match any
+	 * of this enum's constants
 	 */
 	public static DataUnit fromSuffix(String suffix) {
 		for (DataUnit candidate : values()) {

spring-tx/src/main/java/org/springframework/transaction/TransactionStatus.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 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.
@@ -25,7 +25,7 @@ import java.io.Flushable;
  * and to programmatically request a rollback (instead of throwing
  * an exception that causes an implicit rollback).
  *
- * <p>Derives from the SavepointManager interface to provide access
+ * <p>Includes the {@link SavepointManager} interface to provide access
  * to savepoint management facilities. Note that savepoint management
  * is only available if supported by the underlying transaction manager.
  *
@@ -39,9 +39,9 @@ import java.io.Flushable;
 public interface TransactionStatus extends SavepointManager, Flushable {
 
 	/**
-	 * Return whether the present transaction is new (else participating
+	 * Return whether the present transaction is new; otherwise participating
-	 * in an existing transaction, or potentially not running in an
+	 * in an existing transaction, or potentially not running in an actual
-	 * actual transaction in the first place).
+	 * transaction in the first place.
 	 */
 	boolean isNewTransaction();
 
@@ -50,9 +50,9 @@ public interface TransactionStatus extends SavepointManager, Flushable {
 	 * that is, has been created as nested transaction based on a savepoint.
 	 * <p>This method is mainly here for diagnostic purposes, alongside
 	 * {@link #isNewTransaction()}. For programmatic handling of custom
-	 * savepoints, use SavepointManager's operations.
+	 * savepoints, use the operations provided by {@link SavepointManager}.
 	 * @see #isNewTransaction()
-	 * @see #createSavepoint
+	 * @see #createSavepoint()
 	 * @see #rollbackToSavepoint(Object)
 	 * @see #releaseSavepoint(Object)
 	 */

spring-tx/src/main/java/org/springframework/transaction/support/DefaultTransactionStatus.java

@@ -66,14 +66,14 @@ public class DefaultTransactionStatus extends AbstractTransactionStatus {
 
 
 	/**
-	 * Create a new DefaultTransactionStatus instance.
+	 * Create a new {@code DefaultTransactionStatus} instance.
-	 * @param transaction underlying transaction object that can hold
+	 * @param transaction underlying transaction object that can hold state
-	 * state for the internal transaction implementation
+	 * for the internal transaction implementation
-	 * @param newTransaction if the transaction is new,
+	 * @param newTransaction if the transaction is new, otherwise participating
-	 * else participating in an existing transaction
+	 * in an existing transaction
-	 * @param newSynchronization if a new transaction synchronization
+	 * @param newSynchronization if a new transaction synchronization has been
-	 * has been opened for the given transaction
+	 * opened for the given transaction
-	 * @param readOnly whether the transaction is read-only
+	 * @param readOnly whether the transaction is marked as read-only
 	 * @param debug should debug logging be enabled for the handling of this transaction?
 	 * Caching it in here can prevent repeated calls to ask the logging system whether
 	 * debug logging should be enabled.
@@ -130,9 +130,9 @@ public class DefaultTransactionStatus extends AbstractTransactionStatus {
 	}
 
 	/**
-	 * Return whether the progress of this transaction is debugged. This is used
+	 * Return whether the progress of this transaction is debugged. This is used by
-	 * by AbstractPlatformTransactionManager as an optimization, to prevent repeated
+	 * {@link AbstractPlatformTransactionManager} as an optimization, to prevent repeated
-	 * calls to {@code logger.isDebug()}. Not really intended for client code.
+	 * calls to {@code logger.isDebugEnabled()}. Not really intended for client code.
 	 */
 	public boolean isDebug() {
 		return this.debug;
@@ -153,11 +153,11 @@ public class DefaultTransactionStatus extends AbstractTransactionStatus {
 	//---------------------------------------------------------------------
 
 	/**
-	 * Determine the rollback-only flag via checking both the transaction object,
+	 * Determine the rollback-only flag via checking the transaction object, provided
-	 * provided that the latter implements the {@link SmartTransactionObject} interface.
+	 * that the latter implements the {@link SmartTransactionObject} interface.
-	 * <p>Will return "true" if the transaction itself has been marked rollback-only
+	 * <p>Will return {@code true} if the global transaction itself has been marked
-	 * by the transaction coordinator, for example in case of a timeout.
+	 * rollback-only by the transaction coordinator, for example in case of a timeout.
-	 * @see SmartTransactionObject#isRollbackOnly
+	 * @see SmartTransactionObject#isRollbackOnly()
 	 */
 	@Override
 	public boolean isGlobalRollbackOnly() {
@@ -166,8 +166,9 @@ public class DefaultTransactionStatus extends AbstractTransactionStatus {
 	}
 
 	/**
-	 * Delegate the flushing to the transaction object,
+	 * Delegate the flushing to the transaction object, provided that the latter
-	 * provided that the latter implements the {@link SmartTransactionObject} interface.
+	 * implements the {@link SmartTransactionObject} interface.
+	 * @see SmartTransactionObject#flush()
 	 */
 	@Override
 	public void flush() {
@@ -177,24 +178,26 @@ public class DefaultTransactionStatus extends AbstractTransactionStatus {
 	}
 
 	/**
-	 * This implementation exposes the SavepointManager interface
+	 * This implementation exposes the {@link SavepointManager} interface
 	 * of the underlying transaction object, if any.
+	 * @throws NestedTransactionNotSupportedException if savepoints are not supported
+	 * @see #isTransactionSavepointManager()
 	 */
 	@Override
 	protected SavepointManager getSavepointManager() {
 		Object transaction = this.transaction;
 		if (!(transaction instanceof SavepointManager)) {
 			throw new NestedTransactionNotSupportedException(
-				"Transaction object [" + this.transaction + "] does not support savepoints");
+					"Transaction object [" + this.transaction + "] does not support savepoints");
 		}
 		return (SavepointManager) transaction;
 	}
 
 	/**
-	 * Return whether the underlying transaction implements the
+	 * Return whether the underlying transaction implements the {@link SavepointManager}
-	 * SavepointManager interface.
+	 * interface and therefore supports savepoints.
-	 * @see #getTransaction
+	 * @see #getTransaction()
-	 * @see org.springframework.transaction.SavepointManager
+	 * @see #getSavepointManager()
 	 */
 	public boolean isTransactionSavepointManager() {
 		return (this.transaction instanceof SavepointManager);

spring-tx/src/main/java/org/springframework/transaction/support/SimpleTransactionStatus.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 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,10 +18,8 @@ package org.springframework.transaction.support;
 
 /**
  * A simple {@link org.springframework.transaction.TransactionStatus}
- * implementation.
+ * implementation. Derives from {@link AbstractTransactionStatus} and
- *
+ * adds an explicit {@link #isNewTransaction() "newTransaction"} flag.
- * <p>Derives from {@link AbstractTransactionStatus} and adds an explicit
- * {@link #isNewTransaction() "newTransaction"} flag.
  *
  * <p>This class is not used by any of Spring's pre-built
  * {@link org.springframework.transaction.PlatformTransactionManager}
@@ -32,8 +30,7 @@ package org.springframework.transaction.support;
  *
  * @author Juergen Hoeller
  * @since 1.2.3
- * @see #SimpleTransactionStatus(boolean)
+ * @see TransactionCallback#doInTransaction
- * @see TransactionCallback
  */
 public class SimpleTransactionStatus extends AbstractTransactionStatus {
 
@@ -41,7 +38,7 @@ public class SimpleTransactionStatus extends AbstractTransactionStatus {
 
 
 	/**
-	 * Create a new instance of the {@link SimpleTransactionStatus} class,
+	 * Create a new {@code SimpleTransactionStatus} instance,
 	 * indicating a new transaction.
 	 */
 	public SimpleTransactionStatus() {
@@ -49,7 +46,7 @@ public class SimpleTransactionStatus extends AbstractTransactionStatus {
 	}
 
 	/**
-	 * Create a new instance of the {@link SimpleTransactionStatus} class.
+	 * Create a new {@code SimpleTransactionStatus} instance.
 	 * @param newTransaction whether to indicate a new transaction
 	 */
 	public SimpleTransactionStatus(boolean newTransaction) {