Configuration

The Anteater configuration is designed to be flexible and user-friendly, allowing you to customize its behavior through an XML-based configuration file (ae.xml). This file defines the environment, variables, logging, recipes, and other startup-specific settings. The hierarchical structure uses elements and attributes to specify various configurations. Below is a simplified and non-developer-friendly explanation of the structure and its components.

Overview

At the heart of the configuration is the <Environment> element. Think of this as the “container” for all your settings. Inside the <Environment>, one or more <Configuration> elements can exist. These configurations hold your actual settings.

The configuration file structure (ae.xml) is validated using a defined XML Schema Definition (XSD). The XSD describes the rules and structure that the file must follow, ensuring consistency and correctness.

You can view the full XSD here: Anteater Configuration XSD.

Key Attributes of <Environment>

  • base: This allows one configuration to extend or inherit settings from another (“parent configuration”). If you want to reuse settings from another configuration, this is the way to do it.
  • name: The name of the configuration.
  • menu: Specifies the menu associated with the configuration.
  • userPreferencesEncryption: Enables encryption for saved user preferences. Use true if you want added security.
  • ip: Defines a specific IP address for the configuration (if needed).

Core Elements in Configuration

<Recipes>

The <Recipes> element defines where Anteater searches for recipes. Recipes inform Anteater about tasks and workflows it needs to process.

Attributes:

  • path:
    • Specifies the location of the recipes. It can point to:
      • A local directory (e.g., /path/to/recipes).
      • A .zip file containing the recipes.
      • A URL to an online resource hosting the recipes.
    • This flexibility allows recipes to be accessed from various sources, making Anteater adaptable for remote deployments.

Behavior:

  1. Primary Path Handling:

    • Anteater searches for recipes in the directories, archives, or URLs specified via the path attribute.

  2. Fallback to Default Recipe Folder:

    • If the provided path does not exist or is inaccessible, Anteater will automatically attempt to load recipes embedded within the application JAR.
    • This behavior supports self-contained Anteater implementations, enabling you to create a single deployable JAR file where both the application and recipes are bundled together.

    The example project: ae-assemble-sample

  3. Priority of Multiple <Recipes> Tags:

    • When multiple <Recipes> elements are defined, the last <Recipes> tag in the configuration has the highest priority. Recipes in earlier paths will be overridden if the same recipe exists in the last path.

Use Cases for Default Embedded Recipes:

  • Building a single-file Anteater JAR that includes both the application and recipes.
    • This simplifies deployments by bundling everything needed into a single executable JAR file.
    • It's particularly useful for cases where recipes are static or pre-defined for specific workflows.
  • Ensuring Anteater continues to function even if external resource paths (local or remote) are unavailable.

Example 1: Using Local Directory

<Recipes path="/path/to/local/recipes" />

Example 2: Using a .zip File

<Recipes path="/path/to/recipes.zip" />

Example 3: Using URL to Fetch Recipes

<Recipes path="https://example.com/recipes/recipes.zip" />

Example 4: Multiple <Recipes> Tags

<Recipes path="/path/to/recipes1" />
<Recipes path="/path/to/recipes2" />
<Recipes path="https://example.com/recipes/latest.zip" />
  • In this example:
    • Recipes in /path/to/recipes1 are loaded first.
    • Recipes in /path/to/recipes2 override matching recipes from /path/to/recipes1.
    • Recipes from https://example.com/recipes/latest.zip have highest priority and override files from both locally defined paths.

Example 5: Embedded Recipes in JAR as Default Fallback

<Recipes path="/some/invalid/path" />
  • In this case:
    • Anteater first tries to load recipes from /some/invalid/path.
    • Since the path does not exist, recipes embedded in the JAR file will load as a fallback.

Benefits of Using Embedded Recipes

  1. Simplified Deployments:

    • With recipes bundled inside the application JAR, there's no need to distribute or manage separate recipe folders.

  2. High Availability:

    • The fallback behavior ensures Anteater executes predefined recipes even in cases of missing paths or inaccessible remote servers.

  3. Portable Configuration:

    • The approach reduces reliance on external resources, making the application more portable and self-contained.

Additional Notes:

  • The highest-priority <Recipes> tag is especially useful for providing dynamic updates to recipes (e.g., loading the latest version of a script from a remote server).
  • Using a .zip archive or URL reduces the need for manually updating recipes across distributed deployments or teams, increasing flexibility.

