Main Content

getProviderProperties

Kafka stream configuration property data

Since R2022b

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

    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.

    example

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

    example

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

    example

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

    example

    Examples

    collapse all

    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"

    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'

    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'

    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

    collapse all

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

    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

    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

    collapse all

    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.

    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

    collapse all

    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