On Thu, Jul 12, 2018 at 3:09 AM Oleg Kalnichevski <ol...@apache.org> wrote:

> Gary,
>
> How about that?
>
>
> https://github.com/ok2c/httpcore/commit/b922161b9776672c89bd8df2ce0757de143a15e4
>
> https://github.com/ok2c/httpcore/commit/fff078122075d5ab6249e247b5b71e23422be768


+1 :-) Much better IMO.

Gary

>
>
> Oleg
>
>
> On Wed, 2018-07-11 at 23:16 +0200, Oleg Kalnichevski wrote:
> > 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: dev-unsubscr...@hc.apache.org
> > For additional commands, e-mail: dev-h...@hc.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org
> For additional commands, e-mail: dev-h...@hc.apache.org
>
>

Reply via email to