This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 7.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit 2767d569970ce4b9b8eab52040451bc878285683
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Thu Sep 26 22:25:50 2019 +0100
Align with 8.5.x (and fix Javadoc warnings)
---
java/org/apache/catalina/Lifecycle.java | 17 ++++++---
java/org/apache/catalina/util/LifecycleBase.java | 44 +++++++++++++++---------
2 files changed, 39 insertions(+), 22 deletions(-)
diff --git a/java/org/apache/catalina/Lifecycle.java
b/java/org/apache/catalina/Lifecycle.java
index a2b7f99..3dfd7ea 100644
--- a/java/org/apache/catalina/Lifecycle.java
+++ b/java/org/apache/catalina/Lifecycle.java
@@ -53,7 +53,7 @@ package org.apache.catalina;
* | DESTROYED |
* | |
* | stop() |
- * ---»------------------------------»------------------------------
+ * ----»-----------------------------»------------------------------
*
* Any state can transition to FAILED.
*
@@ -87,7 +87,7 @@ public interface Lifecycle {
/**
- * The LifecycleEvent type for the "component after init" event.
+ * The LifecycleEvent type for the "component before init" event.
*/
public static final String BEFORE_INIT_EVENT = "before_init";
@@ -182,8 +182,11 @@ public interface Lifecycle {
/**
- * Get the life cycle listeners associated with this life cycle. If this
- * component has no listeners registered, a zero-length array is returned.
+ * Get the life cycle listeners associated with this life cycle.
+ *
+ * @return An array containing the life cycle listeners associated with
this
+ * life cycle. If this component has no listeners registered, a
+ * zero-length array is returned.
*/
public LifecycleListener[] findLifecycleListeners();
@@ -296,7 +299,11 @@ public interface Lifecycle {
/**
* Obtain a textual representation of the current component state. Useful
- * for JMX.
+ * for JMX. The format of this string may vary between point releases and
+ * should not be relied upon to determine component state. To determine
+ * component state, use {@link #getState()}.
+ *
+ * @return The name of the current component state.
*/
public String getStateName();
diff --git a/java/org/apache/catalina/util/LifecycleBase.java
b/java/org/apache/catalina/util/LifecycleBase.java
index faba205..c9739ca 100644
--- a/java/org/apache/catalina/util/LifecycleBase.java
+++ b/java/org/apache/catalina/util/LifecycleBase.java
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.catalina.util;
import org.apache.catalina.Lifecycle;
@@ -26,7 +25,6 @@ import org.apache.juli.logging.LogFactory;
import org.apache.tomcat.util.ExceptionUtils;
import org.apache.tomcat.util.res.StringManager;
-
/**
* Base implementation of the {@link Lifecycle} interface that implements the
* state transition rules for {@link Lifecycle#start()} and
@@ -110,8 +108,15 @@ public abstract class LifecycleBase implements Lifecycle {
}
+ /**
+ * Sub-classes implement this method to perform any instance initialisation
+ * required.
+ *
+ * @throws LifecycleException If the initialisation fails
+ */
protected abstract void initInternal() throws LifecycleException;
+
/**
* {@inheritDoc}
*/
@@ -175,7 +180,7 @@ public abstract class LifecycleBase implements Lifecycle {
* will be called on the failed component but the parent component will
* continue to start normally.
*
- * @throws LifecycleException
+ * @throws LifecycleException Start error occurred
*/
protected abstract void startInternal() throws LifecycleException;
@@ -246,7 +251,7 @@ public abstract class LifecycleBase implements Lifecycle {
* {@link LifecycleState#STOPPING} during the execution of this method.
* Changing state will trigger the {@link Lifecycle#STOP_EVENT} event.
*
- * @throws LifecycleException
+ * @throws LifecycleException Stop error occurred
*/
protected abstract void stopInternal() throws LifecycleException;
@@ -263,9 +268,7 @@ public abstract class LifecycleBase implements Lifecycle {
}
}
- if (LifecycleState.DESTROYING.equals(state) ||
- LifecycleState.DESTROYED.equals(state)) {
-
+ if (LifecycleState.DESTROYING.equals(state) ||
LifecycleState.DESTROYED.equals(state)) {
if (log.isDebugEnabled()) {
Exception e = new LifecycleException();
log.debug(sm.getString("lifecycleBase.alreadyDestroyed",
toString()), e);
@@ -279,10 +282,8 @@ public abstract class LifecycleBase implements Lifecycle {
return;
}
- if (!state.equals(LifecycleState.STOPPED) &&
- !state.equals(LifecycleState.FAILED) &&
- !state.equals(LifecycleState.NEW) &&
- !state.equals(LifecycleState.INITIALIZED)) {
+ if (!state.equals(LifecycleState.STOPPED) &&
!state.equals(LifecycleState.FAILED) &&
+ !state.equals(LifecycleState.NEW) &&
!state.equals(LifecycleState.INITIALIZED)) {
invalidTransition(Lifecycle.BEFORE_DESTROY_EVENT);
}
@@ -299,8 +300,15 @@ public abstract class LifecycleBase implements Lifecycle {
}
+ /**
+ * Sub-classes implement this method to perform any instance destruction
+ * required.
+ *
+ * @throws LifecycleException If the destruction fails
+ */
protected abstract void destroyInternal() throws LifecycleException;
+
/**
* {@inheritDoc}
*/
@@ -326,9 +334,9 @@ public abstract class LifecycleBase implements Lifecycle {
* transition is valid for a sub-class.
*
* @param state The new state for this component
+ * @throws LifecycleException when attempting to set an invalid state
*/
- protected synchronized void setState(LifecycleState state)
- throws LifecycleException {
+ protected synchronized void setState(LifecycleState state) throws
LifecycleException {
setStateInternal(state, null, true);
}
@@ -341,14 +349,16 @@ public abstract class LifecycleBase implements Lifecycle {
*
* @param state The new state for this component
* @param data The data to pass to the associated {@link Lifecycle} event
+ * @throws LifecycleException when attempting to set an invalid state
*/
protected synchronized void setState(LifecycleState state, Object data)
throws LifecycleException {
setStateInternal(state, data, true);
}
- private synchronized void setStateInternal(LifecycleState state,
- Object data, boolean check) throws LifecycleException {
+
+ private synchronized void setStateInternal(LifecycleState state, Object
data, boolean check)
+ throws LifecycleException {
if (log.isDebugEnabled()) {
log.debug(sm.getString("lifecycleBase.setState", this, state));
@@ -388,9 +398,9 @@ public abstract class LifecycleBase implements Lifecycle {
}
}
+
private void invalidTransition(String type) throws LifecycleException {
- String msg = sm.getString("lifecycleBase.invalidTransition", type,
- toString(), state);
+ String msg = sm.getString("lifecycleBase.invalidTransition", type,
toString(), state);
throw new LifecycleException(msg);
}
}
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
