incubator-adffaces-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Adam Winer" <awi...@gmail.com>
Subject Re: API Documentation for "oracle.adfinternal.view.faces" package
Date Fri, 31 Mar 2006 21:47:00 GMT
On 3/31/06, arti <arti@tambas.at> wrote:
> Hi Adam,
>
> Thanks for details. I have few queries.
>
> If the queries are out of your scope, can you please direct me to
> concerned person please? It is critical for us to make a decision for
> using ADF or not.
>
> 1. Can you elaborate what do you mean by "not part of Public API", when
> ADF is declared as donated to Apache under Apache 2.0 lisence?

By "public" I don't mean license.  I mean "public" in a Java API
sense, public vs. private.

> 2. If the entire source code for "adfinternal" package is already made
> available, why not just API docs?

You're free to run javadoc over the code.  It's available in
that it is required at runtime, but it is an internal implementation
detail that customers should not rely on.

> 3. Will future versions of ADF Faces NOT be backward-compatible with the
> current "early access release" available?

In the process of going through the incubator, we have no
choice but to make non-backwards-compatible changes, because
we're going to move into an org.apache package and out of
oracle.adf.

The point is that once we're out of incubator land, you can
depend on whatever the new counterpart will be to oracle.adf;
we will not introduce backwards-incompatible changes except
at "major" release cycles (e.g., going from 1.0 to 2.0, but
not from 1.0 to 1.1).  The counterpart for oracle.adfinternal,
not so;  it can change arbitrarily.

This is completely standard practice in the industry - witness
the Sun RI split between javax.faces (public API) and
com.sun.faces (private API), or in the JDK itself (java.*
vs. com.sun.*).

This is also a stronger guarantee than what is currently stated for
the Tomahawk codebase, for example, where backwards compatibility
is not guaranteed for any code.

> 4. Surprisingly this fact is not clearly mentioned on Oracle ADF
> website, neither on Apache incubation website.

It should be better documented, yes.

> 5. Due to project urgency, if we are forced to use currnet version of
> ADF, we have high risk in upgrading to future versions. What is Oracle's
> suggestion for minimizing such upgradation-risk?

Which current version?  The 10.1.3 Oracle JDev version, or
the code that will be donated to Apache?

If you use the Oracle one, you need to have an Oracle license,
and then you can ask on Oracle forums (or contact Oracle
support) about upgrade and migration paths.  This is Apache land
over here, and it's not appropriate for us to use this forum to discuss
proprietary software upgrade paths.  This e-mail list in particular
is to discuss the ADF Faces incubation in Apache, not the
Oracle-branded version of the software.

> 6. When will the entire APIs be "public" with complete API
> documentation?

There will never be a time when all the Java code is public;  again,
this is standard industry practice with some part of a codebase
as publicly useable APIs, and others internal-only code.

The key point is that in the ADF codebase, we explicitly
state which parts can be depended on, and which parts
cannot be.  We provide API documentation for the parts
that can be depended on.

-- Adam


>
>
> Thanks,
> Arti
>
> -----Original Message-----
> From: Adam Winer [mailto:awiner@gmail.com]
> Sent: Friday, March 31, 2006 8:54 PM
> To: adffaces-user@incubator.apache.org
> Subject: Re: API Documentation for "oracle.adfinternal.view.faces"
> package
>
> Arti,
>
> We don't generate docs for adfinternal because it is explicitly not part
> of our public API - these classes are subject to arbitrary change and
> are therefore considered "off-limits" for extension.  For example,
> everything under:
>
>   oracle.adfinternal.view.faces.ui
> and
>   oracle.adfinternal.view.faces.uinode
> ... is code that needs to be rewritten inside of:
>   oracle.adfinternal.view.faces.renderkit
> ... and then deleted.
>
> One of the planned projects is extracting a public API out of the
> renderkit package (e.g., the AdfRenderingContext and CoreRenderer
> classes), and moving them to the public API as part of
> oracle.adf.view.faces (or, rather, whatever org.apache package we end up
> in), at which point they're publicly supported and documented.
>
> In the meantime, you're free to subclass or use anything inside
> oracle.adfinternal, but only on the understanding that your code *will*
> break at some point;  features you were relying on might just disappear
> without any replacement, etc.
>
> -- Adam
>
> On 3/31/06, arti <arti@tambas.at> wrote:
> > Hi,
> >
> > ADF Faces API documentation does not include
> > "oracle.adfinternal.view.faces" package classes. I checked the online
> > version also.
> > I need it for writing custom components & renderers.
> >
> > Does anyone know why? Where should we get it from?
> >
> > Thanks,
> > Arti
> >
> >
>
>
>
>

Mime
View raw message