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 > >
