# Stream XML File Reader

O **Stream XML File Reader** lê um arquivo XML local e identifica nós de acordo com o target node e os context fields configurados. Para cada nó encontrado, ele gera uma estrutura XML junto com suas propriedades de contexto e aciona subpipelines para processar cada mensagem resultante de forma independente. Esse conector é usado para ler e processar grandes arquivos XML de maneira eficiente, em partes, sem carregar o arquivo inteiro na memória.

## Parâmetros

Configure o conector utilizando os parâmetros abaixo. Campos que aceitam [expressões Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces) estão marcados na coluna **Suporta DB**.

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Tipo</th><th>Suporta DB</th><th>Valor</th></tr></thead><tbody><tr><td><strong>Alias</strong></td><td>Nome (alias) para o output deste conector, permitindo <a href="../../double-braces/how-to-reference-data-using-double-braces">referenciá-lo posteriormente no fluxo usando expressões Double Braces</a>.</td><td>String</td><td>✅</td><td>stream-xml-f-reader-1</td></tr><tr><td><strong>File name</strong> </td><td>Nome do arquivo ou caminho completo (por exemplo, <code>tmp/processed/file.txt</code>) do arquivo XML local.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Charset</strong></td><td>Nome do conjunto de caracteres para leitura do arquivo.</td><td>String</td><td>❌</td><td>UTF-8</td></tr><tr><td><strong>Node Path</strong> </td><td>Caminho do nó desejado a ser lido a partir do arquivo XML (<code>//root/level1/level2/desirednode</code>).</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Context Paths</strong></td><td>Define os caminhos das tags que representam campos que adicionam contexto ao nó desejado (<code>//root/node1/code</code> ou <code>//root/node2/description</code>).</td><td>String</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Ignore Paths</strong></td><td>Define os caminhos que serão ignorados e não retornados dentro do nó desejado (/<code>/root/node1/email,//root/node2/city</code>).</td><td>String</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Ignore Nested Child Nodes</strong></td><td>Quando ativado, ignora nós filhos aninhados (que não sejam filhos diretos do target node). Nesse caso, apenas nós no mesmo nível do target node são retornados, enquanto nós mais profundos são excluídos.</td><td>Boolean</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Element Identifier</strong></td><td>Atributo que será enviado em caso de erros.</td><td>String</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Parallel Execution Of Each Iteration</strong></td><td>Ocorre em paralelo com a execução do <em>loop</em>.</td><td>Booleano</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Remove whitespaces</strong></td><td>Quando ativado, remove espaços em branco no início e no final de todos os valores de caracteres XML.</td><td>Booleano</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Coalesce</strong></td><td>Quando ativado, os valores de caracteres XML são lidos como uma única string.</td><td>Booleano</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Escape Special Characters</strong></td><td>Quando ativado, faz o escape automático de caracteres reservados do XML (<code>&#x26;</code>, <code>&#x3C;</code>, <code>></code>) para evitar erros de parsing durante a transformação dos dados.</td><td>Booleano</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Tolerate Invalid XML</strong></td><td>Quando ativado, retorna um objeto JSON alternativo em vez de lançar uma exceção para XML inválido.</td><td>Booleano</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Fail On Error</strong></td><td>Quando ativado, interrompe a execução do pipeline caso ocorra um erro crítico durante a iteração. Não se aplica a erros em conectores utilizados dentro de subpipelines (onProcess e onException).</td><td>Booleano</td><td>❌</td><td>N/A</td></tr></tbody></table>

{% hint style="warning" %}
Use o parâmetro **Remove Whitespaces** com cuidado para evitar alterar a integridade dos dados, pois ele remove espaços em cada etapa de processamento. Para evitar esse problema, combine-o com **Coalesce**, que lê os valores de caracteres como um bloco único. No entanto, lembre-se de que **Coalesce** pode aumentar o uso de recursos ao processar grandes volumes de dados.
{% endhint %}

## Fluxo de mensagens <a href="#h_9935e06ea4" id="h_9935e06ea4"></a>

### Entrada <a href="#h_ddefd24400" id="h_ddefd24400"></a>

Nenhuma mensagem de entrada específica é necessária. No entanto, um arquivo XML válido deve existir no diretório local do pipeline, e os campos File Name e Node Path devem estar corretamente configurados para o processamento.

### Saída <a href="#h_3c41e7bad5" id="h_3c41e7bad5"></a>

```json
{
"total": 0,
"success": 0,
"failed": 0
}
```

* **`total`:** Número total de linhas processadas.
* **`success`:** Número total de linhas processadas com sucesso.
* **`failed`:** Número total de linhas cujo processamento falhou.

{% hint style="info" %}
Quando uma linha é processada com sucesso, o subpipeline correspondente retorna "success": true }
{% endhint %}

