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