CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-squareup--javapoet

Java API for generating .java source files programmatically with fluent builder interfaces.

—

Pending
Overview
Eval results
Files

code-specifications.mddocs/

Code Structure Specifications

Builders for creating Java language constructs including classes, interfaces, enums, methods, fields, parameters, and annotations. All specifications use the Builder pattern for fluent construction.

Capabilities

TypeSpec

Specification for creating classes, interfaces, enums, and annotations. Handles modifiers, inheritance, generic type parameters, and member declarations.

/**
 * Specification for creating types (classes, interfaces, enums, annotations)
 */
public final class TypeSpec {
    // Nested enum for type kinds
    public enum Kind {
        CLASS, INTERFACE, ENUM, ANNOTATION
    }
    
    // Public fields
    public final Kind kind;
    public final String name;
    public final CodeBlock anonymousTypeArguments;
    public final CodeBlock javadoc;
    public final List<AnnotationSpec> annotations;
    public final Set<Modifier> modifiers;
    public final List<TypeVariableName> typeVariables;
    public final TypeName superclass;
    public final List<TypeName> superinterfaces;
    public final Map<String, TypeSpec> enumConstants;
    public final List<FieldSpec> fieldSpecs;
    public final CodeBlock staticBlock;
    public final CodeBlock initializerBlock;
    public final List<MethodSpec> methodSpecs;
    public final List<TypeSpec> typeSpecs;
    public final List<Element> originatingElements;
    public final Set<String> alwaysQualifiedNames;
    
    // Static factory methods
    public static Builder classBuilder(String name);
    public static Builder classBuilder(ClassName className);
    public static Builder interfaceBuilder(String name);
    public static Builder interfaceBuilder(ClassName className);
    public static Builder enumBuilder(String name);
    public static Builder enumBuilder(ClassName className);
    public static Builder anonymousClassBuilder(String typeArgumentsFormat, Object... args);
    public static Builder anonymousClassBuilder(CodeBlock typeArguments);
    public static Builder annotationBuilder(String name);
    public static Builder annotationBuilder(ClassName className);
    
    // Instance methods
    public boolean hasModifier(Modifier modifier);
    public Builder toBuilder();
    public boolean equals(Object o);
    public int hashCode();
    public String toString();
}

Usage Examples:

// Create a simple class
TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
    .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
    .build();

// Create an interface
TypeSpec processor = TypeSpec.interfaceBuilder("DataProcessor")
    .addModifiers(Modifier.PUBLIC)
    .addTypeVariable(TypeVariableName.get("T"))
    .addMethod(MethodSpec.methodBuilder("process")
        .addModifiers(Modifier.PUBLIC, Modifier.ABSTRACT)
        .addParameter(TypeVariableName.get("T"), "data")
        .returns(TypeVariableName.get("T"))
        .build())
    .build();

// Create an enum
TypeSpec status = TypeSpec.enumBuilder("Status")
    .addModifiers(Modifier.PUBLIC)
    .addEnumConstant("PENDING")
    .addEnumConstant("PROCESSING") 
    .addEnumConstant("COMPLETED")
    .addEnumConstant("FAILED")
    .build();

// Create an annotation
TypeSpec documented = TypeSpec.annotationBuilder("Documented")
    .addModifiers(Modifier.PUBLIC)
    .addMethod(MethodSpec.methodBuilder("value")
        .addModifiers(Modifier.PUBLIC, Modifier.ABSTRACT)
        .returns(String.class)
        .defaultValue("$S", "")
        .build())
    .build();

MethodSpec

Specification for creating methods and constructors with parameters, return types, exceptions, and method bodies.

/**
 * Specification for creating methods and constructors
 */
public final class MethodSpec {
    // Static constant for constructor name
    public static final String CONSTRUCTOR = "<init>";
    
    // Public fields
    public final String name;
    public final CodeBlock javadoc;
    public final List<AnnotationSpec> annotations;
    public final Set<Modifier> modifiers;
    public final List<TypeVariableName> typeVariables;
    public final TypeName returnType;
    public final List<ParameterSpec> parameters;
    public final boolean varargs;
    public final List<TypeName> exceptions;
    public final CodeBlock code;
    public final CodeBlock defaultValue;
    
    // Static factory methods
    public static Builder methodBuilder(String name);
    public static Builder constructorBuilder();
    public static Builder overriding(ExecutableElement method);
    public static Builder overriding(ExecutableElement method, DeclaredType enclosing, Types types);
    
    // Instance methods
    public boolean hasModifier(Modifier modifier);
    public boolean isConstructor();
    public Builder toBuilder();
    public boolean equals(Object o);
    public int hashCode();
    public String toString();
}

