getProviderProperties

Kafka stream configuration property data

Since R2022b

This function requires Streaming Data Framework for MATLAB^® Production Server™.

Syntax

prop = getProviderProperties(ks)

prop = getProviderProperties(ks,name)

prop = getProviderProperties(___,Category=cat)

[prop,val] = getProviderProperties(___)

Description

prop = getProviderProperties(ks) returns the names and categories of the Kafka^® stream provider properties in the structure array prop. The returned property names and categories are the ones specified during the creation of the Kafka stream connector object ks.

prop = getProviderProperties(ks,name) returns only the properties with the provider property names specified by name.

prop = getProviderProperties(___,Category=cat) returns only the properties that belong to the provider category cat, using either of the preceding syntaxes.

[prop,val] = getProviderProperties(___) also returns a cell array of the values for each returned property.

Examples

Get Provider Property Data

Assume that you have a Kafka server running at the network address kafka.host.com:9092 that has a topic CoolingFan.

Create a KafkaStream object connected to the Kafka host and also specify Kafka provider properties during object creation.

ks = kafkaStream("kafka.host.com",9092,"CoolingFan", ...
"security.protocol","SSL","ssl.truststore.type","PEM", ...
"ssl.truststore.location","kafka-boston.pem","retention.ms",500);

Get the names and categories for all provider properties.

prop = getProviderProperties(ks)

prop = 

  8×1 struct array with fields:

    name
    category

Display the property categories and names.

string({prop.category})' + "/" + string({prop.name})'

ans = 

  8×1 string array

    "Consumer/auto.offset.reset"
    "Consumer/security.protocol"
    "CreateTopic/retention.ms"
    "KafkaConnector/sasl.jaas.config"
    "Producer/security.protocol"
    "Uncategorized/ssl.truststore.location"
    "Uncategorized/ssl.truststore.type"
    "librdkafka/sasl.username"

Get Provider Properties by Name

Assume that you have a Kafka server running at the network address kafka.host.com:9092 that has a topic CoolingFan.

Create a KafkaStream object connected to the Kafka host and also specify Kafka provider properties during object creation.

ks = kafkaStream("kafka.host.com",9092,"CoolingFan", ...
"security.protocol","SSL","ssl.truststore.type","PEM", ...
"ssl.truststore.location","kafka-boston.pem","retention.ms",500);

Get the names and categories for two properties. Because the max.poll.records property is not set in ks, the getProviderProperties function does not return data for that property.

prop = getProviderProperties(ks,["max.poll.records" "retention.ms"])

prop = 

  struct with fields:

        name: 'retention.ms'
    category: 'CreateTopic'

Get Provider Properties by Category

Assume that you have a Kafka server running at the network address kafka.host.com:9092 that has a topic CoolingFan.

Create a KafkaStream object connected to the Kafka host and also specify Kafka provider properties during object creation.

ks = kafkaStream("kafka.host.com",9092,"CoolingFan", ...
"security.protocol","SSL","ssl.truststore.type","PEM", ...
"ssl.truststore.location","kafka-boston.pem","retention.ms",500);

Get data for the properties that belong to the CreateTopic category. This category includes only one property.

prop = getProviderProperties(ks,Category="CreateTopic")

prop = 

  struct with fields:

        name: 'retention.ms'
    category: 'CreateTopic'

Get Provider Property Names and Values

Assume that you have a Kafka server running at the network address kafka.host.com:9092 that has a topic CoolingFan.

Create a KafkaStream object connected to the Kafka host and also specify Kafka provider properties during object creation.

ks = kafkaStream("kafka.host.com",9092,"CoolingFan", ...
"security.protocol","SSL","ssl.truststore.type","PEM", ...
"ssl.truststore.location","kafka-boston.pem","retention.ms",500);

Display the categories, names, and values. The sasl.jaas.config property value fails to synthesize because ks is missing a dependent property. Instead of returning a value for this property, getProviderProperties returns an MException object describing this error.

[{"Category" "Name" "Value"};{prop.category}' {prop.name}' val']

ans =

  3×3 cell array

    {["Category"    ]}    {["Name"           ]}    {["Value"     ]}
    {'KafkaConnector'}    {'sasl.jaas.config' }    {1×1 MException}
    {'Producer'      }    {'security.protocol'}    {["SSL"       ]}

Input Arguments

ks — Object connected to Kafka stream topic

KafkaStream object

Object connected to a Kafka stream topic, specified as a KafkaStream object.

name — Kafka stream provider property names

string scalar | character vector | string array | cell array of character vectors

Kafka stream provider property names, specified as a string scalar, character vector, string array, or cell array of character vectors. If a property is not set in ks, then getProviderProperties does not return a name and category for that property in prop or an optional corresponding value in val.

Example: [prop, val] = getProviderProperties(ks,"retention.ms") returns data for the retention.ms property.

Data Types: char | string | cell

cat — Kafka stream provider category names

string scalar | character vector | string array | cell array of character vectors

Kafka stream provider category names, specified as a string scalar, character vector, string array, or cell array of character vectors.

The specified categories must be present in ks. To get a list of valid categories, use the ks.PropertyCategories property.

Data Types: char | string | cell

Output Arguments

prop — Kafka stream provider property names and categories

structure array

Kafka stream provider property names and categories, returned as a structure array. Each structure corresponds to a provider property in ks and has these fields:

• name — Provider property name, returned as a string

• category — Category that the provider property belongs to, returned as a string

Because properties can belong to more than one category, the category and name uniquely identity a property.

val — Kafka stream provider property values

cell array

Kafka stream provider property values, returned as a cell array of values for the property returned in prop. If ks is missing a dependent property needed to derive a property value, then in place of that value, getProviderProperties returns an MException (MATLAB) object that describes the error.

More About

Stream Provider Properties

Stream providers such as Kafka have vendor-specific configuration properties that influence how the stream provider operates on the stream. Some properties apply to a single type of operation, such as topic creation, while other properties apply to multiple operations. Properties are grouped into categories so that properties are sent only to the provider with operations that support them. Because the same property can belong to multiple categories, each property is uniquely identified by the combination of its name and category.

Version History

Introduced in R2022b