<Var>

Used to define reusable variables.

  • Attributes:
    • name: The variable's name.
    • value: (Optional) The value assigned to the variable.
    • type: (Optional) Defines the data type (e.g., string, array, map).
    • init: (Optional) Defines how to initialize the variable (e.g., mandatory, console).

Example:

<Var name="myVar" value="some value" />
<Var name="customList" type="array">
    <item value="FirstItem" />
    <item value="SecondItem" />
</Var>

<Logger>

Handles logging settings—where and how logs are stored.

  • Attributes:

    • rootLogger: Root logger name (optional).
    • Threshold: Logging level (e.g., DEBUG, INFO, ERROR).
    • ConversionPattern: Customize the format of log messages.
    • File: File path for saving logs.

  • Nested Element: <filter>

    • Filters sensitive information or logs only necessary data.

Example:

<Logger Threshold="DEBUG" File="logs/output.log" ConversionPattern="%d %p %m%n">
    <filter class="MaskJSON" name="password" />
</Logger>

<Table>

Defines organized data using variables that can be referenced in execution.

  • Attributes:
    • name: The name of the table.
    • Nested Elements:
      • <var>: Defines each variable in the table.

Example:

<Table name="ServerConfig">
    <var name="host" value="localhost" />
    <var name="port" value="8080" />
    <var name="secure" value="true" />
</Table>

<Startup>

Specifies tasks that are executed when Anteater starts.

  • Attributes:
    • task: The name of the startup task.
    • async: Whether this task runs asynchronously (true or false).

Example:

<Startup task="InitializeDatabase" async="true" />

<Menu>

Defines the menu structure, enabling users to navigate and trigger specific tasks.

  • Attributes:
    • name: The name of the menu.
    • Nested Element: <item> defines each menu entry.

Example:

<Menu name="Main Menu">
    <item task="RunTask" />
    <item file="example.json" />
</Menu>

<Editor>

Customizes editors to handle and display certain components.

  • Attributes:
    • class: The class used for this editor.
    • name: Name of the editor.

Example:

<Editor class="com.editor.custom" name="CustomEditor" />

How to Create a Basic ae.xml File

Here’s an example of a basic configuration file for Anteater:

<?xml version="1.0" encoding="UTF-8"?>
<Environment xmlns="http://ganteater.com/xml/configuration">
    <Configuration name="Default" userPreferencesEncryption="true">
        <!-- Define Variables -->
        <Var name="apiKey" value="12345" />
        <Var name="host" value="localhost" />
        
        <!-- Logger Configuration -->
        <Logger File="logs/app.log" Threshold="INFO" />

        <!-- Recipes Configuration -->
        <Recipes path="/path/to/recipes" />

        <!-- Startup Task -->
        <Startup task="Initialize" async="true" />

        <!-- Menu -->
        <Menu name="Main Menu">
            <item task="RunTask" />
            <item file="config.json" />
        </Menu>
    </Configuration>
</Environment>

Additional Notes for Non-Technical Users

  1. Inheritance with base Attribute:

    • If you want one configuration to reuse or “inherit” properties from another, use the base attribute.
    • Example: 
      <Configuration name="ExtendedConfig" base="Default">
    <Var name="extendedVar" value="extendedValue" />
</Configuration>

  2. Using Variables (<Var>):

    • Variables allow you to reuse values throughout your tasks without redefining them.

  3. Logging Configuration:

    • Logs help you debug problems or monitor the application. Ensure File is specified to store logs in a file.

  4. Startup Configuration:

    • Use <Startup> to define actions Anteater runs automatically during startup.

Common Use Cases

  1. Enable Secure Logging:

    • Use filtered logging to prevent sensitive information (e.g., passwords) from being logged.

    Example:

    <Logger File="logs/secure-output.log">
   <filter class="MaskJSON" name="password" />
</Logger>

  2. Execute Recipes Automatically:

    • Add directories of recipes that should be executed dynamically.

    Example:

    <Recipes path="/recipes/automation" />

  3. Organize Dynamic Data:

    • Use tables for complex or dynamic configurations.

    Example:

    <Table name="DatabaseConfig">
   <var name="host" value="db.local" />
   <var name="port" value="3306" />
</Table>

The ae.xml configuration file is highly flexible and allows you to customize Anteater's behavior to meet your specific needs, all without requiring technical expertise. If anything is unclear, review the official documentation or reach out to support.