As Bill noted, we intentionally took the conservative approach of making things private until we discovered a need to make them protected. I personally think it makes sense to continue with that philosophy as it help to limit the surface area of the APIs. G
On Aug 8, 2011, at 5:03 AM, Chris Bartlett wrote: > Valid points there, Roger. I don't think there will be a single > solution to apply to all Pivot classes for the reasons you state. > > Some classes, like the previously mentioned MessageBus could be > changed easily with low risk. The change might be to make the class > final, make the HashMap protected or to add a protected getter for the > HashMap. However a user could easily copy the source of this class, > rename it and just use their version if they wanted to. > http://svn.apache.org/repos/asf/pivot/trunk/core/src/org/apache/pivot/util/MessageBus.java > > I think I am right in saying that the provided Skins classes are > intended to be subclassed, so they might have some or all of their > private methods & fields changed to protected. > > There will be plenty of others that fall between these two extremes > which will not be so obvious. > > For example, the Resources class is used by BXMLSerializer to provide > locale based text localization so cannot just be replaced by a custom > version made from a copy of the source code. Extending it would be > much easier if the 'resourceMap' field was protected or had a > public/protected accessor. If the class is not meant to be extended, > then marking it as final more clearly communicates that fact, and > therefore that Pivot Resources must be JSON on the classpath, as there > is no way to provide an alternate implementation. > http://svn.apache.org/repos/asf/pivot/trunk/core/src/org/apache/pivot/util/Resources.java > > If we were to mark any public classes as final now, it would be a > breaking change for any code that currently does extend them. Making > the fields/methods more accessible would be far less disruptive, but > implies that the classes are *intended* to be subclassed. > > As I mentioned in my earlier email, I think that such expectations can > be managed/limited via documentation. I wouldn't feel much sympathy > for a developer who extends a class without reading its documentation > first, and then gets caught out later when a necessary change affects > them. > > > On 8 August 2011 11:06, Roger and Beth Whitcomb > <[email protected]> wrote: >> This is an issue we have been wrestling with in our code, because we >> implemented a "Tools API", which is a public contract, really, that if it >> were to be used by outside developers would mean we would have to maintain >> compatibility over the long term. At this point we're not ready (nor >> equipped) to do that, so we chose to not make the API public right now. >> >> So, I think similar questions could be asked here: >> - Are the classes sufficiently stable so that we could reasonably make a >> contract with future users that "protected" fields are not going to change? >> - How much risk is there to limiting future change due to user applications >> depending on what may become vestigial members/methods? >> - How much additional (really useful) functionality would be made available >> by allowing the classes to be extended? >> - How much work is it for users to have to copy/reinvent things if we don't >> allow extensions? >> >> I don't know the answers, but these are some of the questions we have been >> asking about our own APIs.... >> >> >> On 8/7/11 3:06 AM, Chris Bartlett wrote: >>> >>> (This discussion could perhaps be moved to its own thread, but for now >>> I will continue here) >>> >>> I feel the same way as Sandro regarding making Pivot classes easily >>> extendible unless there is a good reason not to. Classes that are not >>> meant to be extended should be marked as 'final' to signal the intent >>> clearly, especially when there are limited Javadocs. Leaving classes >>> non-final makes the API look unfinished IMO as there are times when >>> the only things you would ever need in a subclass are the things >>> marked private and therefore inaccessible to you. >>> >>> It would only need a few lines of documentation in the FAQ and >>> Javadocs to explain that Pivot has chosen to allow its classes to be >>> more easily extended rather than defaulting to making all methods& >>> fields private. This could include a note to say that the API is >>> still evolving and there may be changes later that could affect custom >>> subclasses of Pivot classes, but the choice was made to help Pivot >>> consumers get the most benefit out of the code in the library. >>> >>> There are many Pivot classes that *can* be extended because they are >>> non-final, but which are very hard to meaningfully extend because of >>> the private fields& methods. I mentioned >>> org.apache.pivot.util.MessageBus and org.apache.pivot.util.Resources >>> on the Dev mailing list recently, but Component Skins are a problem >>> too. They contain a lot of private fields& methods which means that >>> it is often easier (or the only option) to copy an entire Skin class >>> and make changes in the copy rather than trying to extend the >>> original, especially if painting is involved. >>> >>> (Threads mentioned above) >>> >>> http://apache-pivot-developers.417237.n3.nabble.com/org-apache-pivot-util-MessageBus-td3151762.html >>> >>> http://apache-pivot-developers.417237.n3.nabble.com/Some-thoughts-on-org-apache-pivot-util-Resources-localization-td3156467.html >>> >>> If anyone else feels strongly about this (either 'for', or 'against' >>> changes) then please let us know. If there is a desire for change, >>> then it might happen, but I don't think it will happen unless it is >>> requested. >>> >>> Chris >>> >>> On 7 August 2011 04:43, Sandro Martini<[email protected]> wrote: >>>> >>>> Hi all, >>>> if you have some real use case that require to change a little some Pivot >>>> classes (even that could change a little its API) maybe a JIRA ticket for >>>> our 2.1 release could be useful. >>>> >>>> My point of view is to enable users to extend Pivot where needed. >>>> And Greg likes real use cases before changing anything in Pivot ... so >>>> write >>>> them (and if possible put even a reference to this thread). >>>> >>>> Bye >>>> >>>> Il giorno 06/ago/2011 20:05, "Bill van Melle"<[email protected]> >>>> ha >>>> scritto: >>>>> >>>>> I remember facing a similar question when I wanted to add an http >>>>> timeout to GetQuery. These classes could be much more usefully >>>>> extended if some of their important locals were marked protected >>>>> instead of private. (Not that it's an easy decision to know when to >>>>> do that when you're implementing the base class. Pivot seems to take >>>>> the conservative approach of marking everything private for which >>>>> Pivot does not itself have a subclass that wants access.) >>>>> >>>>> On Sat, Aug 6, 2011 at 6:49 AM, Thomas G. Schuessler<[email protected]> >>>>> wrote: >>>>>> >>>>>> I cannot access the connection since it is local to Query's execute >>>>>> method. >>>>>> The only ways I can think of to fix this, are: >>>>>> 1. Copy the complete Query.execute, modify it in MyPostQuery, and not >>>>>> call >>>>>> the inherited method at all. >>>>>> 2. Create my own abstract Query class and subclass that. >>> >>
