dest.h File Reference

This file defines destination objects and various associated calls. More...

Macros
#define	TIB_ADVISORY_DEST   "_advisory_dest"
	special advisory destination that destination subscribers can subscribe to receive advisories. More...
#define	TIB_DEST_BROWSER_PROPERTY_STRING_DURABLE_NAME   "com.tibco.ftl.client.browser.durable.name"
	Durable name property; string. More...
#define	TIB_LOGGING_DEST   "_logging_dest"
	special logging destination that dest subscribers can subscribe to receive logging stream. More...
#define	TIB_MONITORING_DEST   "_monitoring_dest"
	special monitoring destination that destination subscribers can subscribe to receive monitoring stream. More...

Functions
TIB_API tibBrowser	tibRealm_CreateDestBrowser (tibEx e, tibRealm realm, const char *dest, tibProperties properties)
	Create a Destination Browser object. More...
TIB_API tibDestPublisher	tibRealm_CreateDestPublisher (tibEx e, tibRealm realm, const char *default_dest, tibProperties properties)
	Create a destination Publisher object. More...
TIB_API tibDestSubscriber	tibRealm_CreateDestSubscriber (tibEx e, tibRealm realm, const char *dest, tibProperties properties)
	Create a destination subscriber object. More...
TIB_API tibMap	tibRealm_CreateMapOnDest (tibEx e, tibRealm realm, const char *dest, tibProperties properties)
	Create a map object. A map is essentially a key value store. More...
TIB_API void	tibRealm_RemoveMapOnDest (tibEx e, tibRealm realm, const char *dest, tibProperties properties)
	Remove a map object. A map is essentially a key value store. More...
TIB_API void	tibRealm_RewindDest (tibEx e, tibRealm realm, const char *dest, tibProperties properties)
	Rewind either the durable on the destination or the queue. More...
TIB_API void	tibRealm_UnsubscribeDest (tibEx e, tibRealm realm, const char *dest, const char *durableName, tibProperties properties)
	Unsubscribe a durable from destination, this essentailly destroys a durable on a destination on the persistence service side. More...

Detailed Description

This file defines destination objects and various associated calls.

Destinations are of three different types

1. Destinations of type topic (no prefix required <dest_name>)
2. Destinations of type queue (prefixed with Q:<dest_name>)
3. Destinations of type maps (prefixed with M:<dest_name>)

Destination Sytanx.

The following restrictions apply to destination strings: UTF8 character encoding

1. Destination name shall not contain {, } characters with the exception that > and * can only be trailing characters or part of the token (e.g foo.bar.* or foo.ba*z.> are allowed)
2. ‘.’ (dot) is used as a separator between tokens, e.g. foo.bar.> or foo.bar.baz ‘*’ and ‘>’ are restricted characters
3. ‘*’ cannot be used as an intermediate token within a destination, it can only be used as a wildcard e.g. foo.*.bar not allowed, but foo.bar.* is allowed, also ‘>’ cannot be used as an intermediate token, but allowed to be specified by itself or as a leaf token ex. foo.> ),

Macro Definition Documentation

TIB_ADVISORY_DEST

#define TIB_ADVISORY_DEST   "_advisory_dest"

special advisory destination that destination subscribers can subscribe to receive advisories.

Application programs can create a subscriber on this advisory destination to receive asynchronous events that the FTL library generates. see advisory.h

TIB_DEST_BROWSER_PROPERTY_STRING_DURABLE_NAME

#define TIB_DEST_BROWSER_PROPERTY_STRING_DURABLE_NAME   "com.tibco.ftl.client.browser.durable.name"

Durable name property; string.

When creating a browser on a destination see tibRealm_CreateDestBrowser, this durable name property is required for browsing messages on the durable, since there could be many durables on given destination.

tibRealm_CreateDestBrowser

TIB_LOGGING_DEST

#define TIB_LOGGING_DEST   "_logging_dest"

special logging destination that dest subscribers can subscribe to receive logging stream.

