> ## 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-stop-listen) operation. The status of an open stream
can be retrieved using the [`LIST_STATUS`](./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/6.2/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/6.2/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/6.2/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-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.