Skip to content

fix: update readme to have proper wordings #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dalelane merged 3 commits into from
Jan 14, 2025
Merged

fix: update readme to have proper wordings #9

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9e9bc40
fix: update readme to have proper wordings
Joel-hanson Jan 2, 2025
0ce4c59
fix: Apply suggestions from code review
Joel-hanson Jan 8, 2025
ed8da4b
Update README.md
Joel-hanson Jan 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 19 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,64 @@
# kafka-connect-xml-converter
# Kafka Connect XML converter and transformation plug-ins

A Kafka Connect plugin to make it easier to work with XML data in Kafka Connect pipelines.
The Kafka Connect XML converter and transformation plug-ins make it easier to work with XML data in Kafka Connect pipelines.

## Contents

- `com.ibm.eventstreams.kafkaconnect.plugins.xml.XmlConverter`
- a Kafka Connect converter for converting to/from XML strings
A Kafka Connect converter for converting between structured objects (Kafka Connect's internal data format, and Java Maps and Lists) and XML strings.
- `com.ibm.eventstreams.kafkaconnect.plugins.xml.XmlTransformation`
- a Kafka Connect transformation for converting Kafka Connect records to/from XML strings
A Single Message Transform (SMT) that takes a Kafka Connect record containing an XML string and transforms it into a structured Connect record.
- `com.ibm.eventstreams.kafkaconnect.plugins.xml.XmlMQRecordBuilder`
- an MQ Source Record builder for parsing MQ messages containing XML strings
An MQ Source Record builder for parsing MQ messages containing XML strings.

## Configuration

Optional configuration that can be set when using the plugin to turn XML strings into Connect records (XML string -> Conect Record)
The following table lists optional configuration that can be set when turning XML strings into Connect records by using the plug-ins (XML string to Connect record).

| **Option** | **Default value** | **Notes** |
| --------------------- | ----------------- | --------------------------------------------------------------------------------------- |
| `root.element.name` | `root` | The name of the root element in the XML document being parsed. |
| `xsd.schema.path` | | Location of a schema file to use to parse the XML string. |
| `xml.doc.flat.enable` | `false` | Set to `true` if the XML strings contain a single value (e.g. `<root>the message</root>`) |
| **Option** | **Default value** | **Notes** |
| --------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `root.element.name` | `root` | The name of the root element in the XML document that is being parsed. |
| `xsd.schema.path` | | The location of the schema file to use when parsing the XML string. |
| `xml.doc.flat.enable` | `false` | Set to `true` if the XML strings contain a single value (for example, `<root>the message</root>`) |

Optional configuration that can be set when using the plugin to create XML strings from Connect records (Conect Record -> XML string)
The following table lists optional configuration that can be set when turning Connect records into XML strings by using the plug-ins (Connect Record to XML string)

| **Option** | **Default value** | **Notes** |
| ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `root.element.name` | `root` | The name to use for the root element of the XML document being created. Only used when no name can be found within the schema of the Connect record. |

## Example uses

Use **`XmlConverter`** with Source Connectors to produce structured Connect records to Kafka topics as XML strings.
Use **`XmlConverter`** with source connectors to produce structured Connect records to Kafka topics as XML strings.

```properties
value.converter=com.ibm.eventstreams.kafkaconnect.plugins.xml.XmlConverter
value.converter.schemas.enable=false
```

Use **`XmlConverter`** with Source Connectors to produce Connect records to Kafka topics as XML strings, with an embedded XSD schema. (requires structs)
Use **`XmlConverter`** with source connectors to produce Connect records to Kafka topics as XML strings, with an embedded XSD schema (requires structured objects).

```properties
value.converter=com.ibm.eventstreams.kafkaconnect.plugins.xml.XmlConverter
value.converter.schemas.enable=true
```

Use **`XmlTransformation`** with Sink Connectors to convert a Connect record containing an XML string into a structured Connect record.
Use **`XmlTransformation`** with sink connectors to convert a Connect record containing an XML string into a structured Connect record.

```properties
transforms=xmlconvert
transforms.xmlconvert.type=com.ibm.eventstreams.kafkaconnect.plugins.xml.XmlTransformation
transforms.xmlconvert.converter.type=value
```

Use **`XmlConverter`** with the MQ Sink Connector to send non-XML Kafka messages to MQ queues as XML strings.
Use **`XmlConverter`** with the IBM MQ sink connector to send non-XML Kafka messages to MQ queues as XML strings.

```properties
mq.message.builder=com.ibm.eventstreams.connect.mqsink.builders.ConverterMessageBuilder
mq.message.builder.value.converter=com.ibm.eventstreams.kafkaconnect.plugins.xml.XmlConverter
```

Use **`XmlMQRecordBuilder`** with the MQ Source Connector to convert XML strings from MQ queues into Connect records.
Use **`XmlMQRecordBuilder`** with the IBM MQ source connector to convert XML strings from MQ queues into Connect records.

```properties
mq.record.builder=com.ibm.eventstreams.kafkaconnect.plugins.xml.XmlMQRecordBuilder
Expand All @@ -68,11 +68,11 @@ mq.record.builder.xsd.schema.path=/location/of/mq-message-schema.xsd

## Adding the IBM MQ Source Connector JAR to the Project

To build the project, you need to pull and install the latest IBM MQ Source Connector JAR. Follow these steps:
To build the project, you need to pull and install the latest IBM MQ source connector JAR. Follow these steps:

1. **Download the MQ Source Connector JAR**

Download the latest version of the MQ Source Connector JAR from the official IBM GitHub releases page:
Download the latest version of the IBM MQ source connector JAR from the official IBM GitHub releases page:

```bash
curl -L -o kafka-connect-mq-source-<VERSION>.jar https://github.com/ibm-messaging/kafka-connect-mq-source/releases/download/v<VERSION>/kafka-connect-mq-source-<VERSION>.jar
Expand Down
Loading