# Actions: Xml

install4j BeanInfo catalog. Each entry below documents a bean class that can appear inside a `<serializedBean>` element in an install4j project file.

## Contents

- [Apply an XSLT transform](#apply-an-xslt-transform) — `com.install4j.runtime.beans.actions.xml.XsltAction`
- [Count nodes in XML file](#count-nodes-in-xml-file) — `com.install4j.runtime.beans.actions.xml.XPathCountAction`
- [Insert XML fragment into XML files](#insert-xml-fragment-into-xml-files) — `com.install4j.runtime.beans.actions.xml.InsertXmlFragmentAction`
- [Read value from XML file](#read-value-from-xml-file) — `com.install4j.runtime.beans.actions.xml.XPathReadAction`
- [Remove nodes from XML files](#remove-nodes-from-xml-files) — `com.install4j.runtime.beans.actions.xml.RemoveXPathAction`
- [Replace text in XML files](#replace-text-in-xml-files) — `com.install4j.runtime.beans.actions.xml.XPathReplaceAction`

---

### Apply an XSLT transform
- **Class:** `com.install4j.runtime.beans.actions.xml.XsltAction`
- **Category:** XML files
- **Multiple instances:** yes
- **Installed files required:** yes

Transform an installed file by applying an XSLT stylesheet.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `downloadExternalEntities` — Download external entities | boolean | XML parser | — | If selected, a DTD referenced with an HTTP system ID will be downloaded as the document is parsed. The success of the action requires a direct internet connection in that case. |
| `validating` — Validate XML file | boolean | XML parser | — | If selected, the XML parser will validate the document according to an associated DTD or XML schema. If the validation is unsuccessful, the action will fail. |
| `sourceFile` — Source file | File | Configuration | — | The source for the transformation. This can be the same file as the destination. |
| `file` — Destination file | File | Configuration | — | The output of the transformation. This can be the same file as the source. |
| `xlstFile` — Stylesheet | ExternalFile | Configuration | — | The XSLT stylesheet to apply. |

### Count nodes in XML file
- **Class:** `com.install4j.runtime.beans.actions.xml.XPathCountAction`
- **Category:** XML files
- **Multiple instances:** yes
- **Installed files required:** yes

Count the occurrences of an XPath expression in an XML file and save the result to an installer variable.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `file` — XML file | File | Configuration | — | The XML file that should be read. It will not be validated, and no external entities will be downloaded. |
| `namespaceAware` — Namespace-aware | boolean | Configuration | `xpathExpression` set | If selected, the used XML parser will be namespace-aware. If the elements in the XPath expression have namespaces, these namespaces have to be declared in the "XML namespaces" child property and the configured prefixes have to be used in the XPath expression. |
| `namespaces` — XML namespaces | Map [context=namespaces] | Configuration | `namespaceAware`=true | Namespaces that are used in the XPath expression. Leave empty if the XML document does not contain namespace definitions (xmlns="..." or xmlns:xxx="...")If the document uses a default namespace (xmlns="..."), you have to define it with an explicit prefix because a missing prefix will only match nodes with no namespaces and not match any nodes in the default namespace. |
| `xpathExpression` — XPath expression | String | Configuration | — | The XPath expression whose occurrences should be counted. Example for counting attributes: /myRootNode/myChildNode/@myAttribute. Example for counting regular nodes: /myRootNode/myChildNode |
| `variableName` — Variable name | String [context=variableName] (variable→ Integer) | Configuration | — | The name of the variable that will be set to the result of the count as a java.lang.Integer. Enter the variable without the installer prefix and the dollar sign. If the XPath expression cannot be found, the variable value will be zero. |

### Insert XML fragment into XML files
- **Class:** `com.install4j.runtime.beans.actions.xml.InsertXmlFragmentAction`
- **Category:** XML files
- **Multiple instances:** yes
- **Installed files required:** yes

Insert an XML fragment into the position defined by an XPath expression. The fragment can replace an existing element node, or it can be inserted as a child or a sibling.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `downloadExternalEntities` — Download external entities | boolean | XML parser | — | If selected, a DTD referenced with an HTTP system ID will be downloaded as the document is parsed. The success of the action requires a direct internet connection in that case. |
| `validating` — Validate XML file | boolean | XML parser | — | If selected, the XML parser will validate the document according to an associated DTD or XML schema. If the validation is unsuccessful, the action will fail. |
| `files` — XML files | File[] | Configuration | — | The XML files that should be modified. In the edit dialog you can choose files from the distribution tree or enter them manually. XML files that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate XML files, this allows you to build a variable length list of XML files at runtime. |
| `xpathExpression` — XPath expression | String | Configuration | — | The XPath expression to the DOM nodes for which the insertion or replacement should be performed. The result of the XPath expression should consist of one or more element nodes and not of attribute or text nodes. Example for selecting nodes by position: /levelOne[2]/levelTwo[4]. Example for selecting nodes by attribute: /myRootNode/myChildNode[@id='123']. If no match can be found, the action will fail. |
| `namespaces` — XML namespaces | Map [context=namespaces] | Configuration | `xpathExpression` set | Namespaces that are used in the XPath expression. Leave empty if the XML document does not contain namespace definitions (xmlns="..." or xmlns:xxx="...")If the document uses a default namespace (xmlns="..."), you have to define it with an explicit prefix because a missing prefix will only match nodes with no namespaces and not match any nodes in the default namespace. |
| `fragmentSource` — XML fragment source | [FragmentSource](enums.md#fragmentsource) | Configuration | — | The XML fragment that is inserted can either be entered directly in a text editor or be read from a file. |
| `fragmentText` — XML fragment text | String [context=multiline] | Configuration | `fragmentSource`=Direct entry | The XML fragment that should be inserted. The fragment must not include an XML declaration and can contain multiple top-level elements.Example: <insert>1</insert><insert>2</insert> |
| `fragmentFile` — XML fragment file | ExternalFile [context=externalOrInternal] | Configuration | `fragmentSource`=Fragment file | The source file with the XML fragment that should be inserted. The file has to contain a well-formed XML file. The root element is discarded and the XML fragment is formed from its immediate children. |
| `fragmentInsertMode` — Insert mode | [FragmentInsertMode](enums.md#fragmentinsertmode) | Configuration | — | For each result of the XPath expression, the selected action is performed. You can replace the matched element, insert the fragment as a sibling or as a child.To insert as the n-th child, enter a positional XPath expression like /root/nested[3], and choose "Insert before". |

### Read value from XML file
- **Class:** `com.install4j.runtime.beans.actions.xml.XPathReadAction`
- **Category:** XML files
- **Multiple instances:** yes
- **Installed files required:** yes

Read a string value from an XML file specified by an XPath expression and save the result to an installer variable.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `file` — XML file | File | Configuration | — | The XML file that should be read. It will not be validated, and no external entities will be downloaded. |
| `namespaceAware` — Namespace-aware | boolean | Configuration | `xpathExpression` set | If selected, the used XML parser will be namespace-aware. If the elements in the XPath expression have namespaces, these namespaces have to be declared in the "XML namespaces" child property and the configured prefixes have to be used in the XPath expression. |
| `namespaces` — XML namespaces | Map [context=namespaces] | Configuration | `namespaceAware`=true | Namespaces that are used in the XPath expression. Leave empty if the XML document does not contain namespace definitions (xmlns="..." or xmlns:xxx="...")If the document uses a default namespace (xmlns="..."), you have to define it with an explicit prefix because a missing prefix will only match nodes with no namespaces and not match any nodes in the default namespace. |
| `xpathExpression` — XPath expression | String | Configuration | — | The XPath expression to the DOM node whose string value should be read. Example for reading text from an attribute: /myRootNode/myChildNode/@myAttribute. Example for reading text from an element: /myRootNode/myChildNode/text() |
| `variableName` — Variable name for string value | String [context=variableName] (variable→ String) | Configuration | — | The name of the variable that will be set with the string value of the matched node. Enter the variable without the installer prefix and the dollar sign. If the XPath expression cannot be found, the variable value will not be set. If the XPath expression matches a node with a null node value, such as en element, the variable will be set to null. |
| `nodeVariableName` — Variable name for node | String [context=variableName] (variable→ Node) | Configuration | — | The name of the variable that will be set with the node as an org.w3c.dom.Node instance. Enter the variable without the installer prefix and the dollar sign. If the XPath expression cannot be found, the variable value will not be set. |

### Remove nodes from XML files
- **Class:** `com.install4j.runtime.beans.actions.xml.RemoveXPathAction`
- **Category:** XML files
- **Multiple instances:** yes
- **Installed files required:** yes

Remove selected nodes from XML files by specifying an XPath expression.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `downloadExternalEntities` — Download external entities | boolean | XML parser | — | If selected, a DTD referenced with an HTTP system ID will be downloaded as the document is parsed. The success of the action requires a direct internet connection in that case. |
| `validating` — Validate XML file | boolean | XML parser | — | If selected, the XML parser will validate the document according to an associated DTD or XML schema. If the validation is unsuccessful, the action will fail. |
| `files` — XML files | File[] | Configuration | — | The XML files that should be modified. In the edit dialog you can choose files from the distribution tree or enter them manually. XML files that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate XML files, this allows you to build a variable length list of XML files at runtime. |
| `xpathExpression` — XPath expression | String | Configuration | — | The XPath expression to the DOM nodes that should be removed. The result of the XPath expression can be or any node type. Example for selecting element nodes: /myRootNode/myChildNode[@id='123']. Example for selecting attribute nodes: //@removedAttribute. Example for selecting text nodes: //container/text(). If no match can be found, the action will fail. |
| `namespaces` — XML namespaces | Map [context=namespaces] | Configuration | `xpathExpression` set | Namespaces that are used in the XPath expression. Leave empty if the XML document does not contain namespace definitions (xmlns="..." or xmlns:xxx="...")If the document uses a default namespace (xmlns="..."), you have to define it with an explicit prefix because a missing prefix will only match nodes with no namespaces and not match any nodes in the default namespace. |

### Replace text in XML files
- **Class:** `com.install4j.runtime.beans.actions.xml.XPathReplaceAction`
- **Category:** XML files
- **Multiple instances:** yes
- **Installed files required:** yes

Modify installed XML files by selecting nodes with an XPath expression and applying a regular expression on the selected values.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `downloadExternalEntities` — Download external entities | boolean | XML parser | — | If selected, a DTD referenced with an HTTP system ID will be downloaded as the document is parsed. The success of the action requires a direct internet connection in that case. |
| `validating` — Validate XML file | boolean | XML parser | — | If selected, the XML parser will validate the document according to an associated DTD or XML schema. If the validation is unsuccessful, the action will fail. |
| `files` — XML files | File[] | Configuration | — | The XML files that should be modified. In the edit dialog you can choose files from the distribution tree or enter them manually. XML files that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate XML files, this allows you to build a variable length list of XML files at runtime. |
| `xpathExpression` — XPath expression | String | Configuration | — | The XPath expression to selected DOM nodes that have a value (this includes attributes and text).Example for replacing text in an attribute: /myRootNode/myChildNode/@myAttribute. Example for replacing text in an element: /myRootNode/myChildNode/text(). This will also work if myChildNode is an empty node. If you want to match line breaks with the dot as well, prefix the regular expression with (?s). If you want the comparison to be case-insensitive, prefix it with (?i). |
| `namespaces` — XML namespaces | Map [context=namespaces] | Configuration | `xpathExpression` set | Namespaces that are used in the XPath expression. Leave empty if the XML document does not contain namespace definitions (xmlns="..." or xmlns:xxx="...")If the document uses a default namespace (xmlns="..."), you have to define it with an explicit prefix because a missing prefix will only match nodes with no namespaces and not match any nodes in the default namespace. |
| `regex` — Match expression | String | Configuration | — | The match expression. This is a regular expression. |
| `replacement` — Replacement | String [context=multiline] | Configuration | — | The replacement. The replacement string may contain references to subsequences, see the javadoc for java.util.regex.Matcher#appendReplacement for more details |
| `replaceAll` — Replace all | boolean | Configuration | — | If all occurrences should be replaced or only the first one. |
| `quoteVariables` — Quote variables | boolean | Configuration | — | If values of installer variables in the match and replacement expressions should be quoted. This means that the characters of replaced installer variables will be treated literally instead of modifying the search or replace expressions with special characters such as \\ or $. |
| `logReplacement` — Log replacement | boolean | Configuration | — | If the replacement text should be written into the log file or not. If the modified file has different security settings than the log file, you might want to disable this property for security reasons. |

