@informaticon/web.compiler v2.14.3

web.compiler

A precompiler to run, compile and update (multi-layered) web projects.

Requirements

1. Current version of SBT
2. Current version of watchman

Compatibility

Note: See Contributing for compatibility while developing.

Usage

In most modern web projects utilizing version 2+, wompiler does not need to be executed manually. Projects integrating the web.compiler.plugin SBT Plugin will start wompiler automatically as part of the Play! Run-Hook.

For a full list of commands please execute the wompiler --help command.

Note For creating a distributable package, you should use sbt dist instead of wompiler dist if your project uses the web.compiler.plugin plugin.

Note about wompiler clean

This will delete the following directories or files relative to your current working directory.
Wompiler will not check whether you are located in a valid project. It also will not validate the type of file it deletes (file / directory).

Limitations

Annotations

No extends clause is permitted in Java annotation types. Therefore, they cannot be overridden in the traditional sense.
See Java Language Specification - Chapter 9.6.

Create a layered type like public @interface MyAnnotationL1 {..} anyway, because wompiler copies the members of the highest layer to the mirror. This means that if you "override" an annotation using wompiler, you have to copy the member declarations from all other layers! When you add a new member, it must have a default value so that the usages of the annotation in the code of the other layers are not broken.

Ebean Models

Ebean Model classes are handled in a different way from other java classes. The code of all layers including fields, constructors, and methods are copied to the mirror instead of the mirror class extending from the highest layer class. The reason is that ebean doesn't handle fields of parent classes. The Ebean Model compiler is limitted in the following ways:

• Generic Supertype: Nested generic supertypes are not supported
  OK: public class XyzL2 extends SuperModel<Abc>
  Bad: public class XyzL2 extends SuperModel<List<String>>
• Method and Constructor Annotations: Only repeatable or the following marker annotations are supported when the annotation is repeated on the overridden method in further layers. Using a non-marker variant of one of the following annotations or any other annotation might lead to a compiler error stating that a non-repeatable annotation was repeated in the mirror class.
  Supported annotations are: @Override, @Nonnull, @Nullable, @CheckReturnValue, @CheckForNull, @Deprecated, @Transactional
  OK: @Nonnull @Override public void test()
  Bad: @Nonnull(when = When.MAYBE) @Override public void test()
• Super Calls: Calling super(...) or super.method(...) only has a defined behaviour in the constructor or method that overrides the excact super method to call.
  OK:

  public void test() {
    super.test();
  }

  Bad:

  public void test() {
    super.doSomething();
  }

Contributing

Note: Building the project requires Node 16 or 18. Running and debugging should still work with Node 14.

If you want to contribute to the wompiler project, follow the steps below.

1. Clone the Repository
2. Run npm i to install dependencies
3. Implement your fixes or features on a separate branch
4. Test your code
5. Build the project: npm run build (requires Node 16 or 18)
6. Change directories to a web project you can test your changes with
7. Run your local wompiler with: node <PATH-TO-WOMPILER-PROJECT>\dist\cli.js <command>\ eg. node C:\Java\rb_web\web.compiler\dist\cli.js precompile
8. Commit your changes
9. Open a Pull Request on GitHub

Release

Only create a new release if your changes have been reviewed and merged into master/next.

1. Update version and automatically create git tag\ npm version (major|minor|patch) on master\ or npm version (premajor|preminor|prepatch|prerelease) --preid=rc on next
2. Push the newly created tag\ git push origin --tags