update-constraint.h File Reference

A constraint to be applied to an update operation or the creation of an update stream. More...

Typedefs
typedef struct DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T	DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T
	Opaque topic update constraint struct.

Enumerations
enum	DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_T {   DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_IS , DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_EQ , DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_NE , DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_GT ,   DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_GE , DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_LT , DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_LE }
	An operator used in a constraint comparison. More...

Functions
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	diffusion_topic_update_constraint_and (const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *left_constraint, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *right_constraint)
	Create a composed constraint that represents a logical AND of two constraints.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	diffusion_topic_update_constraint_or (const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *left_constraint, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *right_constraint)
	Create a composed constraint that represents a logical OR of two constraints.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	diffusion_topic_update_constraint_locked (const DIFFUSION_SESSION_LOCK_T *lock)
	Create a constraint requiring a lock to be held by the session.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	diffusion_topic_update_constraint_value (const BUF_T *value)
	Create a constraint requiring the current value of the topic to exactly match the supplied value.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	diffusion_topic_update_constraint_value_comparison (DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_T comparison_operator, DIFFUSION_UPDATE_CONSTRAINT_VALUE_T *value)
	Create a constraint comparing the current value of a topic to a supplied value.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	diffusion_topic_update_constraint_no_value (void)
	Create a constraint requiring the topic to have no value.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	diffusion_topic_update_constraint_no_topic (void)
	Create a constraint requiring the path to have no topic.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	diffusion_topic_update_constraint_unconstrained (void)
	Create a constraint with no requirements.
	DEPRECATED (DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *diffusion_topic_update_constraint_partial_json_with_value(const char *pointer, DIFFUSION_DATATYPE datatype, const BUF_T *value))
	Require a value at a specific position in the JSON object.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	diffusion_topic_update_constraint_partial_json_comparison (const char *pointer, DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_T comparison_operator, DIFFUSION_UPDATE_CONSTRAINT_VALUE_T *value)
	Compares a location within the JSON topic value to a specified value.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	diffusion_topic_update_constraint_partial_json_without_value (const char *pointer)
	Require a specific position in the JSON object to be absent.
void	diffusion_topic_update_constraint_free (DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint)
	Free a memory allocated DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T

Detailed Description

A constraint to be applied to an update operation or the creation of an update stream.

Constraints describe a condition that must be satisfied for an operation to succeed. Constraints can be applied to the setting of a value or creation of an update stream. Constraints are only evaluated on the server.

The constraints are evaluated using the:

• active session locks
• existence of the topic
• current value of the topic

The value of a topic can be described in several ways. The value can be described as an exact value, a partial value or an unset value.

Constraints can be composed with one another. It is only possible to construct logical ANDs of constraints. Constraints can only be composed if the resulting constraint is satisfiable. Multiple session locks can be held but a topic can only have a single value. Constraints specifying multiple topic values cannot be constructed.

Since

6.2

Enumeration Type Documentation

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_T

enum DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_T

An operator used in a constraint comparison.

Since

6.10

Enumerator
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_IS	Strict binary equality. This operator requires that the binary topic value is exactly equivalent to the value supplied for comparison.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_EQ	Lenient equals. This operator requires that the topic value is logically equal to the supplied value. If the supplied value is a string, the string representation of the specified topic value is compared for string equality. If the supplied value is a number (Integer, Long or Double), the corresponding topic value may be a number or a string containing a parseable number and will be compared for numeric equality. If the supplied value is null, the condition will be satisfied if the value at a specified pointer is JSON null.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_NE	Lenient not equals. This operator requires that the topic value is logically not equal to the supplied value. If the supplied value is a string, the string representation of the specified topic value is compared for string equality. If the supplied value is a number (Integer, Long or Double), the corresponding topic value may be a number or a string containing a parseable number and will be compared for numeric equality. If the supplied value is null, the condition will be satisfied if the value at a specified pointer not JSON null.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_GT	Lenient greater than. This operator requires that the topic value is greater than the supplied value. The supplied value must be a number (Integer, Long or Double). The corresponding topic value may be a number or a string containing a parseable number and the condition will be satisfied if the topic value is greater than the supplied value.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_GE	Lenient greater than or equals. This operator requires that the topic value is greater than or equal to the supplied value. The supplied value must be a number (Integer, Long or Double). The corresponding topic value may be a number or a string containing a parseable number and the condition will be satisfied if the topic value is greater than or equal to the supplied value.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_LT	Lenient less than. This operator requires that the topic value is less than the supplied value. The supplied value must be a number (Integer, Long or Double). The corresponding topic value may be a number or a string containing a parseable number and the condition will be satisfied if the topic value is less than the supplied value.
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_LE	Lenient less than or equals. This operator requires that the topic value is less than or equal to the supplied value. The supplied value must be a number (Integer, Long or Double). The corresponding topic value may be a number or a string containing a parseable number and the condition will be satisfied if the topic value is less than or equal to the supplied value.

