Expand Collapse
Just a second...

DEPRECATED: Add a topic using an initial value

A client can add a topic and define its type by providing an initial value, but this is now deprecated. It is better to create a topic, then separately update it with an initial value.

Required permissions: modify_topic

Supported platforms: JavaScript®, Android™, Java™, .NET

Add a topic, providing a value to the method from which the Diffusion™ server can derive the type of the topic:

JavaScript
// Create a topic with string values, and an initial value of "xyz".
session.topics.add('topic/string', 'xyz');

// Create a topic with integer values, and an initial value of 123.
session.topics.add('topic/integer', 123);

// Create a topic with decimal values, with an implicit scale of 2 and an initial value of 1.23.
session.topics.add('topic/decimal', 1.23);
                        
// Create record content from previously defined metadata
var builder = metadata.builder();

// Values must be set before a value can be created
builder.add('game', { title : 'Planet Express!', count : 3 });
    
builder.add('player', { name : 'Fry', score : 0 });
builder.add('player', { name : 'Amy', score : 0 });
builder.add('player', { name : 'Kif', score : 0 });

// Build a content instance
var initial_value = builder.build();

// Create a topic with record content. The metadata structure is derived from the structure of the initial value.
session.topics.add('games/game', initial_value).then(function() {
   console.log('Topic was added with initial value');
});
Java and Android
// Create a topic with string values, and an initial value of "xyz".
topicControl.addTopicFromValue( "topic/string", "xyz", callback);

// Create a topic with integer values, and an initial value of 42.
topicControl.addTopicFromValue( "topic/integer", "42", callback);

// Create a topic with decimal values, with an implicit scale of 3 and an initial value of 2.718.
topicControl.addTopicFromValue( "topic/decimal", "2.718", callback);
                                
// Create a topic with record content. Use RecordCOntentBuilder and its methods to construct the content.
// The metadata structure is derived from the structure of the initial value.
topicControl.addTopicFromValue( "topic/record",
                                 Diffusion.content().newBuilder(RecordContentBuilder.class)
                                                    .putFields(initialValues).build(),
                                 callback);
.NET
var topicControl = session.TopicControl;

var callback = new TopicControlAddCallbackDefault();

// Create a topic with string values and an initial value of 'xyz'.
topicControl.AddTopicFromValue( "topic/string", "xyz", callback );

// Create a topic with integer values and an initial value of 42.
topicControl.AddTopicFromValue( "topic/integer", "42", callback );

// Create a topic with decimal values with an implicit scale of 3 and an initial value of 2.718.
topicControl.AddTopicFromValue( "topic/decimal", "2.718", callback );

// Create a topic with record content.  Use IRecordContentBuilder and its methods to construct the content.
// The metadata structure is derived from the structure of the initial value.
var initialValues = new[]{"1","2","3"};

topicControl.AddTopicFromValue(
	"topic/record",
	Diffusion.Content.NewBuilder<IRecordContentBuilder>().PutFields( initialValues ).Build(), callback );

The value used to create the topic is set as the initial value of the topic and sent to any subscribed clients.

Derived topic types

The following table lists the topic types derived from different types of provided values:
Value type Topic type Metadata Initial value
JSON JSON Not applicable The supplied value
Binary Binary Not applicable The supplied value
Content created using a builder method Record The metadata of the content is derived from the records and fields in the content with the following assumptions:
  • Numeric values are assumed to be MIntegerString
  • Numeric values that contain a decimal point (.) are assumed to be MDecimalString with a scale equal to the number of places after the decimal point
  • All other values are assumed to be MString
 The supplied content
Content not created using a builder method Single value MString The supplied content as a string
Integer, Long, Short, Byte, BigInteger, AtomicInteger, AtomicLong Single value MIntegerString A value derived from the string representation of the supplied value
BigDecimal Single value MDecimalString with scale from supplied value A value derived from the string representation of the supplied value
Double, Float Single value MDecimalString with scale 2 A value derived from the string representation of the supplied value
Note: We do not recommend using floating point numbers. If used, the number is converted to decimal using half even rounding.
Other Single value MString A string representation of the supplied value
Note: Ensure that you correctly format the data provided as an initial value according to the standards of the language you are using. Incorrectly formatted data can cause errors when using the data to add topics.

For more information about the format of the initial value in each API and how metadata structure and data types are derived from that value, see the API documentation for that API.

Record topics

If the topic type is a record topic, Diffusion derives the structure of the metadata of the topic from the provided initial value. This metadata structure or data type must be adhered to by all subsequent updates to the topic.

Note: Using this method to define the metadata structure for record topics has limitations.
  • Field types are derived from the values provided. Avoid providing initial values that are ambiguous. For example, if you intend that a field have a string data type, do not provide an initial value that is numeric. In this case a decimal or integer type is derived.
  • It is not possible for Diffusion to detect the intent to use repeating records or fields. If your metadata structure is to contain repeating records or fields, you cannot define your topic using a value. Instead create your metadata definition explicitly, using the provided builder methods.
  • In some APIs (for example, JavaScript you must have defined the metadata in order to create record content. In many cases, it is better when adding a topic to use this metadata definition in addition to providing an initial value.