Skip to content

CodeAPI 4

Jump to bottom
JonathanxD edited this page Apr 22, 2017 · 8 revisions

This page describes the changes of CodeAPI 4. I'm writting this because CodeAPI 4 will receive a lot of features during its development, there is no release date and the CodeAPI 4 will grow as needed. Snapshots of CodeAPI 4 may be stable and backward compatible, but compatibility is not guaranted.

Backward incompatibilities

  • Builder, the change probably breaks codes written to CodeAPI 3.

Development releases

We will periodically release nightlies and snapshots.

  • Nightlies: Unstable builds. This is not recommended to be used in production, nightly features are subject to change (and probably will be changed in the next nightly or snapshot)

  • Snapshots: Subject to be stable, and probably have more standardized features. We do not guarantee that these features will change before the release.

Features before first snapshot

Builders

We are introducing builder classes implementation on top of Java Proxy, after a bunch of tries, I decided to write builder implementation on top of Proxy instead of concrete classes because the builder generator system of CodeAPI 3 is not public, then you can not contribute to the project since you are not able to generate builders for your classes. We planned to use BuilderGenerator, which is public and intended to be used in CodeAPI, but because of some problems that we found during implementation - kapt generating methods that is not needed, problems with wildcard that will be hard to resolve because kotlin generate strange java stubs (why Kotlin generate a method returning a List<CodePart> for properties of type List<? extends CodePart>?!, obs: it is not allowed in Java) - I decided to write a Proxy and cache Method to avoid method lookup.

I know, after reading that, probably a cloud with a question appeared in your mind: Why do not hand-write builders?

A:

  • I hate boilerplate code, and Java does not help.
  • I don't want to waste my time writting builder, I prefer to use this time to to implement things and fix issues.
  • Builders, I don't know if I hate them or love them, the same obstacle appeared in CodeAPI 3 (pseudo-setters to builder), this is a problem of extensible data structure.
  • Avoid duplicated code.

If you have a better solution, open an issue and let me take a look

Anonymous classes

Yeah, finally anonymous classes.

Dynamic invocation

We will change the way you create dynamic invocations. (at this moment this is only what I can say).

Types change and CodeType Resolution

This is described in #54 and #55.

You do not need to wrap all Class instances into a CodeType using CodeAPI.getJavaType (which only exists for historical reasons) or CodeTypes.getCodeType. All Type will be converted to a CodeType internally.

We also introduced isAssignableFrom, getSuperclass, getInterfaces and a CodeTypeResolver which can resolve a CodeType to any type (Mainly to a Class or a TypeElement, but can be used to translate to any type). Obs: isAssignableFrom, getSuperclass and getInterfaces depends on the CodeTypeResolver.

Validation

I'm not sure how this will be, but this will add validation of CodeAPI structures, some validations will be added directly to init of the CodePart others validations will be made by a class (extensible). See issue #47

Features after first snapshot

Generator changes

More changes on generator, I do not like the way that the generators works, I want a better code, with a better performance.

All generators will be visitor-like and will have overloaded methods for each CodeAPI base types. (We will not remove ability to register custom types, but it will be made in a different way).

Performance improvements

I'm always looking for performance improvements, but I don't like premature optimizations, then I need to profile the code and analyze it strictly to find which parts need improvements (I think that Java itself need improvements).

Builder Information

If you are migrating from 3.0, in 4.0 builders are provided by a BuilderProvider (accessible from CodeAPI.getBuilderProvider()), to get a builder instance call BuilderProvider.get with the type of builder, for example:

AnnotationDeclaration.Builder<AnnotationDeclaration, ?> builder = CodeAPI.getBuilderProvider().get(AnnotationDeclaration.Builder.class);

Probably the IDE will warn about unchecked assignment, I know about that, this is a problem with Java generics, to avoid this warning you could also call AnnotationDeclaration.Builder.Companion.builder method:

AnnotationDeclaration.Builder.Companion.builder()

I will try to resolve this issue later, at the moment features and improvements are priority.

More info later

Clone this wiki locally