Realm objects contain definitions of message formats, endpoints and transport maps. More...

Inheritance diagram for TIBCO.FTL.IRealm:

Public Member Functions
ITibBrowser	CreateBrowser (String endpointName, String durableName, ITibProperties props)
	Create a browser. More...

IContentMatcher	CreateContentMatcher (string MatchString)
	Create a content matcher. More...

IEventQueue	CreateEventQueue ()
	Create an event queue. More...

IEventQueue	CreateEventQueue (ITibProperties props)
	Create an event queue. More...

IInboxSubscriber	CreateInboxSubscriber (string endpointName)
	Create an inbox subscriber. More...

IInboxSubscriber	CreateInboxSubscriber (string endpointName, ITibProperties props)
	Create an inbox subscriber. More...

ITibLock	CreateLock (String lockName, ITibProperties props)
	Create a lock object. More...

ITibMap	CreateMap (String endpointName, String mapName, ITibProperties props)
	Create a map object. More...

IMessage	CreateMessage ()
	Create a mutable message object with an unnamed dynamic format (for use only in one specific message). More...

IMessage	CreateMessage (byte[] bytes, int length)
	Create a message from a byte-array representation. More...

IMessage	CreateMessage (string formatName)
	Create a mutable message object. More...

IMessageFieldRef	CreateMessageFieldRef (string fieldName)
	Create a field reference object. More...

IPublisher	CreatePublisher (string endpointName)
	Create a publisher. More...

IPublisher	CreatePublisher (string endpointName, ITibProperties properties)
	Create a publisher. More...

ISubscriber	CreateSubscriber (string endpointName)
	Create a subscriber. More...

ISubscriber	CreateSubscriber (string endpointName, IContentMatcher matcher)
	Create a subscriber. More...

ISubscriber	CreateSubscriber (string endpointName, IContentMatcher matcher, ITibProperties props)
	Create a subscriber. More...

ISubscriber	CreateSubscriber (string endpointName, ITibProperties props)
	Create a subscriber. More...

String	GetServerVersion ()
	Return the FTLserver version the client is connected to. More...

void	RemoveMap (String endpointName, String mapName, ITibProperties props)
	Delete a map from a persistence store. More...

void	RewindSubscription (String endpointName, String durableName, ITibProperties props)
	Rewind a durable. More...

void	SetLogFiles (String filePrefix, long maxFileSize, int maxFiles, ITibProperties properties)
	Arrange rotating log files for the realm. More...

void	SetLogHandler (ILogHandler logHandler, ITibProperties properties)
	Register a log handler for the realm. More...

void	SetLogLevel (String level)
	Set the global log trace level for low-level FTL internal calls for a specified realm. More...

void	SetNotificationHandler (INotificationHandler handler)
	Register the notification handler. More...

void	Unsubscribe (string endpointName, string dynamicDurableName)
	Destroy a dynamic durable. More...

void	Unsubscribe (string endpointName, string dynamicDurableName, ITibProperties props)
	Destroy a dynamic durable. More...

Properties
ITibProperties	Properties `[get]`
	Get a copy of the realm connection properties. More...

string	ServerUrl `[get]`
	Get the URL string that your program supplied to FTL.ConnectToRealmServer. More...

Detailed Description

Realm objects contain definitions of message formats, endpoints and transport maps.

The IRealm interface includes methods to create messages, message field references, publishers, subscribers, event queues and content matchers.

To create a realm object, call FTL.ConnectToRealmServer.

Customers do not implement this interface.

Member Function Documentation

◆ CreateBrowser()

ITibBrowser TIBCO.FTL.IRealm.CreateBrowser	(	String	endpointName,
		String	durableName,
		ITibProperties	props
	)

Create a browser.

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

See also: ITibBrowser.Next(), ITibBrowser.DeleteMessage()

Parameters

endpointName	The endpoint identifies the browser's store configuration within the realm. The endpoint must have the same store and durable template as the endpoint used by the durable subscriber.
durableName	The durable to browse.
props	Optional. `null` to omit.

Properties:

