DO NOT REPLY [Bug 6206] New: - Sixteen Lifecycle implementers disagree with Lifecycle API docs

[bu...@apache.org]

DO NOT REPLY TO THIS EMAIL, BUT PLEASE POST YOUR BUG 
RELATED COMMENTS THROUGH THE WEB INTERFACE AVAILABLE AT
<http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6206>.
ANY REPLY MADE TO THIS MESSAGE WILL NOT BE COLLECTED AND 
INSERTED IN THE BUG DATABASE.

http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6206

Sixteen Lifecycle implementers disagree with Lifecycle API docs

           Summary: Sixteen Lifecycle implementers disagree with Lifecycle
                    API docs
           Product: Tomcat 4
           Version: 4.0.2 Beta 2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: Minor
          Priority: Other
         Component: Catalina
        AssignedTo: tomcat-dev@jakarta.apache.org
        ReportedBy: janekdb@yahoo.co.uk


Lifecycle.java documents the methods start and stop as throwing an
IllegalStateException if invoked when already started/stopped. This contradicts
the majority of the implementations.

Of the 20 classes in org.apache.catalina (and subpackages) which implement
Lifecycle, 16 throw LifecycleException instead of the documented
IllegalStateException. It seems as if the docs in Lifecycle.java are in error
and the 16 classes are correct.


These classes will throw LifecycleExceptions from start () and stop ():

    authenticator/AuthenticatorBase.java
    authenticator/SingleSignOn.java
    cluster/StandardCluster.java
    core/ContainerBase.java
    core/FastEngineMapper.java
    core/StandardPipeline.java
    core/StandardServer.java
    core/StandardService.java
    logger/FileLogger.java
    realm/MemoryRealm.java
    session/PersistentManagerBase.java
    session/StandardManager.java
    session/StoreBase.java
    startup/Embedded.java
    valves/AccessLogValve.java
    valves/CertificatesValve.java

These classes will throw IllegalStateExceptions from start () and stop ():

    realm/RealmBase.java
    realm/JAASRealm.java
    realm/JDBCRealm.java
    realm/UserDatabaseRealm.java

Docs from Lifecycle.java

    /**
     * Prepare for the beginning of active use of the public methods of this
     * component.  This method should be called before any of the public
     * methods of this component are utilized.  It should also send a
     * LifecycleEvent of type START_EVENT to any registered listeners.
     *
     * @exception IllegalStateException if this component has already been
     *  started
     * @exception LifecycleException if this component detects a fatal error
     *  that prevents this component from being used
     */
    public void start() throws LifecycleException;


    /**
     * Gracefully terminate the active use of the public methods of this
     * component.  This method should be the last one called on a given
     * instance of this component.  It should also send a LifecycleEvent
     * of type STOP_EVENT to any registered listeners.
     *
     * @exception IllegalStateException if this component has not been started
     * @exception LifecycleException if this component detects a fatal error
     *  that needs to be reported
     */
    public void stop() throws LifecycleException;

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>