Skip to content

add public/internal/spi annotations - #411

Merged
andimarek merged 2 commits into
masterfrom
public-internal-api
May 8, 2017
Merged

andimarek merged 2 commits into
masterfrom
public-internal-api

Conversation

@andimarek

Copy link
Copy Markdown
Member

This is a first idea how we could handle #284:

There are three different Annotations:
-@PublicApi for public classes/methods/interfaces.

  • @PrivateApi for private stuff
  • @PublicSpi for public interfaces/abstract classes which users are expected to implement.

@bbakerman

Copy link
Copy Markdown
Member

Naming is hard.

I would use @internal rather than @internalapi

Also I think we should consider @experimentalapi and ExperimentalSpi. This allows you to stage new code without the super strong commitment.

@bbakerman bbakerman left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should put some README evidence of the API policy

eg: contructors marked as @internal may be changed without notice. Do not use them, use their builders instead etc...

import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;

@Retention(RetentionPolicy.RUNTIME)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding

java.lang.annotation.Documented

@documented

import static java.lang.annotation.ElementType.CONSTRUCTOR;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider @documented

@InternalApi
public GraphQL(GraphQLSchema graphQLSchema, ExecutionStrategy queryStrategy, ExecutionStrategy mutationStrategy, ExecutionStrategy subscriptionStrategy) {
this(graphQLSchema, queryStrategy, mutationStrategy, subscriptionStrategy, DEFAULT_EXECUTION_ID_PROVIDER, NoOpInstrumentation.INSTANCE);
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In 4.0 we should remove deprecations.

@andimarek
andimarek force-pushed the public-internal-api branch from 5aa6abc to 9b10764 Compare May 8, 2017 05:22
@andimarek
andimarek force-pushed the public-internal-api branch from 9b10764 to e700c9c Compare May 8, 2017 05:29
@andimarek

Copy link
Copy Markdown
Member Author

@bbakerman Changed it to @Internal add added @Documented.

I am not really sure about the "rules" where to put these annotations: I added the on the class/interface, but not on every method. I quietly assume that every method is public or internal if the type itself is so. If this is not the case I added a extra annotation: for example the constructor is marked as internal, but the class itself is public.

@bbakerman

Copy link
Copy Markdown
Member

Yeah I think you put them on the class and then IF you want to make an exemption, you put that into the method.

The typical ones will be constructors. By making them @internal you allow them to be expanded over time without breaking API. The builders are how people should construct them and hence we can default values there etc..

@andimarek

Copy link
Copy Markdown
Member Author

It is a first start: we will add new annotations before 3.0.0

@andimarek
andimarek merged commit 7242973 into master May 8, 2017
@andimarek andimarek added this to the 3.0.0 milestone May 8, 2017
@andimarek
andimarek deleted the public-internal-api branch May 13, 2017 07:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants