From 3d83f869d9b11da87b9ac1ec48f0105862f2b80e Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sat, 9 Nov 2019 18:03:07 +0100 Subject: [PATCH] Fix Javadoc for SmartLifecycle.DEFAULT_PHASE regarding ordering Closes gh-23956 --- .../context/SmartLifecycle.java | 35 +++++++++++-------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/spring-context/src/main/java/org/springframework/context/SmartLifecycle.java b/spring-context/src/main/java/org/springframework/context/SmartLifecycle.java index 4ee111d3d8..06f98a4048 100644 --- a/spring-context/src/main/java/org/springframework/context/SmartLifecycle.java +++ b/spring-context/src/main/java/org/springframework/context/SmartLifecycle.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2018 the original author or authors. + * Copyright 2002-2019 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. @@ -17,19 +17,21 @@ package org.springframework.context; /** - * An extension of the {@link Lifecycle} interface for those objects that require to - * be started upon ApplicationContext refresh and/or shutdown in a particular order. - * The {@link #isAutoStartup()} return value indicates whether this object should + * An extension of the {@link Lifecycle} interface for those objects that require + * to be started upon {@code ApplicationContext} refresh and/or shutdown in a + * particular order. + * + *

The {@link #isAutoStartup()} return value indicates whether this object should * be started at the time of a context refresh. The callback-accepting * {@link #stop(Runnable)} method is useful for objects that have an asynchronous * shutdown process. Any implementation of this interface must invoke the * callback's {@code run()} method upon shutdown completion to avoid unnecessary - * delays in the overall ApplicationContext shutdown. + * delays in the overall {@code ApplicationContext} shutdown. * *

This interface extends {@link Phased}, and the {@link #getPhase()} method's - * return value indicates the phase within which this Lifecycle component should - * be started and stopped. The startup process begins with the lowest phase - * value and ends with the highest phase value ({@code Integer.MIN_VALUE} + * return value indicates the phase within which this {@code Lifecycle} component + * should be started and stopped. The startup process begins with the lowest + * phase value and ends with the highest phase value ({@code Integer.MIN_VALUE} * is the lowest possible, and {@code Integer.MAX_VALUE} is the highest possible). * The shutdown process will apply the reverse order. Any components with the * same value will be arbitrarily ordered within the same phase. @@ -44,9 +46,11 @@ package org.springframework.context; * *

Any {@code Lifecycle} components within the context that do not also * implement {@code SmartLifecycle} will be treated as if they have a phase - * value of 0. That way a {@code SmartLifecycle} implementation may start - * before those {@code Lifecycle} components if it has a negative phase value, - * or it may start after those components if it has a positive phase value. + * value of {@code 0}. This allows a {@code SmartLifecycle} component to start + * before those {@code Lifecycle} components if the {@code SmartLifecycle} + * component has a negative phase value, or the {@code SmartLifecycle} component + * may start after those {@code Lifecycle} components if the {@code SmartLifecycle} + * component has a positive phase value. * *

Note that, due to the auto-startup support in {@code SmartLifecycle}, a * {@code SmartLifecycle} bean instance will usually get initialized on startup @@ -55,6 +59,7 @@ package org.springframework.context; * * @author Mark Fisher * @author Juergen Hoeller + * @author Sam Brannen * @since 3.0 * @see LifecycleProcessor * @see ConfigurableApplicationContext @@ -63,9 +68,10 @@ public interface SmartLifecycle extends Lifecycle, Phased { /** * The default phase for {@code SmartLifecycle}: {@code Integer.MAX_VALUE}. - *

This is different from the common phase 0 associated with regular + *

This is different from the common phase {@code 0} associated with regular * {@link Lifecycle} implementations, putting the typically auto-started - * {@code SmartLifecycle} beans into a separate later shutdown phase. + * {@code SmartLifecycle} beans into a later startup phase and an earlier + * shutdown phase. * @since 5.1 * @see #getPhase() * @see org.springframework.context.support.DefaultLifecycleProcessor#getPhase(Lifecycle) @@ -115,7 +121,8 @@ public interface SmartLifecycle extends Lifecycle, Phased { /** * Return the phase that this lifecycle object is supposed to run in. *

The default implementation returns {@link #DEFAULT_PHASE} in order to - * let stop callbacks execute after regular {@code Lifecycle} implementations. + * let {@code stop()} callbacks execute after regular {@code Lifecycle} + * implementations. * @see #isAutoStartup() * @see #start() * @see #stop(Runnable) -- GitLab