Questions about Public API

[Jihoon Son]

Hi folks,

I wonder what's the exact meaning of the 'PublicApi' annotation. From https://github.com/druid-io/druid/pull/4433, 

> @PublicApi which signifies something you're not meant to subclass, but that you can use for implementation.

I can also see some methods can't be deleted because they are in some classes annotated with @PublicApi. Here is an example in TaskRunner.

/**

 * Start the state of the runner.

 *

 * This method is unused, but TaskRunner is {@link PublicApi}, so we cannot remove it.

 */

@SuppressWarnings("unused")

void start();

Does this mean @PublicApi classes must change in a backward-compatible way? Or can we change in a non-compatible way and call out when we release?

If this is not defined yet, it would be good to start a discussion on this.

Best,

Jihoon

[Gian Merlino]

Hi Jihoon,

The javadoc for @PublicApi explains the intent. They can change, but not in a minor release. There should also

be some consensus around changing them. Once we are 1.0, then we should only change PublicApis when going

to 2.0.

Btw, since we are trying to migrate the dev mailing list to Apache, please cross post this sort of thing with

d...@druid.incubator.apache.org, or even only post to that list.

From the javadoc:

> Signifies that the annotated entity is a public API for extension authors. Public APIs may change in breaking ways

> only between major Druid release lines (e.g. 0.10.x -> 0.11.0), but otherwise must remain stable. Public APIs may

> change at any time in non-breaking ways, however, such as by adding new fields, methods, or constructors.

> 

> Note that interfaces annotated with {@code PublicApi} but not with {@link ExtensionPoint} are not meant to be

> subclassed in extensions. In this case, the annotation simply signifies that the interface is stable for callers.

> In particular, since it is not meant to be subclassed, new non-default methods may be added to an interface and

> new abstract methods may be added to a class.

> 

> If a class or interface is annotated, then all public and protected fields, methods, and constructors that class

> or interface are considered stable in this sense. If a class is not annotated, but an individual field, method, or

> constructor is annotated, then only that particular field, method, or constructor is considered a public API.

> 

> Classes, fields, method, and constructors _not_ annotated with {@code @PublicApi} may be modified or removed

> in any Druid release, unless they are annotated with {@link ExtensionPoint} (which implies they are a public API

> as well).

Gian

--
You received this message because you are subscribed to the Google Groups "Druid Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to druid-development+unsubscribe@googlegroups.com.
To post to this group, send email to druid-development@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/druid-development/CACZfFK4_xEG-6JSdqARh3SRRVWCgoSVpK3Z48rqUhOTuqS-x3w%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Jihoon Son]

Thanks.

Should I send this email to the Apache mailing list as well?

Jihoon

2018년 3월 30일 (금) 오후 1:58, Gian Merlino <gi...@imply.io>님이 작성:

To unsubscribe from this group and stop receiving emails from it, send an email to druid-developm...@googlegroups.com.
To post to this group, send email to druid-de...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/druid-development/CACZfFK4_xEG-6JSdqARh3SRRVWCgoSVpK3Z48rqUhOTuqS-x3w%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to the Google Groups "Druid Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to druid-developm...@googlegroups.com.
To post to this group, send email to druid-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/druid-development/CACZNdYAPj7o4DF3AekgM1Bv77gQV5f6JWikknjtZM5x4QtT2ng%40mail.gmail.com.