Gary, How about that?
https://github.com/ok2c/httpcore/commit/b922161b9776672c89bd8df2ce0757de143a15e4 https://github.com/ok2c/httpcore/commit/fff078122075d5ab6249e247b5b71e23422be768 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: [email protected] > For additional commands, e-mail: [email protected] > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
