What is Astra?

Astra is a Java tool for analysing and refactoring Java source code.

For example:

• "References to type A should instead reference type B"
• "Callers of method A should add an additional argument B"
• "Find classes which are annotated with A"

Astra has been developed and tested at Alfa to improve the velocity at which large scale refactors may be performed.

How do I use Astra?

• First, please see the Wiki!
• Astra can be run as part of a Java application, using astra-core as a dependency and using the refactors it provides. For an illustration of how to do this, please see the README in astra-core. The code can be found in astra-example.
• For cases needing a more bespoke approach, astra-core also provides an SPI for writing your own custom ASTOperations. See the astra-core README for further details.
• For very simple cases, there is also a command line interface which exposes a small subset of Astra's refactoring operations. Please see astra-cli for more information.
• Astra can also be run as a plugin during your build e.g. mvn org.alfasoftware:astra-maven-plugin:2.4.2:refactor -Dastra.usecase=org.my.MyUseCase though this requires MyUseCase to be available on your classpath. Therefore it is often better to amend your pom so that Astra can be used when needed and the UseCase can be retrieved from a separate library e.g.

      <build>
        <plugins>
          <plugin>
            <groupId>org.alfasoftware</groupId>
            <artifactId>astra-maven-plugin</artifactId>
            <version>2.4.2</version>
            <dependencies>
              <dependency>
                <groupId>org.yourcompany</groupId>
                <artifactId>usecase-library</artifactId>
                <version>1.0.0</version>
              </dependency>
            </dependencies>          
          </plugin>  		
        </plugins>
      </build>
  

  Then, as the plugin and version is defined, you can simply invoke mvn astra:refactor -Dastra.usecase=org.my.MyUseCase

Why would I use Astra?

A simple and common use case is renaming a method, and updating all the callers of that method so that they use the new name. Your IDE is often the best tool for the job, but sometimes this isn't possible. There may be so many modules that manually selecting and opening them is a real pain, or the overall size of the modules may mean that your IDE struggles to open them all at once. This means that sometimes it's easier to just add a new method, deprecate the old one, and leave all the existing callers. The same issues apply to many other refactors, such as renaming a type.

Astra can be used to make changes like these easily, and on a massive scale.

How does Astra work?

Please see How does Astra work? in the Wiki.

Technologies

• Java 11
• Eclipse JDT
• JUnit
• log4j

License

Astra is released under the Apache 2.0 License. Contributions are also made under this license, as per the GitHub terms of service.