Application programs can create a subscriber on this logging destination to receive logging events that are generated FTL services and applications.

TIB_MONITORING_DEST

#define TIB_MONITORING_DEST   "_monitoring_dest"

special monitoring destination that destination subscribers can subscribe to receive monitoring stream.

Application programs can create a subscriber on this monitoring destination to receive monitoring events that are generated by FTL services and applications

Function Documentation

tibRealm_CreateDestBrowser()

TIB_API tibBrowser tibRealm_CreateDestBrowser	(	tibEx	e,
		tibRealm	realm,
		const char *	dest,
		tibProperties	properties
	)

Create a Destination Browser object.

Destination browsers can be created on queues (e.g Q:queue_name) or topics (topic_name)

Applications use browser objects to inspect and, optionally, delete the contents of a destination.

If the destination browser is on a topic then TIB_DEST_BROWSER_PROPERTY_STRING_DURABLE_NAME is required to be specified in the properties object.

NOTE:

1. Wildcard destinations are not allowed.
2. Browsers can be created on either topic or queue destinations.

See tibBrowser_Next and tibBrowser_DeleteMessage.

Parameters

e	The exception object captures information about failures.
realm	The realm object is the source of configuration information about the application, destinations, stores.
dest	The destination can be either a topic or a queue name
properties	Optional. NULL to omit. Properties: TIB_BROWSER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION TIB_BROWSER_PROPERTY_STRING_LABEL TIB_BROWSER_PROPERTY_STRING_MATCHER TIB_DEST_BROWSER_PROPERTY_STRING_DURABLE_NAME

Returns

a new browser object

tibRealm_CreateDestPublisher()

TIB_API tibDestPublisher tibRealm_CreateDestPublisher	(	tibEx	e,
		tibRealm	realm,
		const char *	default_dest,
		tibProperties	properties
	)

Create a destination Publisher object.

A Destination Publisher is used to publish messages to a destination specified by the dest argument, This dest argument can be

1. a specific topic or queue name (queue names have to be prefixed with Q: e.g Q:foo1)
2. or NULL (NULL is used for unbound publisher)

Destination publishers can be of two types

1. Statically bound to a destination specified during create call.
2. Unbound destination publisher that was created with a NULL dest during create.

Statically bound destination publishers

1. Can be used to the send messages to only the destination that the publisher was created with during the tibRealm_CreateDestPublisher. 2 The advantage of statically bound publisher is that they don't incur the additional cost of round-trip required to setup a publisher on the persistence service side during send tibDestPublisher_Send or tibDestPublisher_SendMessages.

Unbound destination publishers

1. Unbound publishers can be used to send messages to any destination specified during the send call.
2. They provide the flexibility to applications to use a single destination publisher to send messages to different destinations.
3. They have one drawback, for a given destination, the very first send on that destination will incur the additional latency of a publisher being setup on the persistence service.

Parameters

e	The exception object captures information about failures.
realm	The realm object.
default_dest	The destination name for statically bound publisher or NULL for unbound publisher.
properties	The properties object. The following properties are possible TIB_DEST_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER TIB_DEST_PUBLISHER_PROPERTY_STRING_LABEL TIB_DEST_PUBLISHER_PROPERTY_INT_SEND_POLICY TIB_DEST_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT

tibRealm_CreateDestSubscriber()

TIB_API tibDestSubscriber tibRealm_CreateDestSubscriber	(	tibEx	e,
		tibRealm	realm,
		const char *	dest,
		tibProperties	properties
	)

Create a destination subscriber object.

Applications use destination subscriber objects to register interest on specific destinations to receive a stream of messages.

A destination subscriber does not receive messages until you add it to an event queue.

Destinations cannot be a wildcard, only specific destination names are allowed. destination names can be either a topic or a queue name (queue name have to be prefixed with Q: e.g Q:foo1)

NOTE:

