TIBCO FTL®

Public Member Functions | Properties | List of all members
TIBCO.FTL.IRealm Interface Reference

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:

- FTL.BROWSER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION
- FTL.BROWSER_PROPERTY_STRING_LABEL
- FTL.BROWSER_PROPERTY_STRING_MATCHER

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:

- ITibMap.CreateIterator(ITibLock, ITibProperties)
- ITibMap.GetSize(ITibLock)
- ITibMap.Get(string, ITibLock)
- ITibMap.RemoveAll(ITibLock)
- ITibMap.Remove(string, ITibLock)
- ITibMap.Set(string, IMessage, ITibLock)
- ITibMap.Set(String[], IMessage[], ITibLock)

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: FTL.PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION FTL.PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT FTL.PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER Message ownership property: FTL.PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND Other properties: FTL.PUBLISHER_PROPERTY_STRING_LABEL FTL.PUBLISHER_PROPERTY_STRING_REPLY_ENDPOINT FTL.PUBLISHER_PROPERTY_INT_SEND_POLICY

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: FTL.SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME FTL.SUBSCRIBER_PROPERTY_STRING_NAME FTL.SUBSCRIBER_PROPERTY_STRING_KEY_FIELD_NAME FTL.SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK FTL.SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION 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: FTL.SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME FTL.SUBSCRIBER_PROPERTY_STRING_NAME FTL.SUBSCRIBER_PROPERTY_STRING_KEY_FIELD_NAME FTL.SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK FTL.SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION 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:

- FTL.LOG_LEVEL_OFF, off
- FTL.LOG_LEVEL_SEVERE, severe
- FTL.LOG_LEVEL_WARN, warn
- FTL.LOG_LEVEL_INFO, info
- FTL.LOG_LEVEL_VERBOSE, verbose
- FTL.LOG_LEVEL_DEBUG, debug

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.