Builder refactor

CHANGELOG.md

@@ -7,8 +7,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 ## [Unreleased]
 
 ### Added
+- Added `string()` convenience method to all DocumentContent builders for creating paragraphs with simple text content
 
 ### Changed
+- Refactored DocumentContent builders to use shared interface, reducing code duplication and improving consistency
+- Standardized string-handling methods: deprecated `content(String)` in favor of `string(String)` for clarity
 
 ### Fixed
 

migration-library/src/main/kotlin/com/quadient/migration/api/dto/migrationmodel/builder/DocumentContentBuilderBase.kt

@@ -0,0 +1,123 @@
+package com.quadient.migration.api.dto.migrationmodel.builder
+
+import com.quadient.migration.api.dto.migrationmodel.DisplayRuleRef
+import com.quadient.migration.api.dto.migrationmodel.DocumentContent
+import com.quadient.migration.api.dto.migrationmodel.DocumentObjectRef
+import com.quadient.migration.api.dto.migrationmodel.ImageRef
+import com.quadient.migration.api.dto.migrationmodel.builder.documentcontent.SelectByLanguageBuilder
+
+/**
+ * Base interface for builders that contain a list of DocumentContent.
+ * Provides standard methods for adding various types of document content.
+ */
+@Suppress("UNCHECKED_CAST")
+interface DocumentContentBuilderBase<T> {
+    /**
+     * The mutable list of document content.
+     * Implementing classes must provide this property.
+     */
+    val content: MutableList<DocumentContent>
+
+    /**
+     * Replaces all content with a single DocumentContent item.
+     * @param content The content to set.
+     * @return This builder instance for method chaining.
+     */
+    fun content(content: DocumentContent): T = apply {
+        this.content.clear()
+        this.content.add(content)
+    } as T
+
+    /**
+     * Replaces all content with multiple DocumentContent items.
+     * @param content The list of content to set.
+     * @return This builder instance for method chaining.
+     */
+    fun content(content: List<DocumentContent>): T = apply {
+        this.content.clear()
+        this.content.addAll(content)
+    } as T
+
+    /**
+     * Appends a DocumentContent item to the existing content.
+     * @param content The content to append.
+     * @return This builder instance for method chaining.
+     */
+    fun appendContent(content: DocumentContent): T = apply {
+        this.content.add(content)
+    } as T
+
+    /**
+     * Adds a paragraph to the content using a builder function.
+     * @param builder A builder function to build the paragraph.
+     * @return This builder instance for method chaining.
+     */
+    fun paragraph(builder: ParagraphBuilder.() -> Unit): T = apply {
+        this.content.add(ParagraphBuilder().apply(builder).build())
+    } as T
+
+    /**
+     * Adds a table to the content using a builder function.
+     * @param builder A builder function to build the table.
+     * @return This builder instance for method chaining.
+     */
+    fun table(builder: TableBuilder.() -> Unit): T = apply {
+        this.content.add(TableBuilder().apply(builder).build())
+    } as T
+
+    /**
+     * Adds an image reference to the content.
+     * @param imageId The ID of the image to reference.
+     * @return This builder instance for method chaining.
+     */
+    fun imageRef(imageId: String): T = apply {
+        this.content.add(ImageRef(imageId))
+    } as T
+
+    /**
+     * Adds a document object reference to the content.
+     * @param documentObjectId The ID of the document object to reference.
+     * @return This builder instance for method chaining.
+     */
+    fun documentObjectRef(documentObjectId: String): T = apply {
+        this.content.add(DocumentObjectRef(documentObjectId, null))
+    } as T
+
+    /**
+     * Adds a conditional document object reference to the content.
+     * @param documentObjectId The ID of the document object to reference.
+     * @param displayRuleId The ID of the display rule.
+     * @return This builder instance for method chaining.
+     */
+    fun documentObjectRef(documentObjectId: String, displayRuleId: String): T = apply {
+        this.content.add(DocumentObjectRef(documentObjectId, DisplayRuleRef(displayRuleId)))
+    } as T
+
+    /**
+     * Adds a first match block to the content using a builder function.
+     * @param builder A builder function to build the first match block.
+     * @return This builder instance for method chaining.
+     */
+    fun firstMatch(builder: FirstMatchBuilder.() -> Unit): T = apply {
+        this.content.add(FirstMatchBuilder().apply(builder).build())
+    } as T
+
+    /**
+     * Adds a select by language block to the content using a builder function.
+     * @param builder A builder function to build the select by language block.
+     * @return This builder instance for method chaining.
+     */
+    fun selectByLanguage(builder: SelectByLanguageBuilder.() -> Unit): T = apply {
+        this.content.add(SelectByLanguageBuilder().apply(builder).build())
+    } as T
+
+    /**
+     * Adds a paragraph with the given string to the content (convenience method).
+     * Creates: Paragraph → Text → StringValue
+     * @param text The string to add in a paragraph.
+     * @return This builder instance for method chaining.
+     */
+    fun string(text: String): T = apply {
+        this.content.add(ParagraphBuilder().string(text).build())
+    } as T
+}

