From 6fc388315e686650709e406aef377398fa71097f Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Fri, 12 Jun 2015 21:59:44 +0200 Subject: [PATCH] Polish Javadoc for @Transactional --- .../transaction/annotation/Transactional.java | 59 +++++++++++-------- 1 file changed, 33 insertions(+), 26 deletions(-) diff --git a/spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java b/spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java index 856d24ace5..73a5b2a0b4 100644 --- a/spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java +++ b/spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2012 the original author or authors. + * Copyright 2002-2015 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. @@ -38,11 +38,12 @@ import org.springframework.transaction.TransactionDefinition; * (rolling back on runtime exceptions). * *

For specific information about the semantics of this annotation's attributes, - * consider the {@link org.springframework.transaction.TransactionDefinition} and + * consult the {@link org.springframework.transaction.TransactionDefinition} and * {@link org.springframework.transaction.interceptor.TransactionAttribute} javadocs. * * @author Colin Sampaleanu * @author Juergen Hoeller + * @author Sam Brannen * @since 1.2 * @see org.springframework.transaction.interceptor.TransactionAttribute * @see org.springframework.transaction.interceptor.DefaultTransactionAttribute @@ -55,7 +56,7 @@ import org.springframework.transaction.TransactionDefinition; public @interface Transactional { /** - * A qualifier value for the specified transaction. + * A qualifier value for the specified transaction. *

May be used to determine the target transaction manager, * matching the qualifier value (or the bean name) of a specific * {@link org.springframework.transaction.PlatformTransactionManager} @@ -65,28 +66,28 @@ public @interface Transactional { /** * The transaction propagation type. - * Defaults to {@link Propagation#REQUIRED}. + *

Defaults to {@link Propagation#REQUIRED}. * @see org.springframework.transaction.interceptor.TransactionAttribute#getPropagationBehavior() */ Propagation propagation() default Propagation.REQUIRED; /** * The transaction isolation level. - * Defaults to {@link Isolation#DEFAULT}. + *

Defaults to {@link Isolation#DEFAULT}. * @see org.springframework.transaction.interceptor.TransactionAttribute#getIsolationLevel() */ Isolation isolation() default Isolation.DEFAULT; /** * The timeout for this transaction. - * Defaults to the default timeout of the underlying transaction system. + *

Defaults to the default timeout of the underlying transaction system. * @see org.springframework.transaction.interceptor.TransactionAttribute#getTimeout() */ int timeout() default TransactionDefinition.TIMEOUT_DEFAULT; /** * {@code true} if the transaction is read-only. - * Defaults to {@code false}. + *

Defaults to {@code false}. *

This just serves as a hint for the actual transaction subsystem; * it will not necessarily cause failure of write access attempts. * A transaction manager which cannot interpret the read-only hint will @@ -96,12 +97,13 @@ public @interface Transactional { boolean readOnly() default false; /** - * Defines zero (0) or more exception {@link Class classes}, which must be a - * subclass of {@link Throwable}, indicating which exception types must cause + * Defines zero (0) or more exception {@link Class classes}, which must be + * subclasses of {@link Throwable}, indicating which exception types must cause * a transaction rollback. - *

This is the preferred way to construct a rollback rule, matching the - * exception class and subclasses. + *

This is the preferred way to construct a rollback rule (in contrast to + * {@link #rollbackForClassName}), matching the exception class and its subclasses. *

Similar to {@link org.springframework.transaction.interceptor.RollbackRuleAttribute#RollbackRuleAttribute(Class clazz)} + * @see #rollbackForClassName */ Class[] rollbackFor() default {}; @@ -109,26 +111,30 @@ public @interface Transactional { * Defines zero (0) or more exception names (for exceptions which must be a * subclass of {@link Throwable}), indicating which exception types must cause * a transaction rollback. - *

This can be a substring, with no wildcard support at present. - * A value of "ServletException" would match - * {@link javax.servlet.ServletException} and subclasses, for example. - *

NB: Consider carefully how specific the pattern is, and whether + *

This can be a substring of a fully qualified class name, with no wildcard + * support at present. For example, a value of {@code "ServletException"} would + * match {@link javax.servlet.ServletException} and its subclasses. + *

NB: Consider carefully how specific the pattern is and whether * to include package information (which isn't mandatory). For example, - * "Exception" will match nearly anything, and will probably hide other rules. - * "java.lang.Exception" would be correct if "Exception" was meant to define - * a rule for all checked exceptions. With more unusual {@link Exception} - * names such as "BaseBusinessException" there is no need to use a FQN. + * {@code "Exception"} will match nearly anything and will probably hide other + * rules. {@code "java.lang.Exception"} would be correct if {@code "Exception"} + * were meant to define a rule for all checked exceptions. With more unusual + * {@link Exception} names such as {@code "BaseBusinessException"} there is no + * need to use a FQN. *

Similar to {@link org.springframework.transaction.interceptor.RollbackRuleAttribute#RollbackRuleAttribute(String exceptionName)} + * @see #rollbackFor */ String[] rollbackForClassName() default {}; /** - * Defines zero (0) or more exception {@link Class Classes}, which must be a - * subclass of {@link Throwable}, indicating which exception types must not - * cause a transaction rollback. - *

This is the preferred way to construct a rollback rule, matching the - * exception class and subclasses. + * Defines zero (0) or more exception {@link Class Classes}, which must be + * subclasses of {@link Throwable}, indicating which exception types must + * not cause a transaction rollback. + *

This is the preferred way to construct a rollback rule (in contrast + * to {@link #noRollbackForClassName}), matching the exception class and + * its subclasses. *

Similar to {@link org.springframework.transaction.interceptor.NoRollbackRuleAttribute#NoRollbackRuleAttribute(Class clazz)} + * @see #noRollbackForClassName */ Class[] noRollbackFor() default {}; @@ -136,9 +142,10 @@ public @interface Transactional { * Defines zero (0) or more exception names (for exceptions which must be a * subclass of {@link Throwable}) indicating which exception types must not * cause a transaction rollback. - *

See the description of {@link #rollbackForClassName()} for more info on how - * the specified names are treated. + *

See the description of {@link #rollbackForClassName} for further + * information on how the specified names are treated. *

Similar to {@link org.springframework.transaction.interceptor.NoRollbackRuleAttribute#NoRollbackRuleAttribute(String exceptionName)} + * @see #noRollbackFor */ String[] noRollbackForClassName() default {};