Interface CardTypeHandler

All Known Implementing Classes:
ChartCardType, DatatablesCardType, HtmlCardType, InventoryGaugeCardType, JobLogCardType, SwitcherCardType, TerminalCardType

public interface CardTypeHandler
Server half of a console card type: validates an authored card and returns its page-contract fragment. Rendering is never done here; the JS handler registered under the same type() renders the fragment.

A type with no registered handler uses the generic passthrough (JSON5 body becomes the fragment, markup body becomes a template), so most custom cards need only JS. Register a handler when the server must validate or enrich the body.

Example:

public final class KpiCardType implements CardTypeHandler { @Override public String type() { return "kpi"; } @Override public JsonMap toFragment(CardSource src) { JsonMap b = src.json(); // E-24 on bad JSON5 if (! b.containsKey("value")) throw src.error("type='kpi' requires 'value'."); return b; } } // Registration (either): ConsoleFreemarkerMixin.create().cardType(new KpiCardType()).build(); // or META-INF/services/org.apache.juneau.console.CardTypeHandler

Since:
10.0.0
  • Method Summary

    Modifier and Type
    Method
    Description
    default Set<String>
    cmd:<id> ops this type handles, beyond the shell's refresh, for E-43 on a ribbon target.
    default Set<String>
    Roles this type accepts in subscribes[].as, beyond refresh and params.
    default List<String>
    Topics this card publishes without declaring them, for R-10.
    default List<Map<String,Object>>
    The cards this card holds, for a container type such as a switcher.
    default List<String>
    Toolkit packs this card needs because of what its body declares, beyond the packs its type always needs.
    Validates the authored card and returns its contract fragment.
    The type name this handler serves.
  • Method Details

    • type

      The type name this handler serves.
      Returns:
      The type name; must match ^[a-z][a-z0-9-]{0,31}$ (E-21).
    • toFragment

      Validates the authored card and returns its contract fragment.
      Parameters:
      source - The authored card (attributes plus body).
      Returns:
      The fragment merged flat onto the card's base keys; must not contain a reserved key (E-23).
      Throws:
      IllegalArgumentException - via CardSource.error(String, Object...) on invalid input.
    • implicitTopics

      default List<String> implicitTopics(JsonMap card)
      Topics this card publishes without declaring them, for R-10. Default: none (the shell adds card:/cmd:).

      Example:

      @Override public List<String> implicitTopics(JsonMap card) { return List.of("kpi.threshold-crossed"); }

      Parameters:
      card - The card object from the page contract (base keys plus this type's fragment).
      Returns:
      The concrete topics (or ns.name:* patterns) the type's JS publishes for this card.
    • acceptedRoles

      default Set<String> acceptedRoles()
      Roles this type accepts in subscribes[].as, beyond refresh and params. null (the default) means "unknown to Java": the Java validator skips E-44 and the JS check (E-JS-47) decides. For a card class these mirror the keys of its JS static roles. A handler subscription (topic + handler) names no role and is never checked against this set.

      Example:

      @Override public Set<String> acceptedRoles() { return Set.of("highlight"); }

      Returns:
      The accepted role names, or null if unknown.
    • acceptedOps

      default Set<String> acceptedOps()
      cmd:<id> ops this type handles, beyond the shell's refresh, for E-43 on a ribbon target. For a card class these mirror the keys of its JS static ops. null (the default) means "unknown to Java": the Java validator skips the check and the JS shell reports an unhandled op at runtime (E-JS-48).

      Example:

      @Override public Set<String> acceptedOps() { return Set.of("set-target"); }

      Returns:
      The handled op names, or null if unknown.
    • requiredPacks

      default List<String> requiredPacks(JsonMap body)
      Toolkit packs this card needs because of what its body declares, beyond the packs its type always needs. Unioned with the type's packs and the card's requires=. Default: none.

      Example:

      @Override public List<String> requiredPacks(JsonMap body) { return body.containsKey("terminal") ? List.of("terminal") : List.of(); }

      Parameters:
      body - The card's body: this type's fragment, as toFragment(CardSource) returned it.
      Returns:
      The pack names; each must be a registered pack.
    • nestedCards

      The cards this card holds, for a container type such as a switcher. The registry lifts each one through its own type's handler, and the page validators and pack requirements treat them as page cards. Default: none.

      Example:

      @Override public List<Map<String,Object>> nestedCards(JsonMap body) { return (List<Map<String,Object>>)body.get("cards"); }

      Parameters:
      body - The card's body: this type's fragment, or the card object as the page contract holds it.
      Returns:
      The nested card maps themselves (each with id and type), not copies, so they can be replaced in place.