Usage Examples:

// Simple method
MethodSpec toString = MethodSpec.methodBuilder("toString")
    .addAnnotation(Override.class)
    .addModifiers(Modifier.PUBLIC)
    .returns(String.class)
    .addStatement("return $S", "Hello World")
    .build();

// Method with parameters and exceptions
MethodSpec processFile = MethodSpec.methodBuilder("processFile")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .addParameter(Path.class, "file")
    .addParameter(boolean.class, "createBackup")
    .returns(void.class)
    .addException(IOException.class)
    .addException(IllegalArgumentException.class)
    .addStatement("// Implementation here")
    .build();

// Constructor
MethodSpec constructor = MethodSpec.constructorBuilder()
    .addModifiers(Modifier.PUBLIC)
    .addParameter(String.class, "name")
    .addParameter(int.class, "age")
    .addStatement("this.name = $N", "name")
    .addStatement("this.age = $N", "age")
    .build();

// Generic method
MethodSpec genericMethod = MethodSpec.methodBuilder("transform")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .addTypeVariable(TypeVariableName.get("T"))
    .addTypeVariable(TypeVariableName.get("R"))
    .addParameter(ParameterizedTypeName.get(List.class, TypeVariableName.get("T")), "input")
    .addParameter(ParameterizedTypeName.get(Function.class, TypeVariableName.get("T"), TypeVariableName.get("R")), "mapper")
    .returns(ParameterizedTypeName.get(List.class, TypeVariableName.get("R")))
    .addStatement("return input.stream().map(mapper).collect($T.toList())", Collectors.class)
    .build();

// Varargs method
MethodSpec format = MethodSpec.methodBuilder("format")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .returns(String.class)
    .addParameter(String.class, "template")
    .addParameter(ArrayTypeName.of(Object.class), "args")
    .varargs()
    .addStatement("return $T.format(template, args)", String.class)
    .build();

FieldSpec

Specification for creating class fields with types, modifiers, and initializers.

/**
 * Specification for creating fields
 */
public final class FieldSpec {
    // Public fields
    public final TypeName type;
    public final String name;
    public final CodeBlock javadoc;
    public final List<AnnotationSpec> annotations;
    public final Set<Modifier> modifiers;
    public final CodeBlock initializer;
    
    // Static factory methods
    public static Builder builder(TypeName type, String name, Modifier... modifiers);
    public static Builder builder(Type type, String name, Modifier... modifiers);
    
    // Instance methods
    public boolean hasModifier(Modifier modifier);
    public Builder toBuilder();
    public boolean equals(Object o);
    public int hashCode();
    public String toString();
}

Usage Examples:

// Simple field
FieldSpec name = FieldSpec.builder(String.class, "name")
    .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
    .build();

// Field with initializer
FieldSpec count = FieldSpec.builder(int.class, "count")
    .addModifiers(Modifier.PRIVATE)
    .initializer("0")
    .build();

// Static constant
FieldSpec maxSize = FieldSpec.builder(int.class, "MAX_SIZE")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC, Modifier.FINAL)
    .initializer("$L", 1000)
    .build();

// Complex initializer
FieldSpec items = FieldSpec.builder(
        ParameterizedTypeName.get(List.class, String.class), "items")
    .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
    .initializer("new $T<>()", ArrayList.class)
    .build();

// Field with annotation
FieldSpec injected = FieldSpec.builder(DataService.class, "dataService")
    .addModifiers(Modifier.PRIVATE)
    .addAnnotation(Inject.class)
    .build();

// Field with Javadoc
FieldSpec documented = FieldSpec.builder(String.class, "value")
    .addModifiers(Modifier.PRIVATE)
    .addJavadoc("The current value being processed.\n")
    .addJavadoc("@see #getValue()\n")
    .build();

ParameterSpec

Specification for creating method and constructor parameters with types, names, and modifiers.

/**
 * Specification for creating parameters
 */
public final class ParameterSpec {
    // Public fields
    public final String name;
    public final List<AnnotationSpec> annotations;
    public final Set<Modifier> modifiers;
    public final TypeName type;
    public final CodeBlock javadoc;
    
    // Static factory methods
    public static ParameterSpec get(VariableElement element);
    public static Builder builder(TypeName type, String name, Modifier... modifiers);
    public static Builder builder(Type type, String name, Modifier... modifiers);
    
    // Instance methods
    public boolean hasModifier(Modifier modifier);
    public Builder toBuilder();
    public boolean equals(Object o);
    public int hashCode();
    public String toString();
}

Usage Examples:

// Simple parameter
ParameterSpec name = ParameterSpec.builder(String.class, "name").build();

