[DISCUSS] Discussion on the capability boundaries and facade API style of the new module fesod-doc

[bengbengbalabalabeng]

Background

Source: https://lists.apache.org/thread/y67yzt1bhbrxq61m9hhlgg1ook45h6yw

Word document processing is an extremely high-frequency requirement in report generation, document creation, and data export. To ensure that the new fesod-doc module continues the excellent development experience, I would like to first discuss the capability boundaries and facade API style of this module.

Capability boundaries and format support

1. Format support (.docx/.doc)

It is recommended to focus solely on .docx for now (as the OOXML format has a natural advantage in node positioning for template filling) to keep the module lightweight and modern.

2. Read/Write priority

It is recommended to prioritize support for "template filling and custom writing" (as this covers the vast majority of common scenarios), while structured reading and parsing can be left for later gradual implementation.

Facade API style

I have envisioned the following API styles:

1. A fully fluent-style API

// for custom writing

FesodDoc.write(pathname)
		// global configure
		.configure(spec -> {
			spec.page(p -> p.size(A4))
				.header(h -> h.text("this is header"))
				.footer(f -> f.text("this is footer").pagination(...))
				.style(s -> s.fontSize(24))
		})
		// paragraph configure
		// or .paragraph("Title", DocStyles.STYLE_TITLE)
		// or .paragraph("Heading 1", DocStyles.STYLE_HEADING_1)
		// or .paragraph("content. Use the global default style")
		.paragraph("Title", s -> s.bold().fontSize(24).align(CENTER))
		.paragraph(spec -> {
			spec.text("This is content.", s -> s.fontSize(16)).break()
				.image(image_pathname, s -> s.size(width, height))
				.links("https://fesod.apache.org")
		})
		// inline-table configure
		.table(TableModel.class, List<TableModel>)
		.table(table -> {
			table.head(HeadBuilder.forSimple("ID", "Name"))
				 .body(List<?>)
		})
		.doWrite();

@DocTableHeadStyle(...)
@DocTableContentStyle(...)
public class TableModel {
	
	@DocTableProperty("ID")
	private Integer id;

	@DocTableProperty("Name")
	private String name;

	// Getter & Setter
}


// template filling
FesodDoc.write(pathname, TemplateModel.class)
		.withTemplate(template_pathname)
		.configure(spec -> {
			// placeholder: My name is {{name}}.
			spec.startDelimiter("{{").endDelimiter("}}")
				// or
				// .templateRenderer(TemplateRenderer)
		})
		.registerRenderPolicy(RenderPolicy)
		.registerConverter(Converter)
		// or
		// .doWrite(Map<String, Object>)
		.doWrite(TemplateModel);


public class TemplateModel {
	
	@DocProperty(render = TextRenderPolicy.class)
	private String name;

	@DocProperty(value = "created_time", converter = LocalDateTimeStringConverter.class)
	private LocalDateTime dateTime;

	@DocProperty(render = ItemsRenderPolicy.class)
	private List<String> items;

	@DocTable
	private List<TableModel> table;

	// Getter & Setter
}

2. Builders-style API

// for custom writing

// global configure builder
DocConfigure config = DocConfigure.builder().pageSize(A4).header(...).build();

try (DocWriter writer = FesodDoc.write(pathname).configure(config).build()) {
	// paragraph builder
	DocParagraph p1 = FesodDoc.writeParagraph()
							 .text("Title")
							 .style(DocStyles.STYLE_TITLE)
							 .build();

	DocItem i1 = FesodDoc.writeItem().text("This is content1.").build();
	DocItem i2 = FesodDoc.writeItem().text("This is content2.").break().build();

	DocImage image = FesodDoc.writeImage(image_pathname).build();
	DocItem i3 = FesodDoc.writeItem().image(image).build();

	// rendered
	// This is content1.This is content2.\n
	// Image
	DocParagraph p2 = FesodDoc.writeParagraph(i1, i2, i3)
							 .style(DocStyles.bold().fontSize(16))
							 .build();

	// inline-table builder
	DocTable t = FesodDoc.writeTable()
							 .head(HeadBuilder.forSimple("ID", "Name")
							 .body(List<?>)
							 .registerWriteHandler(Handler)
							 .build();

	// or
	// writer.add(p1);
	// writer.add(p2);
	writer.addAll(p1, p2, t);

	// auto close && writer.finish()
}

3. Mixed API (1 + 2)

For simple linear documents, use the fluent API for processing. For highly complex custom layouts, use the builders API to process in chunks.

NOTE: The above methods, functions, and annotation names are only for style description and design reference, and are not the final API.

These are some of my initial thoughts. Looking forward to any thoughts or suggestions.