Returns: A new browser object

◆ CreateContentMatcher()

IContentMatcher TIBCO.FTL.IRealm.CreateContentMatcher ( string MatchString )

Create a content matcher.

An application can create a matcher to register interest in a stream of messages.

Programs must IDisposable.Dispose content matcher objects to reclaim resources. For maximum performance, Dispose a content matcher as soon as possible after creating all the subscriber objects that use it.

Match Syntax:

{"<em>fieldname1</em>":value1, ... , "<em>fieldnameN</em>":valueN}

Enclose the list of field:value pairs in curly braces.
Separate field:value pairs with commas.
Enclose field names in double-quote characters. Precede quote characters with an escape character, as needed.
Do not enclose boolean tokens in double-quote characters.
Each field name can appear at most once.
Values can be long integers or strings – or the special boolean tokens true or false.
When value is a string, its maximum length is 256 characters.
Whitespace is ignored (except within double-quote characters).

Match Semantics:

If the match string specifies a field with boolean token true, that field must be present in the message in order to match.
If the match string specifies a field with boolean token false, that field must be absent from the message in order to match.
If the match string specifies a field with either a string or long integer value, that field must be present in the message with that value.
When comparing a field name or a value, all comparisons must be exact. Matching does not support wildcards nor regular expressions.

Parameters

MatchString This string determines message interest.

Returns: A new content matcher object.

See also: IRealm.CreateSubscriber(string, IContentMatcher)

◆ CreateEventQueue() [1/2]

IEventQueue TIBCO.FTL.IRealm.CreateEventQueue ( )

Create an event queue.

Returns: A new event queue object.

See also: FTL.EVENTQUEUE_PROPERTY_BOOL_INLINE_MODE

◆ CreateEventQueue() [2/2]

IEventQueue TIBCO.FTL.IRealm.CreateEventQueue ( ITibProperties props )

Create an event queue.

Programs must IDisposable.Dispose event queue objects to reclaim resources.

Parameters

props Property values configure event queue behavior.

Returns: A new event queue object.

See also: FTL.EVENTQUEUE_PROPERTY_BOOL_INLINE_MODE

◆ CreateInboxSubscriber() [1/2]

IInboxSubscriber TIBCO.FTL.IRealm.CreateInboxSubscriber ( string endpointName )

Create an inbox subscriber.

Applications use inbox subscriber objects to register interest in a stream of inbox messages.

Because inbox messages do not trigger the content matchers of other subscribers on the endpoint, they are an efficient way to target a message to a specific destination. For example, you might use an inbox message to query a specific data source, or to reply to a query.

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

Programs must IDisposable.Dispose inbox subscriber objects to reclaim resources.

Parameters

endpointName The endpoint identifies the subscriber's data stream within the realm. To use the default endpoint, supply null.

Returns: A new subscriber object.

◆ CreateInboxSubscriber() [2/2]

IInboxSubscriber TIBCO.FTL.IRealm.CreateInboxSubscriber	(	string	endpointName,
		ITibProperties	props
	)

Create an inbox subscriber.

Applications use inbox subscriber objects to register interest in a stream of inbox messages.

Because inbox messages do not trigger the content matchers of other subscribers on the endpoint, they are an efficient way to target a message to a specific destination. For example, you might use an inbox message to query a specific data source, or to reply to a query.

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

Programs must IDisposable.Dispose inbox subscriber objects to reclaim resources.

Parameters

endpointName	The endpoint identifies the subscriber's data stream within the realm. To use the default endpoint, supply `null`
props	Message ownership property: FTL.SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK

Returns: A new subscriber object.

◆ CreateLock()

ITibLock TIBCO.FTL.IRealm.CreateLock	(	String	lockName,
		ITibProperties	props
	)

Create a lock object.

Cooperating application programs can use locks to implement exclusive access to a map within a persistence store.

Lock objects with the same lock name represent the same lock within the persistence store.

Note that the lock is actually acquired by map calls for objects associated with a lock. See:

Parameters

