Expand Collapse
Just a second...

Creating a metadata definition

You can use the API to specify the metadata structure that describes the byte data content of a message.

Publishing clients define the metadata structure for messages. This metadata structure can be used when defining a topic. All messages placed on the topic must conform to the metadata structure.

The Diffusion™ API for the following platforms provides builder methods that enable you to define the metadata structure:
  • JavaScript®
  • Java™
  • .NET
The C API does not provide builder methods, but instead takes the definition of the metadata as XML. For more information, see C API overview.

The following example demonstrates how to define the metadata structure using the Java API.

Note: Where there notation c.p.d is used in class or package names, it indicates com.pushtechnology.diffusion.
  1. Define the metadata structure.
    1. Use the Diffusion.metadata method to get a MetadataFactory. 
      private final MetadataFactory factory = Diffusion.metadata();
    2. Use the methods on the MetadataFactory to specify the content, record, and field definitions that make up the metadata structure.
      For example, the following code uses a content builder to create content metadata with a single record type that can occur zero to n times.
      public MContent createContentRepeating() {
    return
        factory.contentBuilder("Content").
            add(
                factory.record(
                    "Rec1",
                    factory.string("A"),
                    factory.string("B")),
                0,
                -1).
            build();

}

      For more information, see Java API documentation.

  2. Create a record topic and apply the metadata definition to it.
    1. Import the TopicControl feature, Session class, and RecordTopicDetails class. 
      import com.pushtechnology.diffusion.client.features.control.topics.TopicControl;
import com.pushtechnology.diffusion.client.session.Session;
import com.pushtechnology.diffusion.client.topics.details.RecordTopicDetails;
    2. Create a Session instance and use it to get the TopicControl feature. 
      final Session session = Diffusion.sessions().open("ws://diffusion.example.com:80");
final TopicControl tc = session.feature(TopicControl.class);
    3. Get a topic builder for a record topic from the TopicControl feature. 
      final RecordTopicDetails.Builder builder =
            tc.newDetailsBuilder(RecordTopicDetails.Builder.class);
    4. Use the metadata method of the topic builder to create the topic definition. 
      tc.addTopic(
            TOPIC_NAME,
            builder.metadata(metadata).build(),
            new TopicControl.AddCallback.Default() {
                @Override
                public void onTopicAdded(String topic) {
                    theTopic = topic;
                }

            });

Example: A client that creates a metadata definition and uses it when creating a topic.

package com.example.metadata;

import com.pushtechnology.diffusion.client.Diffusion;
import com.pushtechnology.diffusion.client.content.metadata.MContent;
import com.pushtechnology.diffusion.client.content.metadata.MDecimalString;
import com.pushtechnology.diffusion.client.content.metadata.MField;
import com.pushtechnology.diffusion.client.content.metadata.MRecord;
import com.pushtechnology.diffusion.client.content.metadata.MetadataFactory;
import com.pushtechnology.diffusion.client.topics.details.TopicType;
import com.pushtechnology.diffusion.client.features.control.topics.TopicControl;
import com.pushtechnology.diffusion.client.session.Session;
import com.pushtechnology.diffusion.client.topics.details.RecordTopicDetails;
import com.pushtechnology.diffusion.client.types.UpdateOptions;


/**
 * An example of a client creating metadata definition and using it when creating a 
 * topic definition. 
 */
public class ControlClient {

    private final static String TOPIC_NAME = "foo/record";
    private String theTopic;
    private final MetadataFactory factory = Diffusion.metadata();

    /**
     * Creates control client instance.
     */
    public ControlClient() {
        
        // Create the Session
        final Session session = Diffusion.sessions()
                .open("ws://diffusion.example.com:80");

        // Add the TopicControl feature
        final TopicControl tc = session.feature(TopicControl.class);

        // Create metadata for the topic
        final MContent metadata = defineMetadata();
        
        // Get a topic builder
        final RecordTopicDetails.Builder builder =
            tc.newDetailsBuilder(RecordTopicDetails.Builder.class);

        // Create the topic with metadata 
        tc.addTopic(
            TOPIC_NAME,
            builder.metadata(metadata).build(),
            new TopicControl.AddCallback.Default() {
                @Override
                public void onTopicAdded(String topic) {
                    theTopic = topic;
                }

            });

    }
    
    
    /**
     * A simple example of creating content metadata with two records.
     *
     * @return content metadata
     */
    public MContent defineMetadata() {
        return factory.content(
            "Content",
            createNameAndAddressRecord(),
            createMultipleRateCurrencyRecord("Exchange Rates", 5));
    }
    
    /**
     * Creates a simple name and address record with fixed name single
     * multiplicity fields.
     *
     * @return record definition.
     */
    public MRecord createNameAndAddressRecord() {
        return factory.record(
            "NameAndAddress",
            factory.string("FirstName"),
            factory.string("Surname"),
            factory.string("HouseNumber"),
            factory.string("Street"),
            factory.string("Town"),
            factory.string("State"),
            factory.string("PostCode"));
    }

    /**
     * This creates a record with two fields, a string called "Currency" and a
     * decimal string called "Rate" with a default value of 1.00 which repeats a
     * specified number of times.
     *
     * @param name the record name
     * @param occurs the number of occurrences of the "Rate" field
     * @return the metadata record
     */
    public MRecord createMultipleRateCurrencyRecord(String name, int occurs) {
        return factory.recordBuilder(name).
            add(factory.string("Currency")).
            add(factory.decimal("Rate", "1.00"), occurs).
            build();
    }

}

This page last modified: 2016/10/03