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

Inheritance diagram for TIBCO.FTL.IRealm:

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

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

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

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

IInboxSubscriber	CreateInboxSubscriber (string endpointName)
	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, ITibProperties props)
	Create a subscriber. More...

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

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

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

void	Unsubscribe (string endpointName, string dynamicDurableName)
	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

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)

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

IEventQueue TIBCO.FTL.IRealm.CreateEventQueue ( )

Create an event queue.

Returns: A new event queue object.

See Also: FTL.EVENTQUEUE_PROPERTY_BOOL_INLINE_MODE

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.

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.

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.

Parameters

lockName	The lock object represents the lock with this name in the store.
props	Reserved for future use. To ensure forward compatibility, programmers must supply `Null`.

Returns: A new lock object.

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

Returns: A new map object.

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.

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.

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.

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.

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.

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:

FTL.PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

Message ownership property:

FTL.PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND

Returns: A new publisher object.

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.

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.

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.

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.

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	Reserved for future use. To ensure forward compatibility, programmers must supply `Null`.

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

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.

Property Documentation

ITibProperties TIBCO.FTL.IRealm.Properties

get

Get a copy of the realm connection properties.

Programs must IDisposable.Dispose the copy to reclaim resources.

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

Property Documentation