You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@druid.apache.org by Gian Merlino <gi...@imply.io> on 2018/03/30 20:58:15 UTC
Re: [druid-dev] Questions about Public API
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
dev@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
On Thu, Mar 29, 2018 at 5:45 PM, Jihoon Son <ji...@apache.org> wrote:
> 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
>
> --
> 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-6JSdqARh3SRRVWCgoSVpK3Z48rqUhO
> TuqS-x3w%40mail.gmail.com
> <https://groups.google.com/d/msgid/druid-development/CACZfFK4_xEG-6JSdqARh3SRRVWCgoSVpK3Z48rqUhOTuqS-x3w%40mail.gmail.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>
Re: [druid-dev] Questions about Public API
Posted by Gian Merlino <gi...@apache.org>.
I cross-posted my reply, so this thread is on both lists now.
On Fri, Mar 30, 2018 at 3:32 PM, Jihoon Son <gh...@gmail.com> wrote:
> Thanks.
>
> Should I send this email to the Apache mailing list as well?
>
> Jihoon
>
> 2018년 3월 30일 (금) 오후 1:58, Gian Merlino <gi...@imply.io>님이 작성:
>
> > 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
> > dev@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
> >
> > On Thu, Mar 29, 2018 at 5:45 PM, Jihoon Son <ji...@apache.org>
> wrote:
> >
> >> 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
> >>
> >> --
> >> 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
> >> <https://groups.google.com/d/msgid/druid-development/CACZfFK4_xEG-
> 6JSdqARh3SRRVWCgoSVpK3Z48rqUhOTuqS-x3w%40mail.gmail.com?utm_
> medium=email&utm_source=footer>
> >> .
> >> 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-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/
> CACZNdYAPj7o4DF3AekgM1Bv77gQV5f6JWikknjtZM5x4QtT2ng%40mail.gmail.com
> > <https://groups.google.com/d/msgid/druid-development/
> CACZNdYAPj7o4DF3AekgM1Bv77gQV5f6JWikknjtZM5x4QtT2ng%40mail.
> gmail.com?utm_medium=email&utm_source=footer>
> > .
> > For more options, visit https://groups.google.com/d/optout.
> >
>
Re: [druid-dev] Questions about Public API
Posted by Jihoon Son <gh...@gmail.com>.
Thanks.
Should I send this email to the Apache mailing list as well?
Jihoon
2018년 3월 30일 (금) 오후 1:58, Gian Merlino <gi...@imply.io>님이 작성:
> 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
> dev@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
>
> On Thu, Mar 29, 2018 at 5:45 PM, Jihoon Son <ji...@apache.org> wrote:
>
>> 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
>>
>> --
>> 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
>> <https://groups.google.com/d/msgid/druid-development/CACZfFK4_xEG-6JSdqARh3SRRVWCgoSVpK3Z48rqUhOTuqS-x3w%40mail.gmail.com?utm_medium=email&utm_source=footer>
>> .
>> 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-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/CACZNdYAPj7o4DF3AekgM1Bv77gQV5f6JWikknjtZM5x4QtT2ng%40mail.gmail.com
> <https://groups.google.com/d/msgid/druid-development/CACZNdYAPj7o4DF3AekgM1Bv77gQV5f6JWikknjtZM5x4QtT2ng%40mail.gmail.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>