Class ApiEnvelope<T>

java.lang.Object
neqsim.mcp.model.ApiEnvelope<T>
Type Parameters:
T - the type of the data payload @author Even Solbraa @version 1.0
public class ApiEnvelope<T> extends Object
Standard API envelope for all MCP runner responses.

Wraps a typed result payload with status, warnings, and errors in a consistent format. This provides a dual interface — call toJson() for the string-based MCP protocol, or use getData() for typed Java access.

Success envelope:

{ "status": "success", "data": { ... }, "warnings": [] }

Error envelope:

{ "status": "error", "errors": [{"severity": "error", "code": "...", "message":
"..."}], "warnings": [] }

  • Field Details

    • GSON

      private static final com.google.gson.Gson GSON

    • status

      private final String status

    • data

      private final T data

    • errors

      private final List<DiagnosticIssue> errors

    • warnings

      private final List<String> warnings

  • Constructor Details

    • ApiEnvelope

      private ApiEnvelope(String status, T data, List<DiagnosticIssue> errors, List<String> warnings)
      Private constructor — use factory methods.
      Parameters:
      status - "success" or "error"
      data - the data payload, or null on error
      errors - the error list
      warnings - the warning list

  • Method Details

    • success

      public static <T> ApiEnvelope<T> success(T data)
      Creates a success envelope with the given data.
      Type Parameters:
      T - the payload type
      Parameters:
      data - the result payload
      Returns:
      the success envelope

    • success

      public static <T> ApiEnvelope<T> success(T data, List<String> warnings)
      Creates a success envelope with data and warnings.
      Type Parameters:
      T - the payload type
      Parameters:
      data - the result payload
      warnings - the warning messages
      Returns:
      the success envelope

    • error

      public static <T> ApiEnvelope<T> error(String code, String message, String remediation)
      Creates an error envelope with a single issue.
      Type Parameters:
      T - the payload type
      Parameters:
      code - the error code
      message - the error message
      remediation - the fix suggestion
      Returns:
      the error envelope

    • errors

      public static <T> ApiEnvelope<T> errors(List<DiagnosticIssue> issues)
      Creates an error envelope with multiple issues.
      Type Parameters:
      T - the payload type
      Parameters:
      issues - the diagnostic issues
      Returns:
      the error envelope

    • getStatus

      public String getStatus()
      Gets the status string.
      Returns:
      "success" or "error"

    • isSuccess

      public boolean isSuccess()
      Returns true if this is a success envelope.
      Returns:
      true if status is "success"

    • getData

      public T getData()
      Gets the data payload.
      Returns:
      the data, or null if this is an error envelope

    • getErrors

      public List<DiagnosticIssue> getErrors()
      Gets the error list.
      Returns:
      the errors

    • getWarnings

      public List<String> getWarnings()
      Gets the warning list.
      Returns:
      the warnings

    • addWarning

      public void addWarning(String warning)
      Adds a warning to this envelope.
      Parameters:
      warning - the warning message

    • toJson

      public String toJson()
      Converts this envelope to a JSON string.
      Returns:
      JSON string