tessl/maven-com-palantir-javapoet--javapoet
JavaPoet is a Java API for generating .java source files programmatically with support for modern Java features including records and sealed types
java-files.mddocs/
Java Files
JavaFile represents a complete Java source file with package declaration, imports, and a single top-level type. It automatically manages imports and provides methods to write the generated file to various outputs.
Capabilities
Creating Java Files
Creates a JavaFile builder for a package and type specification.
/**
* Creates a builder for a Java source file
* @param packageName - The package name for the file
* @param typeSpec - The top-level type specification
* @return Builder for configuring the Java file
*/
static JavaFile.Builder builder(String packageName, TypeSpec typeSpec);Usage Example:
TypeSpec myClass = TypeSpec.classBuilder("MyClass")
.addModifiers(Modifier.PUBLIC)
.build();
JavaFile javaFile = JavaFile.builder("com.example", myClass)
.build();Writing to Output
Write the Java file to various output destinations.
/**
* Writes the Java file to an Appendable (e.g., StringBuilder, Writer)
* @param out - The Appendable to write to
* @throws IOException if writing fails
*/
void writeTo(Appendable out) throws IOException;
/**
* Writes the Java file to a directory (creates subdirectories for package)
* @param directory - The root directory for writing
* @throws IOException if writing fails
*/
void writeTo(File directory) throws IOException;
/**
* Writes the Java file to a Path directory
* @param directory - The root directory path
* @throws IOException if writing fails
*/
void writeTo(Path directory) throws IOException;
/**
* Writes the Java file to a Path directory with specified charset
* @param directory - The root directory path
* @param charset - The character encoding to use
* @throws IOException if writing fails
*/
void writeTo(Path directory, Charset charset) throws IOException;
/**
* Writes the Java file using an annotation processor Filer
* @param filer - The Filer from annotation processing environment
* @throws IOException if writing fails
*/
void writeTo(Filer filer) throws IOException;
/**
* Writes the Java file to a directory and returns the created File
* @param directory - The root directory for writing
* @return The created File object
* @throws IOException if writing fails
*/
File writeToFile(File directory) throws IOException;
/**
* Writes the Java file to a Path directory and returns the created Path
* @param directory - The root directory path
* @return The created Path object
* @throws IOException if writing fails
*/
Path writeToPath(Path directory) throws IOException;
/**
* Writes the Java file to a Path directory with charset and returns the created Path
* @param directory - The root directory path
* @param charset - The character encoding to use
* @return The created Path object
* @throws IOException if writing fails
*/
Path writeToPath(Path directory, Charset charset) throws IOException;Usage Examples:
JavaFile javaFile = JavaFile.builder("com.example", typeSpec).build();
// Write to System.out
javaFile.writeTo(System.out);
// Write to file system
javaFile.writeTo(new File("src/main/java"));
// Write to Path
javaFile.writeTo(Paths.get("src/main/java"));
// Get as string
String code = javaFile.toString();
// Use in annotation processor
javaFile.writeTo(processingEnv.getFiler());Converting to String
Get the Java file content as a string.
/**
* Returns the Java file content as a formatted string
* @return The complete Java source code
*/
String toString();Converting to JavaFileObject
Convert to a JavaFileObject for use in annotation processing.
/**
* Converts to a JavaFileObject for use with Java compiler API
* @return JavaFileObject representation of this file
*/
JavaFileObject toJavaFileObject();Accessing File Properties
Access the package name and type specification of the file.
/**
* Returns the package name of this Java file
* @return The package name
*/
String packageName();
/**
* Returns the top-level type specification
* @return The TypeSpec for this file
*/
TypeSpec typeSpec();Modifying Java Files
Convert to a builder for modification.
/**
* Creates a builder initialized with this file's properties
* @return Builder for modifying this JavaFile
*/
JavaFile.Builder toBuilder();JavaFile.Builder
The builder for configuring JavaFile instances.
Adding File Comments
Add comments at the top of the Java file (before package declaration).
/**
* Adds a file-level comment (appears before package declaration)
* @param format - Format string for the comment
* @param args - Arguments for format placeholders
* @return This builder for chaining
*/
JavaFile.Builder addFileComment(String format, Object... args);Usage Example:
JavaFile javaFile = JavaFile.builder("com.example", typeSpec)
.addFileComment("Generated by MyCodeGen")
.addFileComment("Date: $L", LocalDate.now())
.build();Adding Static Imports
Add static imports to the file.
/**
* Adds a static import for an enum constant
* @param constant - The enum constant to import
* @return This builder for chaining
*/
JavaFile.Builder addStaticImport(Enum<?> constant);
/**
* Adds static imports for specific members of a class
* @param clazz - The class to import from
* @param names - The member names to import
* @return This builder for chaining
*/
JavaFile.Builder addStaticImport(Class<?> clazz, String... names);
/**
* Adds static imports for specific members of a class by ClassName
* @param className - The class name to import from
* @param names - The member names to import
* @return This builder for chaining
*/
JavaFile.Builder addStaticImport(ClassName className, String... names);Usage Examples:
JavaFile javaFile = JavaFile.builder("com.example", typeSpec)
.addStaticImport(Collections.class, "emptyList", "singletonList")
.addStaticImport(ClassName.get("com.example", "Utils"), "*")
.build();Configuring Import Behavior
Control whether to skip imports from java.lang package.
/**
* Controls whether to skip imports from java.lang package
* @param skipJavaLangImports - true to skip java.lang imports
* @return This builder for chaining
*/
JavaFile.Builder skipJavaLangImports(boolean skipJavaLangImports);Configuring Indentation
Set the indentation string (default is two spaces).
/**
* Sets the indentation string for the generated code
* @param indent - The indentation string (e.g., " ", " ", "\t")
* @return This builder for chaining
*/
JavaFile.Builder indent(String indent);Usage Example:
JavaFile javaFile = JavaFile.builder("com.example", typeSpec)
.indent(" ") // Use 4 spaces
.build();Building the JavaFile
Build the final JavaFile instance.
/**
* Builds the JavaFile with configured properties
* @return The built JavaFile instance
*/
JavaFile build();Advanced: JavaFileObject Interface Methods
JavaFile implements the JavaFileObject interface for integration with annotation processors and the Java compiler. The toJavaFileObject() method returns an inner class that provides these low-level file operations. Most users should use the writeTo() methods instead.
/**
* Returns the character content of the JavaFile
* @param _ignoreEncodingErrors - Whether to ignore encoding errors (parameter ignored)
* @return String representation of the Java source file
*/
String getCharContent(boolean _ignoreEncodingErrors);
/**
* Opens an input stream to read the file content
* @return InputStream containing the UTF-8 encoded source
*/
InputStream openInputStream();
/**
* Returns the last modification time
* @return Timestamp when the JavaFileObject was created
*/
long getLastModified();
/**
* Appends character sequence (from Appendable interface)
* @param _charSequence - The character sequence to append
* @return This appendable
*/
Appendable append(CharSequence _charSequence);
/**
* Appends portion of character sequence (from Appendable interface)
* @param _charSequence - The character sequence
* @param _start - Start index
* @param _end - End index
* @return This appendable
*/
Appendable append(CharSequence _charSequence, int _start, int _end);
/**
* Appends a single character (from Appendable interface)
* @param _c - The character to append
* @return This appendable
*/
Appendable append(char _c);Note: These methods are part of the JavaFileObject interface implementation. They are used internally when JavaFile is passed to annotation processors via the Filer API. Normal users should prefer the writeTo() methods for writing Java files to disk or other outputs.
Types
class JavaFile {
static Builder builder(String packageName, TypeSpec typeSpec);
String packageName();
TypeSpec typeSpec();
void writeTo(Appendable out) throws IOException;
void writeTo(File directory) throws IOException;
void writeTo(Path directory) throws IOException;
void writeTo(Path directory, Charset charset) throws IOException;
void writeTo(Filer filer) throws IOException;
File writeToFile(File directory) throws IOException;
Path writeToPath(Path directory) throws IOException;
Path writeToPath(Path directory, Charset charset) throws IOException;
String toString();
JavaFileObject toJavaFileObject();
Builder toBuilder();
boolean equals(Object o);
int hashCode();
// JavaFileObject interface methods (rarely used directly - prefer writeTo methods)
String getCharContent(boolean _ignoreEncodingErrors);
InputStream openInputStream();
long getLastModified();
Appendable append(CharSequence _charSequence);
Appendable append(CharSequence _charSequence, int _start, int _end);
Appendable append(char _c);
}
class JavaFile.Builder {
JavaFile.Builder addFileComment(String format, Object... args);
JavaFile.Builder addStaticImport(Enum<?> constant);
JavaFile.Builder addStaticImport(Class<?> clazz, String... names);
JavaFile.Builder addStaticImport(ClassName className, String... names);
JavaFile.Builder skipJavaLangImports(boolean skipJavaLangImports);
JavaFile.Builder indent(String indent);
JavaFile build();
}Install with Tessl CLI
npx tessl i tessl/maven-com-palantir-javapoet--javapoet@0.11.0docs