Hi All:
I think naming things as best we can is important, so I'd like to talk
about the following.
We have in HttpCore 5:
package org.apache.hc.core5.io;
import java.io.Closeable;
/**
* Process or endpoint that can be gracefully closed.
*
* @since 5.0
*/
public interface GracefullyCloseable extends Closeable {
/**
* Closes this endpoint and releases any system resources associated
* with it. If the endpoint is already closed then invoking this
* method has no effect.
*/
void shutdown(ShutdownType shutdownType);
}
- The interface is called GracefullyCloseable and it extends Closeable (which
implements close() of course)
- The only method in GracefullyCloseable is Javadoc'ed as "Closes ..."
- And yet the method is _not_ called close(ShutdownType). which feels odd
to me.
IMO, either the interface name or the method name needs to change...
Then we have:
/**
* Shutdown type.
*
* @since 5.0
*/
public enum ShutdownType {
IMMEDIATE, GRACEFUL
}
If an object is "gracefully closeable":
- it does not sound right to ask it to close "immediately", which is not
graceful, and
- it sounds redundant to ask it to close gracefully since it is you already
told me it is "gracefully closeable" which now sound like the object is
only _optionally_ gracefully closeable.
- then, there is the third option of calling close() which becomes a
implementation dependent mystery as to close() meaning close(IMMEDIATE) or
close(GRACEFUL). I suppose the Javadoc for an implementation of close()
should tell me that ;-)
This tells me that the interface is misnamed. This interface offers
graceful shutdown as an _option_, not a given. IOW it could also be called
ImmediatelyCloseable which would be just as confusing.
So for me I would like the interface name to tell me that the object is
closable but can do so with options and in this case the options are on how
cleanly or politely (I suppose) we are tidying things up.
How about TypedCloseable? StyledCloseable? ParameterizedCloseable? It's
hard to find a better name! ;-)
Another oddity is that Closeable.close() throws an IOException and our
close(ShutdownType) throws nothing. So does that mean I can safely ignore
IOExceptions from close()?
Thank you ,
Gary
