Class RuleSet

java.lang.Object
dev.mahe.copperlace.RuleSet
All Implemented Interfaces:
AutoCloseable
public final class RuleSet extends Object implements AutoCloseable
Compiled Copperlace rules loaded from configuration.

RuleSet is the lower-level load-once API. It owns a native Copperlace ruleset handle and can render named rules repeatedly until close() is called.

Most callers should use Copperlace; use RuleSet directly when the lower-level type better matches the surrounding API.

  • Method Details

    • fromString

      public static RuleSet fromString(String config)
      Compiles a configuration string into a reusable ruleset.
      Parameters:
      config - configuration text containing Copperlace rules
      Returns:
      a ruleset backed by a native Copperlace handle
      Throws:
      IllegalArgumentException - if config is blank
      CopperlaceException - if the config cannot be parsed or compiled

    • fromStringWithProcessors

      public static RuleSet fromStringWithProcessors(String config, Map<String, CopperlaceProcessor> processors)
      Compiles a configuration string into a reusable ruleset with custom processors.
      Parameters:
      config - configuration text containing Copperlace rules
      processors - custom processor callbacks keyed by processor name
      Returns:
      a ruleset backed by a native Copperlace handle
      Throws:
      NullPointerException - if processors, a processor name, or a processor is null
      IllegalArgumentException - if config is blank
      CopperlaceException - if the config cannot be parsed or compiled

    • fromFile

      public static RuleSet fromFile(Path path)
      Loads and compiles a configuration file into a reusable ruleset.
      Parameters:
      path - path to the configuration file
      Returns:
      a ruleset backed by a native Copperlace handle
      Throws:
      NullPointerException - if path is null
      CopperlaceException - if the file cannot be loaded, parsed, or compiled

    • fromFileWithProcessors

      public static RuleSet fromFileWithProcessors(Path path, Map<String, CopperlaceProcessor> processors)
      Loads and compiles a configuration file into a reusable ruleset with custom processors.
      Parameters:
      path - path to the configuration file
      processors - custom processor callbacks keyed by processor name
      Returns:
      a ruleset backed by a native Copperlace handle
      Throws:
      NullPointerException - if path, processors, a processor name, or a processor is null
      CopperlaceException - if the file cannot be loaded, parsed, or compiled

    • render

      public String render(String rule)
      Renders a named rule from this ruleset.

      Each call uses a fresh render context, so per-render bindings are consistent within one output but do not carry over to later renders.

      Parameters:
      rule - name of the rule to render
      Returns:
      rendered text for rule
      Throws:
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this ruleset is closed or rendering fails

    • render

      public String render(String rule, Map<String,String> context)
      Renders a named rule from this ruleset with initial context values.

      The provided context is scoped to this render only. Values resolve before config-defined context defaults and named rules.

      Parameters:
      rule - name of the rule to render
      context - initial render context values
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this ruleset is closed or rendering fails

    • renderInferred

      public String renderInferred(String rule)
      Renders a named rule as text, returning formatted JSON for object-valued rules.
      Parameters:
      rule - name of the rule to render
      Returns:
      rendered text, or formatted JSON for an object-valued rule
      Throws:
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this ruleset is closed or rendering fails

    • renderInferred

      public String renderInferred(String rule, Map<String,String> context)
      Renders a named rule as text with initial context, returning formatted JSON for object-valued rules.
      Parameters:
      rule - name of the rule to render
      context - initial render context values
      Returns:
      rendered text, or formatted JSON for an object-valued rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this ruleset is closed or rendering fails

    • renderStructuredJson

      public String renderStructuredJson(String rule)
      Renders a named structured rule from this ruleset as formatted JSON text.
      Parameters:
      rule - name of the structured rule to render
      Returns:
      formatted JSON for rule
      Throws:
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this ruleset is closed or rendering fails

    • renderStructuredJson

      public String renderStructuredJson(String rule, boolean formatJson)
      Renders a named structured rule from this ruleset as JSON text.
      Parameters:
      rule - name of the structured rule to render
      formatJson - true to format JSON with tabs, false for compact JSON
      Returns:
      JSON for rule
      Throws:
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this ruleset is closed or rendering fails

    • renderStructuredJson

      public String renderStructuredJson(String rule, Map<String,String> context)
      Renders a named structured rule from this ruleset as formatted JSON text with initial context values.
      Parameters:
      rule - name of the structured rule to render
      context - initial render context values
      Returns:
      formatted JSON for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this ruleset is closed or rendering fails

    • renderStructuredJson

      public String renderStructuredJson(String rule, Map<String,String> context, boolean formatJson)
      Renders a named structured rule from this ruleset as JSON text with initial context values.
      Parameters:
      rule - name of the structured rule to render
      context - initial render context values
      formatJson - true to format JSON with tabs, false for compact JSON
      Returns:
      JSON for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this ruleset is closed or rendering fails

    • close

      public void close()
      Releases this ruleset's native handle.

      Calling close more than once is allowed.

      Specified by:
      close in interface AutoCloseable