TreeConstants API

An annotation processor that builds constant trees

License

License

Categories

Categories

Ant Build Tools
GroupId

GroupId

com.github.cilki
ArtifactId

ArtifactId

tree-constants-api
Last Version

Last Version

1.0.2
Release Date

Release Date

Type

Type

jar
Description

Description

TreeConstants API
An annotation processor that builds constant trees
Project URL

Project URL

https://github.com/cilki/TreeConstants
Source Code Management

Source Code Management

https://github.com/cilki/TreeConstants

Download tree-constants-api

How to add to project

<!-- https://jarcasting.com/artifacts/com.github.cilki/tree-constants-api/ -->
<dependency>
    <groupId>com.github.cilki</groupId>
    <artifactId>tree-constants-api</artifactId>
    <version>1.0.2</version>
</dependency>
// https://jarcasting.com/artifacts/com.github.cilki/tree-constants-api/
implementation 'com.github.cilki:tree-constants-api:1.0.2'
// https://jarcasting.com/artifacts/com.github.cilki/tree-constants-api/
implementation ("com.github.cilki:tree-constants-api:1.0.2")
'com.github.cilki:tree-constants-api:jar:1.0.2'
<dependency org="com.github.cilki" name="tree-constants-api" rev="1.0.2">
  <artifact name="tree-constants-api" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.github.cilki', module='tree-constants-api', version='1.0.2')
)
libraryDependencies += "com.github.cilki" % "tree-constants-api" % "1.0.2"
[com.github.cilki/tree-constants-api "1.0.2"]

Dependencies

There are no dependencies for this project. It is a standalone project that does not depend on any other jars.

Project Modules

There are no modules declared in this project.

License Maven central Build Status

TreeConstants is a simple annotation processor that can turn occurances of string literals in code (like "java.io.tmpdir" or "ui.view.main") into refactorable, typo-safe, documentable field references.

The sole objective of TreeConstants is to transform calls like this:

System.getProperty("java.io.tmpdir");

into calls like this:

System.getProperty(java.io.tmpdir);

The annotation processor creates two nested classes (java.io) and a field (tmpdir). Your code can then use java.io.tmpdir exactly as "java.io.tmpdir" without caring where the class hierarchy actually resides. Since javac automatically inlines static final fields, there's zero runtime performance impact from using TreeConstants. To prove the point, the classes generated by the annotation processor don't even need to be included in your resulting artifact (since they will never be loaded anyway).

Here are some advantages of using TreeConstants:

  • Compile-time typo detection
  • Autocompletion and documentation support within IDEs
  • Allows for more powerful refactoring operations than find-and-replace for string literals

Here are some disadvantages of using TreeConstants:

  • Eclipse doesn't fully support Gradle annotation processors yet (apply net.ltgt.apt-eclipse plugin in the meantime)
  • Although runtime isn't affected, the build process will be slowed down by the annotation processor

Custom Constant Trees

java.io.tmpdir was just an illustrative example. The real utility of TreeConstants is defining your own constants:

/**
 * The current view type.
 */
@TreeConstant
private static final String ui_view_main = "ui.view.main";

/**
 * The filesystem read permission.
 */
@TreeConstant
private static final int permission_fs_read = 102;

This example shows that any static final field can become a tree constant by annotating it with @TreeConstant. The underscore-separated name of the field determines the tree structure (so ui_view_main will become ui.view.main). The field's value will replace all references to the tree constant in code.

Gradle Usage

To include TreeConstants in a Gradle project, add the following dependencies to your build.gradle:

// Contains the @TreeConstant annotation
compileOnly 'com.github.cilki:tree-constants-api:+'

// The annotation processor
annotationProcessor 'com.github.cilki:tree-constants:+'

Or if you just want a set of tree constants for the JDK (like "java.io.tmpdir" and so on):

compileOnly 'com.github.cilki:tree-constants-common:+'

Versions

Version
1.0.2
1.0.1
1.0.0