> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# START_LISTEN

> Reference for the `START_LISTEN` DLC operation, covering the `DlcStartListenRequest` and `DlcStartListenResponse`, and how file source listeners trigger a `LOAD` on each detected file change.

## Overview

This operation will keep the listening stream open in the background.

If a stream is opened on a directory, and that directory contains data, then the data will be loaded immediately when
the stream is opened.

Streams can be closed by using the [`STOP_LISTEN`](/operations/operations-stop-listen) operation. The status of an open stream
can be retrieved using the [`LIST_STATUS`](/operations/operations-listen-status) operation.

The `START_LISTEN` operation can act on any fetching Topic.

## Request

<Tabs>
  <Tab title="Java">
    ### `DlcStartListenRequest`

    | Key                   | Required | Type                            | Description                                                                                          |
    | --------------------- | :------: | :------------------------------ | ---------------------------------------------------------------------------------------------------- |
    | topics                |     Y    | `Set<String>`                   | Set of topics or aliases.                                                                            |
    | topicOverrides        |          | `Set<ILoadingTopicDescription>` | Topic overrides.                                                                                     |
    | scope                 |          | `IDlcScope`                     | [Scope Parameters](/functional/scope-parameters)                                                     |
    | branch                |          | `String`                        | The branch to operate on.                                                                            |
    | performGcOnStart      |          | `Boolean`                       | Perform a [Garbage collection](/functional/garbage-collection) before the datastore transaction.     |
    | performGcOnCompletion |          | `Boolean`                       | Perform a [Garbage collection](/functional/garbage-collection) after the datastore transaction.      |
    | sourceName            |          | `String`                        | The source name to operate on. See [source to topic matching](/functional/source-to-topic-matching). |
    | sourceType            |          | `DlcSourceType`                 | The source type to operate on. See [source to topic matching](/functional/source-to-topic-matching). |

    #### Example:

    ```Java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
    DlcStartListenRequest.builder()
        .topics("Topic1", "Topic2") // Required
        .topicOverrides(Set.of(CsvTopicDescription.builder("TopicToOverride", "glob:file*.csv")...build()))
        .scope(DlcScope.of("ScopeKey1", "ScopeValue1"))
        .branch("BranchToLoadInto")
        .sourceName("NameOfSourceToUse")
        .sourceType(DlcSourceType.LOCAL_SOURCE)
        .build();
    ```
  </Tab>

  <Tab title="JSON">
    ### `DlcStartListenRequestDTO`

    | Key                   | Required | Type                              | Description                                                                                          |
    | --------------------- | :------: | :-------------------------------- | ---------------------------------------------------------------------------------------------------- |
    | topics                |     Y    | `Set<String>`                     | Set of topics or aliases.                                                                            |
    | csvTopicOverrides     |          | `Map<String, CsvTopicProperties>` | CSV Topic overrides.                                                                                 |
    | scope                 |          | `Map<String, Object>`             | [Scope Parameters](/functional/scope-parameters)                                                     |
    | branch                |          | `String`                          | The branch to operate on.                                                                            |
    | performGcOnStart      |          | `Boolean`                         | Perform a [Garbage collection](/functional/garbage-collection) before the datastore transaction.     |
    | performGcOnCompletion |          | `Boolean`                         | Perform a [Garbage collection](/functional/garbage-collection) after the datastore transaction.      |
    | sourceName            |          | `String`                          | The source name to operate on. See [source to topic matching](/functional/source-to-topic-matching). |
    | sourceType            |          | `DlcSourceType`                   | The source type to operate on. See [source to topic matching](/functional/source-to-topic-matching). |

    #### Example:

    ```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
    {
      "operation": "START_LISTEN",
      "topics": ["Topic1", "Topic2"],
      "csvTopicOverrides": {
        "TopicToOverride": {
          "path": "glob:file*.csv"
        }
      },
      "scope": {
        "ScopeKey1": "ScopeValue1"
      },
      "branch": "BranchToLoadInto",
      "performGcOnStart": true,
      "performGcOnCompletion": true,
      "sourceName": "NameOfSourceToUse",
      "sourceType": "LOCAL_SOURCE"
    }
    ```
  </Tab>
</Tabs>

## Response

<Tabs>
  <Tab title="Java">
    ### `DlcStartListenResponse`

    | Key    | Type                | Description                                                  |
    | ------ | :------------------ | ------------------------------------------------------------ |
    | report | `StartListenReport` | Report of what occurred during the `START_LISTEN` operation. |
    | status | `DlcStatus`         | Status of the DLC Operation.                                 |

    ### `StartListenReport`

    | Key              | Type                  | Description                                                       |
    | ---------------- | :-------------------- | ----------------------------------------------------------------- |
    | listenIdPerTopic | `Map<String, String>` | A unique identifier to the stream that was opened for each Topic. |

    ### `DlcStatus`

    A simple enum to capture if the DLC request was executed.

    | Key   | Description                                     |
    | ----- | ----------------------------------------------- |
    | OK    | Request was handled successfully.               |
    | ERROR | Request was not able to be performed correctly. |
  </Tab>

  <Tab title="JSON">
    ### `DlcStartListenResponseDTO`

    | Key              | Type                  | Description                                                       |
    | ---------------- | :-------------------- | ----------------------------------------------------------------- |
    | listenIdPerTopic | `Map<String, String>` | A unique identifier to the stream that was opened for each Topic. |

    #### Example:

    ```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
    {
      "listenIdPerTopic": {
        "Topic1": "4320",
        "Topic2": "6550"
      },
      "status": "OK"
    }
    ```
  </Tab>
</Tabs>

### How it works

#### File source types

For file source types, the DLC will register a file listener and start listening on the specified topics. When the file watcher is notified
of file updates, the DLC listen operation will execute a DLC [`LOAD`](/operations/operations-load) operation to load the files that have been updated.

This means that the listen operation will simply execute a `LOAD` operation on all file updates.