001/*
002 * Copyright 2025 devteam@scivicslab.com
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing,
011 * software distributed under the License is distributed on an
012 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
013 * either express or implied.  See the License for the
014 * specific language governing permissions and limitations
015 * under the License.
016 */
017
018package com.scivicslab.actoriac.report;
019
020/**
021 * POJO interface for section builders.
022 *
023 * <p>This is a pure POJO interface - it does NOT extend {@code CallableByActionName}.
024 * Each section builder POJO should be wrapped by a corresponding IIAR class that
025 * exposes actions via {@code @Action} annotations.</p>
026 *
027 * <h2>Design principle:</h2>
028 * <ul>
029 *   <li>POJO contains business logic only</li>
030 *   <li>IIAR handles String argument parsing and action dispatch</li>
031 *   <li>This separation enables distributed actor messaging (messages are always strings)</li>
032 * </ul>
033 *
034 * <h2>Example:</h2>
035 * <pre>{@code
036 * // POJO - pure business logic
037 * public class WorkflowNameSection implements SectionBuilder {
038 *     public String generate() {
039 *         return "[Workflow Name]\n" + workflowName + "\n";
040 *     }
041 * }
042 *
043 * // IIAR - action dispatch
044 * public class WorkflowNameSectionIIAR extends IIActorRef<WorkflowNameSection> {
045 *     @Action("generate")
046 *     public ActionResult generate(String args) {
047 *         return new ActionResult(true, object.generate());
048 *     }
049 * }
050 * }</pre>
051 *
052 * @author devteam@scivicslab.com
053 * @since 2.16.0
054 */
055public interface SectionBuilder {
056
057    /**
058     * Generates the section content.
059     *
060     * @return the section content as a string
061     */
062    String generate();
063
064    /**
065     * Returns the section title.
066     *
067     * <p>If null or empty, the section content is output without a title line.</p>
068     *
069     * @return the section title, or null for no title
070     */
071    default String getTitle() {
072        return null;
073    }
074}