1. If the destination is of type topic then TIB_DEST_SUBSCRIBER_PROPERTY_INT_DURABLE_TYPE is required property
2. Optionally applications can also specify the prefetch size via the TIB_DEST_SUBSCRIBER_PROPERTY_LONG_PREFETCH_SIZE property
3. Optionally applications can also specify acknowledge mode TIB_DEST_SUBSCRIBER_PROPERTY_INT_ACK_MODE including ack batch size TIB_DEST_SUBSCRIBER_PROPERTY_INT_ACK_BATCH_SIZE and ack batch time TIB_DEST_SUBSCRIBER_PROPERTY_DOUBLE_ACK_BATCH_TIME

Parameters

e	The exception object captures information about failures.
realm	The realm object.
dest	The destination name.
properties	The properties object.

TIB_DEST_SUBSCRIBER_PROPERTY_STRING_LABEL TIB_DEST_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK TIB_DEST_SUBSCRIBER_PROPERTY_INT_DURABLE_TYPE (Shared, Standard, LastValue) TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK TIB_DEST_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION TIB_DEST_SUBSCRIBER_PROPERTY_LONG_PREFETCH_SIZE TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_NOLOCAL_MESSAGE_DELIVERY TIB_DEST_SUBSCRIBER_PROPERTY_STRING_MATCH_FILTER

tibRealm_CreateMapOnDest()

TIB_API tibMap tibRealm_CreateMapOnDest	(	tibEx	e,
		tibRealm	realm,
		const char *	dest,
		tibProperties	properties
	)

Create a map object. A map is essentially a key value store.

Map objects with the same map name represent the same map within the persistence store.

If the store does not already contain the named map, this call creates the map.

NOTE:

1. Maps can be created only on map destinations i.e the ones that begin with M:
2. Wildcard destinations are not allowed.

Parameters

e	The exception object captures information about failures.
realm	The realm object is the source of configuration information about the application
dest	on which to create the map object. (dest name have to have a prefix of M:)
properties	Optional. NULL to omit. Properties: TIB_MAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION TIB_MAP_PROPERTY_STRING_LABEL

Returns

A new map object.

tibRealm_RemoveMapOnDest()

TIB_API void tibRealm_RemoveMapOnDest	(	tibEx	e,
		tibRealm	realm,
		const char *	dest,
		tibProperties	properties
	)

Remove a map object. A map is essentially a key value store.

Removes a map object that was created on the destination.

Map objects with the same map name represent the same map within the persistence store.

NOTE:

1. Maps can be created only on map destinations i.e the ones that begin with M:dest_name
2. Wildcard destinations are not allowed.

Parameters

e	The exception object captures information about failures.
realm	The realm object is the source of configuration information about the application
dest	on which the map object needs to be removed. (dest name have to have a prefix of M:<>)
properties	Optional. NULL to omit. Properties: TIB_MAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION TIB_MAP_PROPERTY_STRING_LABEL

tibRealm_RewindDest()

TIB_API void tibRealm_RewindDest	(	tibEx	e,
		tibRealm	realm,
		const char *	dest,
		tibProperties	properties
	)

Rewind either the durable on the destination or the queue.

Parameters

e	The exception object captures information about failures.
realm	The realm object.
dest	The destination name. [ Can be foo1 (for topic) or Q:foo1 (for queue) ]
properties	The properties object. Properties: TIB_DEST_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME

tibRealm_UnsubscribeDest()

TIB_API void tibRealm_UnsubscribeDest	(	tibEx	e,
		tibRealm	realm,
		const char *	dest,
		const char *	durableName,
		tibProperties	properties
	)

Unsubscribe a durable from destination, this essentailly destroys a durable on a destination on the persistence service side.

Destroying a durable and removes it from the store.

NOTE:

1. Wildcard destinations are not allowed
2. Destinations have to be only of topic type. queues and maps not allowed (Q:dest or M:dest)

If one client destroys a durable while other clients have subscribers to it, subsequent behavior is undefined.

Parameters

e	The exception object captures information about failures.
realm	The call destroys a dynamic durable in this realm.
dest	The destination name.
durableName	The name of the durable to destroy.
properties	The properties object.