Function Documentation

DEPRECATED()

DEPRECATED

(

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *

diffusion_topic_update_constraint_partial_json_with_valueconst char *pointer, DIFFUSION_DATATYPE datatype, const BUF_T *value

)

Require a value at a specific position in the JSON object.

This is equivalent to calling diffusion_topic_update_constraint_partial_json_comparison with an operator of DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_IS.

The pointer is a JSON Pointer syntax reference locating the value in the JSON object.

Only string, int64, and double values are supported. The null value may be passed for any type.

diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.

Parameters

pointer	the pointer expression
datatype	the value datatype
value	the value

Returns

the constraint. NULL if datatype isn't one of DATATYPE_STRING, DATATYPE_INT64 or DATATYPE_DOUBLE. Also NULL if pointer is NULL.

Deprecated:

since 6.10. Rather use diffusion_topic_update_constraint_partial_json_comparison method with the DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_IS operator.

diffusion_topic_update_constraint_and()

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * diffusion_topic_update_constraint_and	(	const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	left_constraint,
		const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	right_constraint
	)

Create a composed constraint that represents a logical AND of two constraints.

diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.

Parameters

left_constraint	a constraint that will be logically-ANDed with right_constraint
right_constraint	a constraint that will be logically-ANDed with left_constraint

Returns

a composed constraint that represents a logical AND of left_constraint and right_constraint

diffusion_topic_update_constraint_free()

void diffusion_topic_update_constraint_free

(

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *

constraint

)

Free a memory allocated DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T

Parameters

constraint

the constraint to be freed

diffusion_topic_update_constraint_locked()

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * diffusion_topic_update_constraint_locked

(

const DIFFUSION_SESSION_LOCK_T *

lock

)

Create a constraint requiring a lock to be held by the session.

This can be used to co-ordination operations between multiple sessions.

diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.

Parameters

lock

the lock

Returns

the constraint

diffusion_topic_update_constraint_no_topic()

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * diffusion_topic_update_constraint_no_topic

(

void

)

Create a constraint requiring the path to have no topic.

This is useful when setting the first value of a topic being added using diffusion_topic_update_add_and_set without changing the value if the topic already exists. This constraint is unsatisfied if a topic is present at the path, making it unsuitable for operations that try to set topics without adding them.

diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.

Returns

the constraint

diffusion_topic_update_constraint_no_value()

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * diffusion_topic_update_constraint_no_value

(

void

)

Create a constraint requiring the topic to have no value.

This is useful when setting the first value of a topic. This constraint is unsatisfied if no topic is present at the path, making it unsuitable for operations that try to add topics.

diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.

Returns

the constraint

diffusion_topic_update_constraint_or()

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * diffusion_topic_update_constraint_or	(	const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	left_constraint,
		const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	right_constraint
	)

Create a composed constraint that represents a logical OR of two constraints.

diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.

Parameters

left_constraint	a constraint that will be logically-ORed with right_constraint
right_constraint	a constraint that will be logically-ORed with left_constraint

Returns

a composed constraint that represents a logical OR of left_constraint and right_constraint

Since

6.10

diffusion_topic_update_constraint_partial_json_comparison()

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * diffusion_topic_update_constraint_partial_json_comparison	(	const char *	pointer,
		DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_T	comparison_operator,
		DIFFUSION_UPDATE_CONSTRAINT_VALUE_T *	value
	)

Compares a location within the JSON topic value to a specified value.

If there is no value found at the specified pointer position, the constraint will be unsatisfied.

If a String value is supplied and the operator is EQ or NE, the string representation of the topic value at the given pointer will be compared to the supplied value. If the value at the pointer position is not a string or number the constraint will be unsatisfied. Other operators (other than IS) are not permitted with String values.