// Final parameter
ParameterSpec finalParam = ParameterSpec.builder(int.class, "value")
    .addModifiers(Modifier.FINAL)
    .build();

// Annotated parameter
ParameterSpec nullable = ParameterSpec.builder(String.class, "input")
    .addAnnotation(Nullable.class)
    .build();

// Generic parameter
ParameterSpec items = ParameterSpec.builder(
        ParameterizedTypeName.get(List.class, WildcardTypeName.subtypeOf(Object.class)), 
        "items")
    .build();

// Using in method
MethodSpec method = MethodSpec.methodBuilder("process")
    .addParameter(ParameterSpec.builder(String.class, "input")
        .addAnnotation(NonNull.class)
        .addModifiers(Modifier.FINAL)
        .build())
    .addParameter(boolean.class, "validate")
    .build();

AnnotationSpec

Specification for creating annotations with member values.

/**
 * Specification for creating annotations
 */
public final class AnnotationSpec {
    // Public fields
    public final TypeName type;
    public final Map<String, List<CodeBlock>> members;
    
    // Static factory methods
    public static AnnotationSpec get(Annotation annotation);
    public static AnnotationSpec get(Annotation annotation, boolean includeDefaultValues);
    public static AnnotationSpec get(AnnotationMirror annotation);
    public static Builder builder(ClassName type);
    public static Builder builder(Class<?> type);
    
    // Instance methods
    public Builder toBuilder();
    public boolean equals(Object o);
    public int hashCode();
    public String toString();
}

Usage Examples:

// Simple annotation
AnnotationSpec override = AnnotationSpec.builder(Override.class).build();

// Annotation with single value
AnnotationSpec suppressWarnings = AnnotationSpec.builder(SuppressWarnings.class)
    .addMember("value", "$S", "unchecked")
    .build();

// Annotation with multiple values
AnnotationSpec requestMapping = AnnotationSpec.builder(RequestMapping.class)
    .addMember("value", "$S", "/api/users")
    .addMember("method", "$T.GET", RequestMethod.class)
    .addMember("produces", "$S", "application/json")
    .build();

// Annotation with array values
AnnotationSpec multiValue = AnnotationSpec.builder(MyAnnotation.class)
    .addMember("values", "$S", "first")
    .addMember("values", "$S", "second")
    .addMember("values", "$S", "third")
    .build();

// Complex annotation with nested annotations
AnnotationSpec headers = AnnotationSpec.builder(Headers.class)
    .addMember("value", "$L", AnnotationSpec.builder(Header.class)
        .addMember("name", "$S", "Accept")
        .addMember("value", "$S", "application/json")
        .build())
    .build();

// From existing annotation instance
@Deprecated
class ExistingClass { }

Annotation deprecatedAnnotation = ExistingClass.class.getAnnotation(Deprecated.class);
AnnotationSpec spec = AnnotationSpec.get(deprecatedAnnotation);

Builder Patterns and Fluent APIs

All specification builders provide fluent method chaining:

// Complex class with multiple members
TypeSpec userService = TypeSpec.classBuilder("UserService")
    .addModifiers(Modifier.PUBLIC)
    .addAnnotation(Service.class)
    .addJavadoc("Service for managing user operations.\n")
    .addJavadoc("@author Generated Code\n")
    .addField(FieldSpec.builder(UserRepository.class, "repository")
        .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
        .addAnnotation(Inject.class)
        .build())
    .addMethod(MethodSpec.constructorBuilder()
        .addModifiers(Modifier.PUBLIC)
        .addParameter(UserRepository.class, "repository")
        .addStatement("this.repository = repository")
        .build())
    .addMethod(MethodSpec.methodBuilder("findById")
        .addModifiers(Modifier.PUBLIC)
        .addParameter(Long.class, "id")
        .returns(ParameterizedTypeName.get(Optional.class, User.class))
        .addStatement("return repository.findById(id)")
        .build())
    .build();

Modifier Handling

All specifications support Java modifiers:

// Checking for modifiers
if (methodSpec.hasModifier(Modifier.STATIC)) {
    // Handle static method
}

// Common modifier combinations
Set<Modifier> publicStatic = EnumSet.of(Modifier.PUBLIC, Modifier.STATIC);
Set<Modifier> privateFinal = EnumSet.of(Modifier.PRIVATE, Modifier.FINAL);

// Modifier usage in builders
MethodSpec.methodBuilder("utility")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC, Modifier.FINAL)
    .build();

Install with Tessl CLI

npx tessl i tessl/maven-com-squareup--javapoet

docs

advanced-types.md

code-generation.md

code-specifications.md

file-management.md

index.md

type-system.md

tile.json