In response to #1 I would say we do not need to be in the business of ensuring developers can rely on our public API's. From my perspective we are in the business of providing a JSF implementation and a series of components and addons for use in any JSF implementation.
I can see a situation where we would need to do something to a component that would break backwards compatability. An example would be the recent changes to tree2 where we added a few new methods to the TreeModel interface. Its an easy upgrade to anyone who implemented their own TreeModel in a previous version but it will technically break code if people upgrade to the newer version of Tomahawk and they have used this more obscure feature of tree2. So be it. This improvement to the interface makes the tree much more flexible now and nobody is forcing anybody to upgrade. Of course we should take every step to avoid this but with components this is unavoidable. As Ted Husted is fond of saying, ultimately there are no customers except for us, the people who do the actual work of writing the software. (I am paraphrasing slightly.) Bottom line is that a component is different then a language like Java or a framework like Struts or JSF where backwards compatability needs to be a higher priority. At least that's my .02 on that subject. As for non components, I really don't have much interest in maintaining a rock solid public API to help people write their own components. There's too much other pressing business IMO. I think users would prefer to see us focus on bringing Tobago and ADF along instead of dwelling on this. As for Issue #2, I would agree this could be an important area to explore. I've used enough bandwidth on issue #1 so I will defer discussion on that until later. In short, I think we should explore what can be done about #2 and I think we should table #1. I also agree that #3 is a distraction at this point. Sean On 2/22/06, Adam Winer <[EMAIL PROTECTED]> wrote: > Definitely. I think we need to extract a few issues here, > and consider them separately. > > (1) Do we need to be in the practice of identifying APIs that > external developers can depend on, and are not subject to > change. If so, how? > (2) Do we consider Tomahawk, Tobago, and ADF as purely > internal codebases that therefore can depend on anything, > or do we define explicit contracts between the various parts > of the overall MyFaces codebase? In particular, do we define > subparts of the architecture as internal even within the project? > (3) Do we split up JARs, and if so what do we name them? > > #3 is pretty minor, and not the big deal here - I'd rather John > hadn't even mentioned it, since it's very easy to get sidetracked > on what is a relatively minor sidepoint. Needs to get talked > about at some point, but until we've decided that there should > even be two JARs or what they'd contain, doesn't make much > sense to talk about what they should be called! > > #1 is something that's very important. I'm deeply uncomfortable > with the notion of just identifying internal classes with Javadoc, > for two main reasons: > - Developers will have no rigorous approach to marking > such classes, and will almost certainly routinely fail to do so > properly. The quantity of code in MyFaces with little or no > Javadoc is a bit discouraging. (Total digression: if there isn't > such a rule already, nothing should get out of Sandbox without > complete Javadoc.) > - End users have no quick way to look at their code and audit it > they're using illicit code. Contrast that to the ease of saying > "am I using javax.faces or com.sun.faces/org.apache?" > > The current reality of the MyFaces codebase is that such distinctions > aren't made at all. In the Tomahawk components, the component > class, the Renderer, and the Tag are all public classes in the same > package, with no Javadoc indication of public or private status. > Are these all really public APIs that can be freely relied on? > > The approach we've used in the ADF Faces codebase - and > been very happy with - is to separate out the API and IMPL > by using different Java packages and JARs. That makes it > trivial for end users to audit their code, or even better to > prevent such dependencies from ever creeping in by only > adding a compile dependency on the API jar. > > #2 may not seem important yet, but as the MyFaces codebase > grows in size, it will become really, really important to making > progress. Without well-defined and minimal dependencies of > the external projects on commons, it will become difficult to > make interesting changes to commons. For example, take > the script-injection code in AddResource; why the dependencies > on Servlet APIs? If I wanted to tackle this, how much code in > the rest of the codebase do I have to analyze and possibly > re-code? > > I see three potential levels: > - Totally public APIs. > - APIs that are public *within* MyFaces, but private externally > - APIs that are private even *within* MyFaces, that is, > only a very limited set of closely related code can depend > on it. > > The middle of these intuitive seems the least desirable - as Manfred > points out, why should code that is acceptable for use by all > component libraries be unacceptable for general use? But as > I understand the current approach, that's what the myfaces-commons > would in fact be. > > -- Adam > > > > On 2/22/06, Sean Schofield <[EMAIL PROTECTED]> wrote: > > I agree with Manfred that we should not rename the implementation jars > > (myfaces-impl.jar and myfaces-api.jar) for the reasons he has stated. > > Even if you take Maven out of the picture you don't want to clash with > > jar names the RI is using. > > > > Naming is only a small part of what John is suggesting, however. I > > think he is onto something here even though I don't necessarily agree > > with all of the proposed solutions to the issue. > > > > The issue that John raises that interests me is the future inclusion > > of Tobago and ADF. There may be code that could be shared between > > these two projects and Tomahawk that has nothing to do with impl. So > > essentially we are talking about another core for components. > > > > I'm not sure how much overlap there is although on the surface there > > seems to be a lot. I will need to dive deeper into the two projects > > before I could say for sure. Lets take the tree case since I am not > > familiar with the file upload component and presumably John is > > familiar with the ADF tree. Is it possible to have a single component > > shared between Tomahawk and ADF and only have different renderers in > > the separate subprojects? That would be interesting and probably more > > realistic then an outright merger of the two trees. > > > > If something like this is possible then maybe we could have a > > tomahawk-core.jar with the components and tomahawk-impl.jar with the > > tags, renderers and config files? > > > > Sean > > > > On 2/22/06, Manfred Geiler <[EMAIL PROTECTED]> wrote: > > > On 2/21/06, John Fallows <[EMAIL PROTECTED]> wrote: > > > > Folks, > > > > > > > > There seems to be increasing discussion lately regarding MyFaces > > > > Commons and > > > > how it relates to both MyFaces Core and MyFaces Tomahawk. > > > > > > > > Adding Tobago and ADF Faces to the discussion makes it even more > > > > critical > > > > that we come up with a useful way to share reusable code between the > > > > various > > > > projects. So, I thought it might be helpful to the current discussion > > > > if I > > > > shared my thoughts about this for the future. > > > > > > > > Right now, we tend to think of MyFaces Commons as a dumping ground for > > > > common utility code that is reused between the Core and Tomahawk, and > > > > AFAIK, > > > > none of this code has been vetted for its suitability as a consistently > > > > backwards-compatible public API. > > > > > > > > In future, we'll need to provide common code to all component libraries > > > > developed as part of the MyFaces effort (and outside MyFaces too), and > > > > due > > > > to the independent upgrade requirements for individual component > > > > libraries, > > > > that common codebase will need to provide a guarantee of backwards > > > > compatiblilty. > > > > > > > > One example of such shared code for the future might be a common > > > > strategy > > > > for the FileUpload feature. It would be a real shame if all of the > > > > internal > > > > implementation code for this FileUpload feature became part of a public > > > > API > > > > just because it was added to Commons. So, I propose a split in Commons > > > > between public API and private implementation. In fact, I think it > > > > shouldn't be called Commons either. :-) > > > > > > > > [groupId = org.apache.myfaces] > > > > myfaces-api-x.y.z.jar > > > > myfaces-impl-x.y.z.jar > > > > > > My definite > > > -1 on naming anything other than the current MyFaces JSF API and Impl > > > as "myfaces-api-*" or "myfaces-impl-*" > > > > > > Not only this would totally confuse our users, having equally named > > > artifacts in Maven that not only differ in version and/or > > > features/bugs but totally differ in their contents sounds more than > > > unreasonable to me. > > > > > > > > > > Dependent projects should be free to create compile-time dependencies > > > > against myfaces-api, but not myfaces-impl. > > > > > > > > The code currently in Commons will need an overhaul to prepare it for > > > > such > > > > backwards compatibility strictness. We should take a hard look at the > > > > codebase in there and decide how best to trim it to a managable size > > > > that > > > > can realisticly be kept compatible across releases. > > > > > > > > Now, this raises the point about the naming for the current API and > > > > implementation for the specification. How about the following? > > > > > > > > [groupId = org.apache.myfaces] > > > > jsf-api-a.b.c.jar > > > > jsf-impl-a.b.c.jar > > > > > > -1 on naming any of our libs identical to any other publicly available > > > lib. Ok, they would differ in Maven groupId, but AFAICT most of our > > > end users will not use Maven at all. Anyway, having equally named libs > > > from different sources sounds very dangerous to me. > > > > > > -0.9 on renaming our current api and impl libs at all > > > > > > > > > > I think this makes two things very clear. > > > > > > > > MyFaces spec api and impl do not contain any non-spec related code > > > > (i.e. no > > > > non-portable "extensions" to the spec) > > > > > > > > MyFaces spec api and impl are equivalents of the reference api and impl > > > > from > > > > Sun > > > > In addition, we might need to break the dependency between > > > > jsf-impl-x.y.z.jar and myfaces-api-x.y.z.jar/my-faces-impl.x.y.z.jar > > > > above. > > > > This may still involve "inlining" commons into the jsf-impl JAR to avoid > > > > potential problems with JavaEE containers vs. webapp ClassLoaders. > > > > > > +1 on "inlining" commons into the jsf-impl JAR for the above reasons > > > I will do some additional experiments on this today. Stay tuned... > > > > > > > > > > It certainly feels better to have a directed dependency from the > > > > MyFaces API > > > > / Impl -> standard JSF API / Impl rather than the reverse. :-) > > > > > > Don't know what you mean by that. > > > > > > > > > > Btw, do JavaEE containers, e.g. Tomcat, properly isolate the Webapp > > > > ClassLoader from the container's own ClassLoader, preventing visibility > > > > of > > > > jsf-impl and only exposing jsf-api to the Webapp ClassLoader? This > > > > should > > > > be perfectly possible using appropriate ClassLoader parentage, but I'm > > > > not > > > > certain if it is commonly done or mentioned in the JavaEE specification. > > > > > > > > For Tomahawk, Tobago and ADF Faces, we can have the following. > > > > > > > > [groupId = org.apache.myfaces] > > > > tomahawk-api-d.e.f.jar > > > > tomahawk-impl-d.e.f.jar > > > > > > > > tobago-api-g.h.i.jar > > > > tobago-impl-g.h.i.jar > > > > > > > > adf-faces-api-j.k.l.jar* > > > > adf-faces-impl-j.k.l.jar* > > > > > > > > where each has a compile time dependeny on both jsf-api and myfaces-api > > > > but > > > > only a runtime dependency on the internal implementation details of > > > > jsf-impl > > > > and myfaces-impl. > > > > > > > > *adf-faces to be renamed during incubation. > > > > > > > > When any of these projects need to be upgraded, and it depends on a > > > > newer > > > > version of myfaces-api / myfaces-impl, the upgrade can proceed with > > > > confidence because the newer version guarantees backwards compatibilty > > > > at > > > > compile-time for myfaces-api and at runtime for myfaces-impl. > > > > > > > > Thoughts? > > > > > > I have the feeling of a slight overkill here. Splitting everything > > > into api and impl makes things unnecessarily complicated. Making it > > > clear in javadoc what is subject to change and what api people can > > > rely on shoud be enough IMHO. > > > > > > What I could do secondary to the planned refactoring of commons > > > classes (package move from o.a.myfaces .* --> o.a.myfaces.commons.*) > > > is to try splitting commons classes into "MyFaces specific helpers" > > > and "Reasonable public interest goodies". The former would be those > > > classes that are subject to change on most releases and could be moved > > > into their own package "o.a.myfaces.commons.private.*" or better, but > > > perhaps confusing "o.a.myfaces.commons.impl.*". The latter would be > > > those "API like" utils and base classes that people may rely on in > > > their own custom components. > > > > > > WDYT? > > > > > > Manfred > > > > > >