lockName	The lock object represents the lock with this name in the store.
props	Persistence property: FTL.TIBLOCK_PROPERTY_DOUBLE_LOCK_ACQUIRE_RETRY_DURATION

Returns: A new lock object.

◆ CreateMap()

ITibMap TIBCO.FTL.IRealm.CreateMap	(	String	endpointName,
		String	mapName,
		ITibProperties	props
	)

Create a map object.

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 as a dynamic durable.

Parameters

endpointName The map object represents a map within the store associated with this endpoint.

mapName The map object represents the map with this name.

props

Persistence property:

FTL.TIBMAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

Other properties:

FTL.SUBSCRIBER_PROPERTY_STRING_LABEL

Returns: A new map object.

◆ CreateMessage() [1/3]

IMessage TIBCO.FTL.IRealm.CreateMessage ( )

Create a mutable message object with an unnamed dynamic format (for use only in one specific message).

Programs can use this call to create messages for sending.

Message objects are not thread-safe. Programs must not access a message from several threads simultaneously.

Programs must IDisposable.Dispose mutable message objects to reclaim resources.

Returns: A new message object.

◆ CreateMessage() [2/3]

IMessage TIBCO.FTL.IRealm.CreateMessage	(	byte[]	bytes,
		int	length
	)

Create a message from a byte-array representation.

This call reconstitutes a message object from its serialized byte-array representation.

After this method returns, you may re-use or discard the byte-array.

To allow programs to reuse the byte array, it may be longer than the actual bytes that represent the message. The length parameter is used to indicate the actual number of bytes associated with the serialized message.

Programs must IDisposable.Dispose mutable message objects to reclaim resources.

Parameters

bytes	The method reads the serialized message from this byte-array.
length	The method copies only this number of bytes from the byte-array.

Returns: A new message object.

◆ CreateMessage() [3/3]

IMessage TIBCO.FTL.IRealm.CreateMessage ( string formatName )

Create a mutable message object.

Programs can use this call to create messages for sending.

Message objects are not thread-safe. Programs must not access a message from several threads simultaneously.

For built-in format names, see FTL.

Programs must IDisposable.Dispose mutable message objects to reclaim resources.

Parameters

formatName The call creates a message with this format. null is a special value, indicating an unnamed dynamic format (for use only in one specific message).

Returns: A new message object.

◆ CreateMessageFieldRef()

IMessageFieldRef TIBCO.FTL.IRealm.CreateMessageFieldRef ( string fieldName )

Create a field reference object.

This method uses its fieldName argument to look up internal information that enables efficient access, and caches that information in the new field reference object.

Programs must IDisposable.Dispose field reference objects to reclaim resources.

Parameters

fieldName The method embeds this field name in the new field reference object.

Returns: A new field reference object.

◆ CreatePublisher() [1/2]

IPublisher TIBCO.FTL.IRealm.CreatePublisher ( string endpointName )

Create a publisher.

Applications use publisher objects to send messages.

Programs must IDisposable.Dispose publisher objects to reclaim resources.

Parameters

endpointName The endpoint identifies the publisher's data stream within the realm. To use the default endpoint, supply null.

Returns: A new publisher object.

◆ CreatePublisher() [2/2]

IPublisher TIBCO.FTL.IRealm.CreatePublisher	(	string	endpointName,
		ITibProperties	properties
	)

Create a publisher.

Applications use publisher objects to send messages.

Programs must IDisposable.Dispose publisher objects to reclaim resources.

Parameters

endpointName The endpoint identifies the publisher's data stream within the realm. To use the default endpoint, supply null.

properties

Persistence property:

Message ownership property:

FTL.PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND

Other properties:

Returns: A new publisher object.

◆ CreateSubscriber() [1/4]

ISubscriber TIBCO.FTL.IRealm.CreateSubscriber ( string endpointName )

Create a subscriber.

Applications use subscriber objects to register interest in a stream of messages (sent with one-to-many send calls).

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

Programs must IDisposable.Dispose subscriber objects to reclaim resources.

Parameters

endpointName The endpoint identifies the subscriber's data stream within the realm. To use the default endpoint, supply null.

