Forge Roaster API

Forge Roaster is a library for inspecting and manipulating Java types.

License

License

Categories

Categories

JBoss Container Application Servers
GroupId

GroupId

org.jboss.forge
ArtifactId

ArtifactId

roaster-api
Last Version

Last Version

2.0.0.Final
Release Date

Release Date

Type

Type

jar
Description

Description

Forge Roaster API
Forge Roaster is a library for inspecting and manipulating Java types.
Project Organization

Project Organization

JBoss by Red Hat

Download roaster-api

How to add to project

<!-- https://jarcasting.com/artifacts/org.jboss.forge/roaster-api/ -->
<dependency>
    <groupId>org.jboss.forge</groupId>
    <artifactId>roaster-api</artifactId>
    <version>2.0.0.Final</version>
</dependency>
// https://jarcasting.com/artifacts/org.jboss.forge/roaster-api/
implementation 'org.jboss.forge:roaster-api:2.0.0.Final'
// https://jarcasting.com/artifacts/org.jboss.forge/roaster-api/
implementation ("org.jboss.forge:roaster-api:2.0.0.Final")
'org.jboss.forge:roaster-api:jar:2.0.0.Final'
<dependency org="org.jboss.forge" name="roaster-api" rev="2.0.0.Final">
  <artifact name="roaster-api" type="jar" />
</dependency>
@Grapes(
@Grab(group='org.jboss.forge', module='roaster-api', version='2.0.0.Final')
)
libraryDependencies += "org.jboss.forge" % "roaster-api" % "2.0.0.Final"
[org.jboss.forge/roaster-api "2.0.0.Final"]

Dependencies

test (1)

Group / Artifact Type Version
junit : junit jar 4.11

Project Modules

There are no modules declared in this project.

Roaster - The only Java source parser library you’ll ever need

Actions Status License Maven Central

Roaster (formerly known as java-parser) is a library that allows easy parsing and formatting of java source files. Roaster introduces a fluent interface to manipulate Java source files, like adding fields, methods, annotations and so on.

Installation

  • If you are using Maven, add the following dependencies to your project:

<properties>
  <version.roaster>2.22.2.Final</version.roaster>
</properties>

<dependency>
  <groupId>org.jboss.forge.roaster</groupId>
  <artifactId>roaster-api</artifactId>
  <version>${version.roaster}</version>
</dependency>
<dependency>
  <groupId>org.jboss.forge.roaster</groupId>
  <artifactId>roaster-jdt</artifactId>
  <version>${version.roaster}</version>
  <scope>runtime</scope>
</dependency>
  • Otherwise, download and extract (or build from sources) the most recent distribution containing the Roaster distribution and command line tools

Usage

CLI

Execute roaster by running the following script (add these to your $PATH for convenience):

bin/roaster     (Unix/Linux/OSX)
bin/roaster.bat (Windows)

Options described here:

$ roaster -h

Usage: roaster [OPTION]... FILES ...
The fastest way to build applications, share your software, and enjoy doing it.

-c, --config [CONFIG_FILE]
	 specify the path to the Eclipse code format profile (usually found at '$PROJECT/.settings/org.eclipse.jdt.core.prefs')

-r, --recursive
	 format files in found sub-directories recursively

FILES...
	 specify one or more space-separated files or directories to format

-h, --help
	 display this help and exit

Java Parser API

Example:

Roaster.parse(JavaClassSource.class, "public class HelloWorld {}");

Java Source Code Generation API

Roaster provides a fluent API to generate java classes. Here an example:

final JavaClassSource javaClass = Roaster.create(JavaClassSource.class);
javaClass.setPackage("com.company.example").setName("Person");

javaClass.addInterface(Serializable.class);
javaClass.addField()
  .setName("serialVersionUID")
  .setType("long")
  .setLiteralInitializer("1L")
  .setPrivate()
  .setStatic(true)
  .setFinal(true);

javaClass.addProperty(Integer.class, "id").setMutable(false);
javaClass.addProperty(String.class, "firstName");
javaClass.addProperty("String", "lastName");

javaClass.addMethod()
  .setConstructor(true)
  .setPublic()
  .setBody("this.id = id;")
  .addParameter(Integer.class, "id");

Will produce:

package com.company.example;

import java.io.Serializable;

public class Person implements Serializable {

   private static final long serialVersionUID = 1L;
   private final Integer id;
   private String firstName;
   private String lastName;

   public Integer getId() {
      return id;
   }

   public String getFirstName() {
      return firstName;
   }

   public void setFirstName(String firstName) {
      this.firstName = firstName;
   }

   public String getLastName() {
      return lastName;
   }

   public void setLastName(String lastName) {
      this.lastName = lastName;
   }

   public Person(Integer id) {
      this.id = id;
   }
}

Java Source Code Modification API

Of course it is possible to mix both approaches (parser and writer) to modify Java code programmatically:

JavaClassSource javaClass =
  Roaster.parse(JavaClassSource.class, "public class SomeClass {}");
javaClass.addMethod()
  .setPublic()
  .setStatic(true)
  .setName("main")
  .setReturnTypeVoid()
  .setBody("System.out.println(\"Hello World\");")
  .addParameter("java.lang.String[]", "args");
System.out.println(javaClass);

JavaDoc creation and parsing

Here is an example on how to add JavaDoc to a class:

JavaClassSource javaClass =
  Roaster.parse(JavaClassSource.class, "public class SomeClass {}");
JavaDocSource javaDoc = javaClass.getJavaDoc();

javaDoc.setFullText("Full class documentation");
// or
javaDoc.setText("Class documentation text");
javaDoc.addTagValue("@author","George Gastaldi");

System.out.println(javaClass);

Formatting the Java Source Code

Roaster formats the Java Source Code by calling the format() method:

String javaCode = "public class MyClass{ private String field;}";
String formattedCode = Roaster.format(javaCode);
System.out.println(formattedCode);

Parsing the java unit

The Java Language Specification allows you to define multiple classes in the same .java file. Roaster supports parsing the entire unit by calling the parseUnit() method:

String javaCode = "public class MyClass{ private String field;} public class AnotherClass {}";

JavaUnit unit = Roaster.parseUnit(javaCode);

JavaClassSource myClass = unit.getGoverningType();
JavaClassSource anotherClass = (JavaClassSource) unit.getTopLevelTypes().get(1);

Validate Code Snippets

Roaster validates Java snippets and reports as Problem objects by calling the validateSnippet() method:

Example:

List<Problem> problem = Roaster.validateSnippet("public class HelloWorld {}");
// problem.size() == 0

List<Problem> problem = Roaster.validateSnippet("public class MyClass {");
// problem.size() == 1 containing a new Problem("Syntax error, insert \"}\" to complete ClassBody", 21, 21, 1)

Building from sources

Just run mvn clean install to build the sources

Issue tracker

ROASTER on JBossDeveloper. You might need to log in, in order to view the issues.

Get in touch

Roaster uses the same forum and mailing lists as the JBoss Forge project. See the JBoss Forge Community page.

Related / Similar projects

For the writer part:

License

org.jboss.forge

JBoss Forge

JBoss Forge is a software development tool that extends your Java IDE, providing wizards and extensions (add-ons) for different technologies and solutions

Versions

Version
2.0.0.Final