On Wed, 2018-07-11 at 09:57 -0600, Gary Gregory wrote:
> 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()?
>
Most of the time IOException thrown by Closeable#close gets ignored or
logged at best, as there is no reasonable recovery from such condition.
GracefullyCloseable simply makes that explicit and mandates the
classes that implement the interface provide a means of shutting
themselves cleanly.
I am very open to a better name.
I am fine with renaming ShutdownType to CloseMode and
#shutdown(ShutdownType) to #close(CloseMode) as the first step.
Oleg
> Thank you ,
> Gary
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