## File handling and Batch processing

* O conector lança uma exceção se o **File Name** não existir ou não puder ser lido.
* O manuseio de arquivos dentro de um pipeline é protegido: todos os arquivos são acessados por meio de um diretório temporário, e cada pipeline key tem acesso apenas ao seu próprio conjunto de arquivos.
* O **Stream XML File Reader** realiza **batch processing**, o que significa que ele processa dados continuamente em lotes menores e controlados, garantindo melhor eficiência e uso de recursos.

## Event Handling: Unsupported Events

O Stream XML File Reader usa um **mecanismo de leitura baseado em eventos**, no qual cada tipo de dado no arquivo XML é tratado como um evento a ser processado. No entanto, alguns tipos de evento não são suportados durante o streaming — ou seja, não são tratados pelo conector:

* PROCESSING INSTRUCTION
* START DOCUMENT
* END DOCUMENT
* SPACE
* ENTITY REFERENCE
* ENTITY DECLARATION
* DTD
* NOTATION DECLARATION

{% hint style="info" %}
Esses eventos não são necessários para o processamento típico de dados XML, e sua omissão ajuda a melhorar o desempenho ao lidar com grandes arquivos.
{% endhint %}

## Stream XML File Reader em Ação <a href="#h_6eb38d0ab7" id="h_6eb38d0ab7"></a>

Os cenários a seguir estão utilizando como base o seguinte arquivo XML:

