File and Package Management

/**
 * A Java file containing a single top level class.
 */
public final class JavaFile {
    // Public fields
    public final CodeBlock fileComment;
    public final String packageName;
    public final TypeSpec typeSpec;
    public final boolean skipJavaLangImports;
    
    // Static factory method
    public static Builder builder(String packageName, TypeSpec typeSpec);
    
    // Writing methods
    public void writeTo(Appendable out) throws IOException;
    public void writeTo(Path directory) throws IOException;
    public void writeTo(Path directory, Charset charset) throws IOException;
    public Path writeToPath(Path directory) throws IOException;
    public Path writeToPath(Path directory, Charset charset) throws IOException;
    public void writeTo(File directory) throws IOException;
    public File writeToFile(File directory) throws IOException;
    public void writeTo(Filer filer) throws IOException;
    
    // Conversion methods
    public JavaFileObject toJavaFileObject();
    public Builder toBuilder();
    
    // Standard object methods
    public boolean equals(Object o);
    public int hashCode();
    public String toString();
}

import com.squareup.javapoet.*;
import javax.lang.model.element.Modifier;

// Create a simple class
TypeSpec myClass = TypeSpec.classBuilder("MyClass")
    .addModifiers(Modifier.PUBLIC)
    .build();

// Create Java file
JavaFile javaFile = JavaFile.builder("com.example", myClass)
    .addFileComment("Generated code - do not modify")
    .build();

// Write to string
String sourceCode = javaFile.toString();

// Write to file system
javaFile.writeTo(Paths.get("src/main/java"));

// Write to annotation processing Filer
javaFile.writeTo(processingEnv.getFiler());

public static final class Builder {
    // Static import management
    public Builder addStaticImport(Enum<?> constant);
    public Builder addStaticImport(Class<?> clazz, String... names);
    public Builder addStaticImport(ClassName className, String... names);
    
    // File configuration
    public Builder addFileComment(String format, Object... args);
    public Builder skipJavaLangImports(boolean skipJavaLangImports);
    public Builder indent(String indent);
    
    // Build method
    public JavaFile build();
}

// Configure file with static imports and comments
JavaFile javaFile = JavaFile.builder("com.example", typeSpec)
    .addFileComment("Auto-generated on $L", new Date())
    .addStaticImport(Collections.class, "emptyList", "singletonList")
    .addStaticImport(Assert.class, "*")
    .skipJavaLangImports(true)
    .indent("    ") // 4 spaces instead of default 2
    .build();

// Static import for enum constants
JavaFile builderFile = JavaFile.builder("com.example", builderClass)
    .addStaticImport(Modifier.PUBLIC)
    .addStaticImport(Modifier.STATIC)
    .build();

// Write to System.out
javaFile.writeTo(System.out);

// Write to any Appendable
StringBuilder buffer = new StringBuilder();
javaFile.writeTo(buffer);

// Write to directory using standard Java package structure
javaFile.writeTo(Paths.get("src/main/java"));

// Write with specific charset
javaFile.writeTo(Paths.get("src/main/java"), StandardCharsets.UTF_8);

// Write and get the actual output path
Path outputPath = javaFile.writeToPath(Paths.get("src/main/java"));
System.out.println("Wrote to: " + outputPath);

// Legacy File API
javaFile.writeTo(new File("src/main/java"));
File outputFile = javaFile.writeToFile(new File("src/main/java"));

// Write using javax.annotation.processing.Filer
@Override
public boolean process(Set<? extends TypeElement> annotations, 
                      RoundEnvironment roundEnv) {
    try {
        javaFile.writeTo(processingEnv.getFiler());
    } catch (IOException e) {
        processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, 
            "Failed to write generated file: " + e.getMessage());
    }
    return true;
}

// Convert to JavaFileObject for compiler integration
JavaFileObject fileObject = javaFile.toJavaFileObject();

// Use with JavaCompiler
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
StandardJavaFileManager fileManager = compiler.getStandardFileManager(null, null, null);
Iterable<? extends JavaFileObject> compilationUnits = Arrays.asList(fileObject);
compiler.getTask(null, fileManager, null, null, null, compilationUnits).call();

// Types are automatically imported
MethodSpec method = MethodSpec.methodBuilder("process")
    .addParameter(List.class, "items")
    .addParameter(Map.class, "config")
    .returns(Optional.class)
    .addStatement("$T result = new $T<>()", ArrayList.class, ArrayList.class)
    .addStatement("return $T.of(result)", Optional.class)
    .build();

// Generated imports:
// import java.util.List;
// import java.util.Map;
// import java.util.Optional;
// import java.util.ArrayList;

// Add static imports for cleaner code
JavaFile.builder("com.example", typeSpec)
    .addStaticImport(Collections.class, "emptyList")
    .addStaticImport(Assertions.class, "*")
    .build();

// Results in:
// import static java.util.Collections.emptyList;
// import static org.junit.jupiter.api.Assertions.*;

// Skip java.lang imports (default behavior includes them)
JavaFile.builder("com.example", typeSpec)
    .skipJavaLangImports(true)
    .build();

// Without skipJavaLangImports: import java.lang.String;
// With skipJavaLangImports: String used without import

// Add file-level comments
JavaFile.builder("com.example", typeSpec)
    .addFileComment("This file was auto-generated on $L", Instant.now())
    .addFileComment("")
    .addFileComment("Copyright (c) $L Example Corp", Year.now().getValue())
    .addFileComment("All rights reserved.")
    .build();

// Generates:
/*
 * This file was auto-generated on 2023-10-15T14:30:00Z
 *
 * Copyright (c) 2023 Example Corp
 * All rights reserved.
 */