Returns: A new subscriber object.

◆ CreateSubscriber() [2/4]

ISubscriber TIBCO.FTL.IRealm.CreateSubscriber	(	string	endpointName,
		IContentMatcher	matcher
	)

Create a subscriber.

Applications use subscriber objects to register interest in a stream of messages (sent with one-to-many send calls).

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

Programs must IDisposable.Dispose subscriber objects to reclaim resources.

Parameters

endpointName	The endpoint identifies the subscriber's data stream within the realm. To use the default endpoint, supply `null`.
matcher	The matcher filters messages based on their content.

Returns: A new subscriber object.

◆ CreateSubscriber() [3/4]

ISubscriber TIBCO.FTL.IRealm.CreateSubscriber	(	string	endpointName,
		IContentMatcher	matcher,
		ITibProperties	props
	)

Create a subscriber.

Applications use subscriber objects to register interest in a stream of messages (sent with one-to-many send calls).

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

Programs must IDisposable.Dispose subscriber objects to reclaim resources.

Parameters

endpointName The endpoint identifies the subscriber's data stream within the realm. To use the default endpoint, supply null.

matcher The matcher filters messages based on their content.

props

Persistence properties:

Message ownership property:

FTL.SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK

Other properties:

FTL.SUBSCRIBER_PROPERTY_STRING_LABEL

Returns: A new subscriber object.

◆ CreateSubscriber() [4/4]

ISubscriber TIBCO.FTL.IRealm.CreateSubscriber	(	string	endpointName,
		ITibProperties	props
	)

Create a subscriber.

Applications use subscriber objects to register interest in a stream of messages (sent with one-to-many send calls).

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

Programs must IDisposable.Dispose subscriber objects to reclaim resources.

Parameters

endpointName The endpoint identifies the subscriber's data stream within the realm. To use the default endpoint, supply null.

props

Persistence properties:

Message ownership property:

FTL.SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK

Other properties:

FTL.SUBSCRIBER_PROPERTY_STRING_LABEL

Returns: A new subscriber object.

◆ GetServerVersion()

String TIBCO.FTL.IRealm.GetServerVersion ( )

Return the FTLserver version the client is connected to.

Returns: The FTLServer version the client is connected to.

◆ RemoveMap()

void TIBCO.FTL.IRealm.RemoveMap	(	String	endpointName,
		String	mapName,
		ITibProperties	props
	)

Delete a map from a persistence store.

Parameters

endpointName	The call removes a map from the store associated with this endpoint.
mapName	The call removes the map with this name from the store.
props	Persistence property: FTL.TIBMAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

◆ RewindSubscription()

void TIBCO.FTL.IRealm.RewindSubscription	(	String	endpointName,
		String	durableName,
		ITibProperties	props
	)

Rewind a durable.

Rewinding a durable returns the durable to an earlier state. Messages that were acknowledged and are still retained by the server will be delivered again when the next subscriber is created on the durable.

For this call to succeed, message retention must be enabled for the durable. Message retention causes successfully acknowledged messages to be preserved for some amount of time, as specified in the realm configuration.

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

FTL.SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION can be specified in 'props' to specify a duration for the persistence call. The call will be retried for the specified time, after which it fails.

◆ SetLogFiles()

void TIBCO.FTL.IRealm.SetLogFiles	(	String	filePrefix,
		long	maxFileSize,
		int	maxFiles,
		ITibProperties	properties
	)

Arrange rotating log files for the realm.

The filename extension .0 indicates the current log file. Rotation shifts each file by incrementing its numeric extension. If the number of files would exceed the maximum, rotation deletes the oldest file.

Parameters

filePrefix	All log files begin with this filename prefix.
maxFileSize	FTL rotates the log files when the current log file exceeds this limit (in bytes). This value must be greater than 102400 (100 kilobytes).
maxFiles	FTL limits the number of log files to this maximum.
properties	Reserved for future use. To ensure forward compatibility, programmers must supply `null`.

◆ SetLogHandler()