If a number value (Integer, Long or Double) is supplied the value will be compared with the number value at the topic location. This will work with JSON string or number values only. JSON strings can only be compared if they contain a value that can be parsed as a number. If a string value at the location cannot be parsed as a number, the constraint will be unsatisfied. Any of the operators (other than IS) can be used with such number comparisons.

Decimal numbers can be compared with integral numbers so 1 is equal to 1.0, "1", or "1.0".

If a NULL value is supplied and the operator is EQ or NE, the topic value at the given pointer will be compared to JSON null. Other operators (other than IS) are not permitted with a NULL value.

If a Boolean value is supplied and the operator is EQ, the topic value at the given pointer will be compared to the boolean value. Other operators are not permitted with a boolean value.

If the IS operator is specified the supplied value will be compared to the topic value for strict binary equality. In this case the value must be of type String, Integer, Long, Double, Bytes, or NULL. This is slightly more efficient than the lenient comparisons described above.

Parameters

pointer	the pointer expression
comparison_operator	the operator that determines the type of comparison
value_type	the value datatype
value	the value

Returns

the constraint. NULL if datatype isn't one of DATATYPE_STRING, DATATYPE_INT64 or DATATYPE_DOUBLE. Also NULL if pointer is NULL.

Since

6.10

diffusion_topic_update_constraint_partial_json_without_value()

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * diffusion_topic_update_constraint_partial_json_without_value

(

const char *

pointer

)

Require a specific position in the JSON object to be absent.

This does not match positions that have null values.

The pointer is a JSON Pointer syntax reference that should have no value in the JSON object.

diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.

Parameters

pointer

the pointer expression

Returns

the constraint. NULL if pointer is NULL

diffusion_topic_update_constraint_unconstrained()

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * diffusion_topic_update_constraint_unconstrained

(

void

)

Create a constraint with no requirements.

This constraint is always satisfied.

diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.

Returns

the constraint

diffusion_topic_update_constraint_value()

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * diffusion_topic_update_constraint_value

(

const BUF_T *

value

)

Create a constraint requiring the current value of the topic to exactly match the supplied value.

NULL value cannot be passed as a parameter because it would prevent the required topic type being inferred.

This is exactly equivalent to calling diffusion_topic_update_constraint_value_comparison(DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_IS, value).

This can be used to change the value of a topic. This constraint is unsatisfied if no topic is present at the path making it unsuitable for operations that try to add topics.

diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.

Parameters

value

the value

Returns

the constraint

diffusion_topic_update_constraint_value_comparison()

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * diffusion_topic_update_constraint_value_comparison	(	DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_T	comparison_operator,
		DIFFUSION_UPDATE_CONSTRAINT_VALUE_T *	value
	)

Create a constraint comparing the current value of a topic to a supplied value.

If a String value is supplied and the operator is EQ or NE, the string representation of the topic will be compared to the supplied value. This can only be used with primitive topic types (or TIME_SERIES topics with a primitive event type). Other operators (other than IS) are not permitted with String values.

If a number value is supplied (Integer, Long or Double), the value will be compared with the number value of the topic. This will work with STRING,INT64 or DOUBLE topics (or TIME_SERIES topics with a primitive event type) only. STRING topics can only be compared if they contain a value that can be parsed as a number.

If the value of a STRING topic cannot be parsed as a number, or the topic is of any other non-number type the constraint will be unsatisfied. Any of the operators (other than IS) can be used with such number comparisons. Decimal numbers can be compared with integral numbers so 1 is equal to 1.0, "1", or "1.0".

If the IS operator is specified, the specified value will be compared to the topic value for strict binary equality.

The value type can be any value type supported by DataTypes (Integer is allowed and is treated as a Long) or any Bytes value and can be used to compare against any topic type.

When a STRING, INT64 or DOUBLE topic is updated to a NULL value, the topic is set to have no value.

Use the diffusion_topic_update_constraint_no_value() constraint to check if the topic has no value. This constraint is useful when changing the value of a topic. This constraint is unsatisfied if no topic is present at the path, making it unsuitable for operations that try to add topics.

Parameters

comparison_operator	the operator the determines the type of comparison
value	the value

Returns

the constraint

Since

6.10