* **File name:** file.xml
* **Conteúdo:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
<list-info qty="4">products</list-info>
<products>
<product>
<price>20.75</price>
<product>Chair</product>
<tags>
<element>NEW</element>
<element>FURNITURE</element>
</tags>
</product>
<product>
<price>399.99</price>
<product>TV</product>
<tags>
<element>NEW</element>
<element>FURNITURE</element>
</tags>
</product>
<product>
<price>100</price>
<product>Couch</product>
<tags>
<element>NEW</element>
<element>FURNITURE</element>
</tags>
</product>
<product>
<price>78.99</price>
<product>Table</product>
<tags>
<element>NEW</element>
<element>FURNITURE</element>
</tags>
</product>
</products>
</root>
```

### Realizando o stream do arquivo informando o nó desejado <a href="#h_dcd89dcaa5" id="h_dcd89dcaa5"></a>

#### **Entrada**

* **File Name:** file.xml
* **Node Path:** //root/products/product

#### **Saída**

```json
{
"total": 4,
"success": 4,
"failed": 0
}
```

Cada elemento identificado pelo caminho do nó desejado será processado de forma independente:

* **Primeiro subfluxo:**

{% code overflow="wrap" %}

```json
{
"node":"<product><price>20.75</price><product>Chair</product><tags><element>NEW</element><element>FURNITURE</element></tags></product>"
}
```

{% endcode %}

* **Segundo subfluxo:**

{% code overflow="wrap" %}

```json
{
"node":"<product><price>399.99</price><product>TV</product><tags><element>NEW</element><element>FURNITURE</element></tags></product>"
}
```

{% endcode %}

* **Terceiro subfluxo:**

{% code overflow="wrap" %}

```json
{
"node":"<product><price>100</price><product>Couch</product><tags><element>NEW</element><element>FURNITURE</element></tags></product>"
}
```

{% endcode %}

* **Quarto subfluxo:**

{% code overflow="wrap" %}

```json
{
"node":"<product><price>78.99</price><product>Table</product><tags><element>NEW</element><element>FURNITURE</element></tags></product>"
}
```

{% endcode %}

### Realizando o stream do arquivo informando o nó desejado e campos de contexto <a href="#h_100ca898cb" id="h_100ca898cb"></a>

#### **Entrada**

* **File Name:** file.xml
* **Node Path:** //root/products/product
* **Context Paths:** //root/list-info

#### **Saída**

```json
{
"total": 4,
"success": 4,
"failed": 0
}
```

Cada elemento identificado pelo caminho do nó desejado será processado de forma independente:

* **Primeiro subfluxo:**

{% code overflow="wrap" %}

```json
{
"context": {
"root": {
"list-info": {
"attributes": {
"qty": "4"
},
"value": "products"
}
}
},
"node": "<product><price>20.75</price><product>Chair</product><tags><element>NEW</element><element>FURNITURE</element></tags></product>"
}
```

{% endcode %}

* **Segundo subfluxo:**

{% code overflow="wrap" %}

```json
{
"context": {
"root": {
"list-info": {
"attributes": {
"qty": "4"
},
"value": "products"
}
}
},
"node": "<product><price>399.99</price><product>TV</product><tags><element>NEW</element><element>FURNITURE</element></tags></product>"
}
```

{% endcode %}

* **Terceiro subfluxo:**

{% code overflow="wrap" %}

```json
{
"context": {
"root": {
"list-info": {
"attributes": {
"qty": "4"
},
"value": "products"
}
}
},
"node": "<product><price>100</price><product>Couch</product><tags><element>NEW</element><element>FURNITURE</element></tags></product>"
}
```

{% endcode %}

* **Quarto subfluxo:**

{% code overflow="wrap" %}

```json
{
"context": {
"root": {
"list-info": {
"attributes": {
"qty": "4"
},
"value": "products"
}
}
},
"node": "<product><price>78.99</price><product>Table</product><tags><element>NEW</element><element>FURNITURE</element></tags></product>"
}
```

{% endcode %}

### Realizando o stream do arquivo informando o nó desejado, campos de contexto e nós à serem ignorados <a href="#h_a6b1dbfa6e" id="h_a6b1dbfa6e"></a>

#### **Entrada**

* **File Name:** file.xml
* **Node Path:** //root/products/product
* **Context Paths:** //root/list-info
* **Ignore Paths:** //root/products/product/tags

#### **Saída**

```json
{
"total": 4,
"success": 4,
"failed": 0
}
```

Cada elemento identificado pelo caminho do nó desejado será processado de forma independente:

* **Primeiro subfluxo:**

```json
{
"context": {
"root": {
"list-info": {
"attributes": {
"qty": "4"
},
"value": "products"
}
}
},
"node": "<product><price>20.75</price><product>Chair</product></product>"
}
```

* **Segundo subfluxo:**

```json
{
"context": {
"root": {
"list-info": {
"attributes": {
"qty": "4"
},
"value": "products"
}
}
},
"node": "<product><price>399.99</price><product>TV</product></product>"
}
```

* **Terceiro subfluxo:**

```json
{
"context": {
"root": {
"list-info": {
"attributes": {
"qty": "4"
},
"value": "products"
}
}
},
"node": "<product><price>100</price><product>Couch</product></product>"
}
```

* **Quarto subfluxo:**

```json
{
"context": {
"root": {
"list-info": {
"attributes": {
"qty": "4"
},
"value": "products"
}
}
},
"node": "<product><price>78.99</price><product>Table</product></product>"
}
```

### Realizando o stream do arquivo informando o nó desejado e ignorando nós filhos aninhados <a href="#h_086a4fe07b" id="h_086a4fe07b"></a>

#### **Entrada**

* **File Name:** file.xml
* **Node Path:** //root/products/product
* **Ignore Nested Child Nodes:** ativado

#### **Saída**

```json
{
"total": 4,
"success": 4,
"failed": 0
}
```

Cada elemento identificado pelo caminho do nó desejado será processado de forma independente:

* **Primeiro subfluxo:**

{% code overflow="wrap" %}

```json
{
"data": {
"node": "<product><price>20.75</price><product>Chair</product><tags></tags></product>"
},
"success": true
}
```

{% endcode %}

* **Segundo subfluxo:**

{% code overflow="wrap" %}

```json
{
"node": "<product><price>399.99</price><product>TV</product><tags></tags></product>"
}
```

{% endcode %}

* **Terceiro subfluxo:**

{% code overflow="wrap" %}

```json
{
"node": "<product><price>100</price><product>Couch</product><tags></tags></product>"
}
```

{% endcode %}

* **Quarto subfluxo:**

{% code overflow="wrap" %}

```json
{
"node": "<product><price>78.99</price><product>Table</product><tags></tags></product>"
}
```

{% endcode %}