void TIBCO.FTL.IRealm.SetLogHandler	(	ILogHandler	logHandler,
		ITibProperties	properties
	)

Register a log handler for the realm.

If you register a log handler (at most one), then FTL directs all log statements associated with this realm to that handler.

Parameters

logHandler	FTL invokes this log handler to process all log statements.
properties	Reserved for future use. To ensure forward compatibility, programmers must supply `null`.

◆ SetLogLevel()

void TIBCO.FTL.IRealm.SetLogLevel ( String level )

Set the global log trace level for low-level FTL internal calls for a specified realm.

Parameters

level The call sets the level to this value.

Set one log level for all logging elements, e.g., TIB_LOG_LEVEL_WARN.

Or, set log levels per element tag, e.g.,"transports:warn;api:debug".

Valid Levels:

Valid Element Tags:

all - applies to all elements.
application - logging for the application, e.g., API calls, message formats, and content matchers.
transports - logging for transports, including peer connections, subscriber interest, message sends, protocols.
msg - logging related to messages. For debug, print a representation of each inbound/outbound message.
api - logging related to API calls.

For more information, see the topic Log Levels in the book TIBCO FTL Development.

◆ SetNotificationHandler()

void TIBCO.FTL.IRealm.SetNotificationHandler ( INotificationHandler handler )

Register the notification handler.

Programs may register at most one notification handler per realm. It is good practice for all programs do so. For background information, see INotificationHandler.

Parameters

handler The method registers this notification handler on the realm.

See also: INotificationHandler

◆ Unsubscribe() [1/2]

void TIBCO.FTL.IRealm.Unsubscribe	(	string	endpointName,
		string	dynamicDurableName
	)

Destroy a dynamic durable.

Destroying a dynamic durable removes it from the store.

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

It is an error to use this call to unsubscribe from a static durable.

Parameters

endpointName	The call destroys a dynamic durable in the store associated with this endpoint.
dynamicDurableName	The call destroys the dynamic durable with this name.

◆ Unsubscribe() [2/2]

void TIBCO.FTL.IRealm.Unsubscribe	(	string	endpointName,
		string	dynamicDurableName,
		ITibProperties	props
	)

Destroy a dynamic durable.

Destroying a dynamic durable removes it from the store.

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

FTL.SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION can be specified in 'props' to specify a duration for persistence call. The call will be retried for the specified time, after which it fails.

It is an error to use this call to unsubscribe from a static durable.

Parameters

endpointName	The call destroys a dynamic durable in the store associated with this endpoint.
dynamicDurableName	The call destroys the dynamic durable with this name.
props	Persistence property: FTL.SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

Property Documentation

◆ Properties

ITibProperties TIBCO.FTL.IRealm.Properties

get

Get a copy of the realm connection properties.

Programs must IDisposable.Dispose the copy to reclaim resources.

◆ ServerUrl

string TIBCO.FTL.IRealm.ServerUrl

get

Get the URL string that your program supplied to FTL.ConnectToRealmServer.

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ CreateBrowser()

◆ CreateContentMatcher()

◆ CreateEventQueue() [1/2]

◆ CreateEventQueue() [2/2]

◆ CreateInboxSubscriber() [1/2]

◆ CreateInboxSubscriber() [2/2]

◆ CreateLock()

◆ CreateMap()

◆ CreateMessage() [1/3]

◆ CreateMessage() [2/3]

◆ CreateMessage() [3/3]

◆ CreateMessageFieldRef()

◆ CreatePublisher() [1/2]

◆ CreatePublisher() [2/2]

◆ CreateSubscriber() [1/4]

◆ CreateSubscriber() [2/4]

◆ CreateSubscriber() [3/4]

◆ CreateSubscriber() [4/4]

◆ GetServerVersion()

◆ RemoveMap()

◆ RewindSubscription()

◆ SetLogFiles()

◆ SetLogHandler()

◆ SetLogLevel()

◆ SetNotificationHandler()

◆ Unsubscribe() [1/2]

◆ Unsubscribe() [2/2]

Property Documentation

◆ Properties

◆ ServerUrl