migration-library/src/main/kotlin/com/quadient/migration/api/dto/migrationmodel/builder/DocumentObjectBuilder.kt

@@ -3,19 +3,16 @@ package com.quadient.migration.api.dto.migrationmodel.builder
 import com.quadient.migration.api.dto.migrationmodel.DisplayRuleRef
 import com.quadient.migration.api.dto.migrationmodel.DocumentContent
 import com.quadient.migration.api.dto.migrationmodel.DocumentObject
-import com.quadient.migration.api.dto.migrationmodel.DocumentObjectRef
-import com.quadient.migration.api.dto.migrationmodel.ImageRef
 import com.quadient.migration.api.dto.migrationmodel.VariableStructureRef
 import com.quadient.migration.api.dto.migrationmodel.builder.documentcontent.AreaBuilder
-import com.quadient.migration.api.dto.migrationmodel.builder.documentcontent.SelectByLanguageBuilder
 import com.quadient.migration.shared.DocumentObjectOptions
 import com.quadient.migration.shared.DocumentObjectType
 import com.quadient.migration.shared.MetadataPrimitive
 import com.quadient.migration.shared.SkipOptions
 
 class DocumentObjectBuilder(id: String, private val type: DocumentObjectType) :
-    DtoBuilderBase<DocumentObject, DocumentObjectBuilder>(id) {
-    private var content: List<DocumentContent> = mutableListOf()
+    DtoBuilderBase<DocumentObject, DocumentObjectBuilder>(id), DocumentContentBuilderBase<DocumentObjectBuilder> {
+    override val content: MutableList<DocumentContent> = mutableListOf()
     private var internal: Boolean = false
     private var targetFolder: String? = null
     private var displayRuleRef: DisplayRuleRef? = null
@@ -27,13 +24,6 @@ class DocumentObjectBuilder(id: String, private val type: DocumentObjectType) :
     private var placeholder: String? = null
     private var reason: String? = null
 
-    /**
-     * Replace content of the document object.
-     * @param content List of [DocumentContent] to set as the content of the document object.
-     * @return This builder instance for method chaining.
-     */
-    fun content(content: List<DocumentContent>) = apply { this.content = content }
-
     /**
      * Set whether the document object is internal. Internal objects do not create a separate
      * file in the target system.
@@ -48,24 +38,28 @@ class DocumentObjectBuilder(id: String, private val type: DocumentObjectType) :
      * @return This builder instance for method chaining.
      */
     fun targetFolder(targetFolder: String) = apply { this.targetFolder = targetFolder }
+
     /**
      * Add display rule to this document object.
      * @param id ID of the display rule to reference.
      * @return This builder instance for method chaining.
      */
     fun displayRuleRef(id: String) = apply { this.displayRuleRef = DisplayRuleRef(id) }
+
     /**
      * Add display rule to this document object.
      * @param ref Reference to the display rule.
      * @return This builder instance for method chaining.
      */
     fun displayRuleRef(ref: DisplayRuleRef) = apply { this.displayRuleRef = ref }
+
     /**
      * Add a reference to a variable structure to this document object.
      * @param id ID of the variable structure to reference.
      * @return This builder instance for method chaining.
      */
     fun variableStructureRef(id: String) = apply { this.variableStructureRef = VariableStructureRef(id) }
+
     /**
      * Override the default base template for this document object.
      * @param baseTemplate Path to the base template to use for this document object.
@@ -81,99 +75,12 @@ class DocumentObjectBuilder(id: String, private val type: DocumentObjectType) :
     fun options(options: DocumentObjectOptions) = apply { this.options = options }
 
     /**
-     * Add an area to the document object.
+     * Add an area to the document object (only for Page-type documents).
      * @param builder Builder function where receiver is a [AreaBuilder].
      * @return This builder instance for method chaining.
      */
     fun area(builder: AreaBuilder.() -> Unit) = apply {
-        val areaBuilder = AreaBuilder().apply(builder)
-        content = content + areaBuilder.build()
-    }
-
-    /**
-     * Add a paragraph to the document object.
-     * @param builder Builder function where receiver is a [ParagraphBuilder].
-     * @return This builder instance for method chaining.
-     */
-    fun paragraph(builder: ParagraphBuilder.() -> Unit) = apply {
-        val paragraphBuilder = ParagraphBuilder().apply(builder)
-        content = content + paragraphBuilder.build()
-    }
-
-    /**
-     * Add a table to the document object.
-     * @param builder Builder function where receiver is a [TableBuilder].
-     * @return This builder instance for method chaining.
-     */
-    fun table(builder: TableBuilder.() -> Unit) = apply {
-        val tableBuilder = TableBuilder().apply(builder)
-        content = content + tableBuilder.build()
-    }
-
-    /**
-     * Add a first match block to the document object
-     * @param builder Builder function where receiver is a [FirstMatchBuilder].
-     * @return This builder instance for method chaining.
-     */
-    fun firstMatch(builder: FirstMatchBuilder.() -> Unit) = apply {
-        val firstMatchBuilder = FirstMatchBuilder().apply (builder)
-        content = content + firstMatchBuilder.build()
-    }
-
-    /**
-     * Add a select by language block to the document object
-     * @param builder Builder function where receiver is a [SelectByLanguageBuilder].
-     * @return This builder instance for method chaining.
-     */
-    fun selectByLanguage(builder: SelectByLanguageBuilder.() -> Unit) = apply {
-        val selectByLanguageBuilder = SelectByLanguageBuilder().apply (builder)
-        content = content + selectByLanguageBuilder.build()
-    }
-
-    /**
-     * Add a reference to an image to the document object
-     * @param imageRef ID of the image to reference.
-     * @return This builder instance for method chaining.
-     */
-    fun imageRef(imageRef: String) = apply {
-        imageRef(ImageRef(imageRef))
-    }
-
-    /**
-     * Add a reference to an image to the document object
-     * @param ref Reference to the image.
-     * @return This builder instance for method chaining.
-     */
-    fun imageRef(ref: ImageRef) = apply {
-        content = content + ref
-    }
-
-    /**
-     * Add a reference to another document object to the document object.
-     * @param documentObjectId ID of the document object to reference.
-     * @return This builder instance for method chaining.
-     */
-    fun documentObjectRef(documentObjectId: String) = apply {
-        documentObjectRef(DocumentObjectRef(documentObjectId))
-    }
-
-    /**
-     * Add a reference to another document object to the document object.
-     * @param documentObjectId ID of the document object to reference.
-     * @param displayRuleId ID of the display rule to reference.
-     * @return This builder instance for method chaining.
-     */
-    fun documentObjectRef(documentObjectId: String, displayRuleId: String) = apply {
-        documentObjectRef(DocumentObjectRef(documentObjectId, DisplayRuleRef(displayRuleId)))
-    }
-
-    /**
-     * Add a reference to another document object to the document object.
-     * @param ref Reference to the document object.
-     * @return This builder instance for method chaining.
-     */
-    fun documentObjectRef(ref: DocumentObjectRef) = apply {
-        content = content + ref
+        content.add(AreaBuilder().apply(builder).build())
     }
 
     /**

migration-library/src/main/kotlin/com/quadient/migration/api/dto/migrationmodel/builder/ParagraphStyleBuilder.kt

@@ -12,8 +12,8 @@ import com.quadient.migration.shared.Size
 class ParagraphStyleBuilder(id: String) : DtoBuilderBase<ParagraphStyle, ParagraphStyleBuilder>(id) {
     var definition: ParagraphStyleDefOrRef? = null
 
-    fun definition(builder: ParagraphStyleDefinitionBuilder.() -> ParagraphStyleDefinitionBuilder) = apply {
-        this.definition = builder(ParagraphStyleDefinitionBuilder()).build()
+    fun definition(builder: ParagraphStyleDefinitionBuilder.() -> Unit) = apply {
+        this.definition = ParagraphStyleDefinitionBuilder().apply(builder).build()
     }
 
     fun definition(definition: ParagraphStyleDefinition) = apply { this.definition = definition }

migration-library/src/main/kotlin/com/quadient/migration/api/dto/migrationmodel/builder/TextStyleBuilder.kt

@@ -11,8 +11,8 @@ import com.quadient.migration.shared.SuperOrSubscript
 class TextStyleBuilder(id: String) : DtoBuilderBase<TextStyle, TextStyleBuilder>(id) {
     var definition: TextStyleDefOrRef? = null
 
-    fun definition(builder: TextStyleDefinitionBuilder.() -> TextStyleDefinitionBuilder) = apply {
-        this.definition = builder(TextStyleDefinitionBuilder()).build()
+    fun definition(builder: TextStyleDefinitionBuilder.() -> Unit) = apply {
+        this.definition = TextStyleDefinitionBuilder().apply(builder).build()
     }
 
     fun definition(definition: TextStyleDefinition) = apply { this.definition = definition }