com.tibco.ftl

Interface Realm

public interface Realm

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

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

Customers do not implement this interface.

Field Summary

Fields

Modifier and Type	Field and Description
static long	HTTPS_CONNECTION_TRUST_EVERYONE Trust any FTL server; property value constant.
static long	HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE Trust an FTL server if its certificate is in a trust file; property value constant.
static long	HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING Trust an FTL server if its certificate is in a trust string; property value constant.
static java.lang.String	PROPERTY_DOUBLE_CONNECT_INTERVAL Property name for the interval between connection attempts; double.
static java.lang.String	PROPERTY_LONG_CONNECT_RETRIES Property name for number of connection attempts; long.
static java.lang.String	PROPERTY_LONG_TRUST_TYPE Property name for secure FTL server trust type; long.
static java.lang.String	PROPERTY_STRING_APPINSTANCE_IDENTIFIER Property name for application instance identifier; string.
static java.lang.String	PROPERTY_STRING_CLIENT_LABEL Property name for client label; string.
static java.lang.String	PROPERTY_STRING_LOG_LEVEL Property name for setting log level via java system property NOTE: This property is specifically meant to be used as java system property example java -Dcom.tibco.ftl.log.level='transport:debug;api:debug'
static java.lang.String	PROPERTY_STRING_SECONDARY_SERVER Deprecated. Revise client code to use the core servers list instead.
static java.lang.String	PROPERTY_STRING_TRUST_FILE Property name for secure FTL server trust file; string.
static java.lang.String	PROPERTY_STRING_TRUST_PEM_STRING Property name for secure FTL server trust data; string.
static java.lang.String	PROPERTY_STRING_USERNAME Property name for FTL server username; string.
static java.lang.String	PROPERTY_STRING_USERPASSWORD Property name for FTL server password; string.

Method Summary

Modifier and Type	Method and Description
void	close() Close a realm object.
ContentMatcher	createContentMatcher(java.lang.String matchString) Create a content matcher.
EventQueue	createEventQueue() Create an event queue.
EventQueue	createEventQueue(TibProperties props) Create an event queue.
InboxSubscriber	createInboxSubscriber(java.lang.String endpointName) Create an inbox subscriber.
InboxSubscriber	createInboxSubscriber(java.lang.String endpointName, TibProperties props) Create an inbox subscriber.
TibLock	createLock(java.lang.String lockName, TibProperties props) Create a lock object.
TibMap	createMap(java.lang.String endpointName, java.lang.String mapName, TibProperties props) Create a map object.
Message	createMessage(byte[] bytes, int length) Create a message from a byte-array representation.
Message	createMessage(java.lang.String formatName) Create a mutable message object.
MessageFieldRef	createMessageFieldRef(java.lang.String fieldName) Create a field reference object.
Publisher	createPublisher(java.lang.String endpointName) Create a publisher.
Publisher	createPublisher(java.lang.String endpointName, TibProperties props) Create a publisher.
Subscriber	createSubscriber(java.lang.String endpointName, ContentMatcher matcher) Create a subscriber.
Subscriber	createSubscriber(java.lang.String endpointName, ContentMatcher matcher, TibProperties props) Create a subscriber.
TibProperties	getProperties() Get a copy of the realm connection properties.
java.lang.String	getServerUrl() Get a copy of the FTL server URL.
java.lang.String	getServerVersion() Return the version of the FTLserver the client is connected to.
void	removeMap(java.lang.String endpointName, java.lang.String mapName, TibProperties props) Delete a map from a persistence store.
void	setLogFiles(java.lang.String filePrefix, long maxFileSize, int maxFiles, TibProperties properties) Arrange rotating log files for the realm.
void	setLogHandler(LogHandler handler, TibProperties properties) Register a log handler for the realm.
void	setLogLevel(java.lang.String level) Set the log trace level for low-level FTL internal calls for a specified realm.
void	setNotificationHandler(NotificationHandler handler) Register the notification handler.
void	unsubscribe(java.lang.String endpointName, java.lang.String dynamicDurableName) Destroy a dynamic durable.

Field Detail

PROPERTY_STRING_USERNAME

static final java.lang.String PROPERTY_STRING_USERNAME

Property name for FTL server username; string.

Supply this property to FTL.connectToRealmServer, which identifies your program to the FTL server with the username value you supply.

See Also:

Constant Field Values

PROPERTY_STRING_USERPASSWORD

static final java.lang.String PROPERTY_STRING_USERPASSWORD

Property name for FTL server password; string.

Supply this property to FTL.connectToRealmServer, which authenticates your program to the FTL server with the password value you supply. This can be a masked password, which would be unmasked before being sent to the realm service.

See Also:

Constant Field Values

PROPERTY_STRING_SECONDARY_SERVER

static final java.lang.String PROPERTY_STRING_SECONDARY_SERVER

Deprecated. Revise client code to use the core servers list instead.

See Also:

Constant Field Values

PROPERTY_STRING_APPINSTANCE_IDENTIFIER

static final java.lang.String PROPERTY_STRING_APPINSTANCE_IDENTIFIER

Property name for application instance identifier; string.

It is good practice to include this property in the realm connect call of every application program. It gives administrators flexible control over application deployment and over the transports that carry message traffic.

For example, the program obtains the application identifier as a command line argument (or through another configuration mechanism). If an application identifier is present, then the program passes it to FTL.connectToRealmServer as the value of this property.

Within the realm, administrators can define one or more application instances, which tailor the connections between endpoints and transports. The value of this property selects from among those instances.

See Also:

Constant Field Values

PROPERTY_STRING_CLIENT_LABEL

static final java.lang.String PROPERTY_STRING_CLIENT_LABEL

Property name for client label; string.

It is good practice to include this property in the realm connect call of every application program. Administrators can use client labels in monitoring and management to recognize and distinguish among processes.

For example, the program obtains the client label as a command line argument (or through another configuration mechanism). If a client label is present, then the program passes it to FTL.connectToRealmServer as the value of this property.

See Also:

Constant Field Values

HTTPS_CONNECTION_TRUST_EVERYONE

static final long HTTPS_CONNECTION_TRUST_EVERYONE

Trust any FTL server; property value constant.

This constant is one possible value of the property Realm.PROPERTY_LONG_TRUST_TYPE in the method FTL.connectToRealmServer.

The client trusts any FTL server without verifying trust in the server's certificate. Do not use this value except for convenience in development and testing. It is not secure.

See Also:

Constant Field Values

HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE

static final long HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE

Trust an FTL server if its certificate is in a trust file; property value constant.

This constant is one possible value of the property Realm.PROPERTY_LONG_TRUST_TYPE in the method FTL.connectToRealmServer.

The client trusts the FTL server based on the trust file created by the FTL server and distributed by the administrator.

Specify the file path of the trust file in the property Realm.PROPERTY_STRING_TRUST_FILE.

See Also:

Constant Field Values

HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING

static final long HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING

Trust an FTL server if its certificate is in a trust string; property value constant.

This constant is one possible value of the property Realm.PROPERTY_LONG_TRUST_TYPE in the method FTL.connectToRealmServer.

The client trusts the FTL server based on a trust string.

Specify the trust string in the property Realm.PROPERTY_STRING_TRUST_PEM_STRING.

See Also:

Constant Field Values

PROPERTY_LONG_TRUST_TYPE

static final java.lang.String PROPERTY_LONG_TRUST_TYPE

Property name for secure FTL server trust type; long.

Supply this property to FTL.connectToRealmServer. Its value determines trust in the FTL server's certificate.

See Also:

HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE, HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING, HTTPS_CONNECTION_TRUST_EVERYONE, Constant Field Values

PROPERTY_STRING_TRUST_FILE

static final java.lang.String PROPERTY_STRING_TRUST_FILE

Property name for secure FTL server trust file; string.

Supply this property to FTL.connectToRealmServer.

If the realm connect call specifies the trust type as HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE, use this property to indicate the location of the trust file.

See Also:

Constant Field Values

PROPERTY_STRING_TRUST_PEM_STRING

static final java.lang.String PROPERTY_STRING_TRUST_PEM_STRING

Property name for secure FTL server trust data; string.

Supply this property to FTL.connectToRealmServer.

If the realm connect call specifies the trust type as HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING, use this property to supply the trust string in PEM format.

See Also:

Constant Field Values

PROPERTY_LONG_CONNECT_RETRIES

static final java.lang.String PROPERTY_LONG_CONNECT_RETRIES

Property name for number of connection attempts; long.

Supply this property to FTL.connectToRealmServer.

If the connect call cannot connect to the FTL server after this maximum number of connection attempts, it fails with an exception.

The default value is retry forever (0).

See Also:

Constant Field Values

PROPERTY_DOUBLE_CONNECT_INTERVAL

static final java.lang.String PROPERTY_DOUBLE_CONNECT_INTERVAL

Property name for the interval between connection attempts; double. Supply this property to FTL.connectToRealmServer.

The connect call waits this interval (in seconds) between connection attempts.

The default value is 1.0 seconds.

See Also:

Constant Field Values

PROPERTY_STRING_LOG_LEVEL

static final java.lang.String PROPERTY_STRING_LOG_LEVEL

Property name for setting log level via java system property NOTE: This property is specifically meant to be used as java system property example java -Dcom.tibco.ftl.log.level='transport:debug;api:debug'

See Also:

Constant Field Values

Method Detail

createContentMatcher

ContentMatcher createContentMatcher(java.lang.String matchString)

Create a content matcher.

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

Match Syntax: { "fieldname1":value1, ... ,"fieldnameN":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

createMessageFieldRef

MessageFieldRef createMessageFieldRef(java.lang.String fieldName)

Create a field reference object.

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

Parameters:

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

Returns:

On success, this method returns a new field reference object. On failure, this method returns null.

createPublisher

Publisher createPublisher(java.lang.String endpointName)
                   throws FTLException

Create a publisher.

Applications use publisher objects to send messages.

Parameters:

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

Returns:

On success, this method returns a new publisher object. On failure, this method returns null.

Throws:

FTLException

createPublisher

Publisher createPublisher(java.lang.String endpointName,
                          TibProperties props)
                   throws FTLException

Create a publisher.

Applications use publisher objects to send messages.

Parameters:

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

props - Optional. Supply null to omit.

Persistence property:

• Publisher.PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

Message ownership property:

• Publisher.PROPERTY_BOOL_RELEASE_MSGS_TO_SEND

Other properties:

• Publisher.PROPERTY_STRING_LABEL
• Publisher.PROPERTY_STRING_REPLY_ENDPOINT
• Publisher.PROPERTY_INT_SEND_POLICY

Returns:

On success, this method returns a new publisher object. On failure, this method returns null.

Throws:

FTLException

createSubscriber

Subscriber createSubscriber(java.lang.String endpointName,
                            ContentMatcher matcher)
                     throws FTLException

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.

Parameters:

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

matcher - Optional. The matcher filters messages based on their content. Supply null to omit.

Returns:

a new subscriber object

Throws:

FTLException

createSubscriber

Subscriber createSubscriber(java.lang.String endpointName,
                            ContentMatcher matcher,
                            TibProperties props)
                     throws FTLException

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.

Parameters:

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

matcher - Optional. The matcher filters messages based on their content. Supply null to omit.

props - Optional. Supply null to omit.

Persistence properties:

• Subscriber.PROPERTY_STRING_DURABLE_NAME
• Subscriber.PROPERTY_STRING_NAME
• Subscriber.PROPERTY_STRING_KEY_FIELD_NAME
• Subscriber.PROPERTY_BOOL_EXPLICIT_ACK
• Subscriber.PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

Message ownership property:

• Subscriber.PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK

Other properties:

• Subscriber.PROPERTY_STRING_LABEL

Returns:

a new subscriber object

Throws:

FTLException

createInboxSubscriber

InboxSubscriber createInboxSubscriber(java.lang.String endpointName)
                               throws FTLException

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.

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

Throws:

FTLException

createInboxSubscriber

InboxSubscriber createInboxSubscriber(java.lang.String endpointName,
                                      TibProperties props)
                               throws FTLException

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.

Parameters:

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

props - Optional. Supply null to omit.

Message ownership property:

• Subscriber.PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK

Other properties:

• Subscriber.PROPERTY_STRING_LABEL

Returns:

a new subscriber object

Throws:

FTLException

unsubscribe

void unsubscribe(java.lang.String endpointName,
                 java.lang.String dynamicDurableName)
          throws FTLException

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.

Throws:

FTLException

createMessage

Message createMessage(java.lang.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 Message.

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

createMessage

Message 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 destroy 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.

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, equivalent to the byte-array representation

createEventQueue

EventQueue createEventQueue()

Create an event queue.

Returns:

a new event queue object

See Also:

EventQueue.PROPERTY_BOOL_INLINE_MODE

createEventQueue

EventQueue createEventQueue(TibProperties props)

Create an event queue.

Parameters:

props - Optional. Properties configure event queue behavior. Supply null to omit.

Returns:

a new event queue object

See Also:

EventQueue.PROPERTY_BOOL_INLINE_MODE

setNotificationHandler

void setNotificationHandler(NotificationHandler handler)
                     throws FTLException

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 NotificationHandler

Parameters:

handler - The method registers this notification handler on the realm.

Throws:

FTLException

close

void close()
    throws FTLException

Close a realm object.

Closing a realm object frees all the resources associated with the realm, and invalidates all objects created using the realm (including messages, message field references, publishers, subscribers and content matchers).

However, closing a local realm object does not change or destroy any definitions on the FTL server.

Programs must not call this method within a listener callback method.

Throws:

FTLException

getServerUrl

java.lang.String getServerUrl()
                       throws FTLException

Get a copy of the FTL server URL.

This call returns a copy of the URL string that your program supplied to FTL.connectToRealmServer

Returns:

a copy of the FTL server URL string

Throws:

FTLException

getProperties

TibProperties getProperties()
                     throws FTLException

Get a copy of the realm connection properties.

This call returns a copy of the properties object that your program supplied to FTL.connectToRealmServer Your program must destroy this properties object (see TibProperties.destroy).

If your program did not supply any properties to the realm connect call, then this call returns null .

Returns:

a properties object that reflects the realm's connection properties

Throws:

FTLException

createLock

TibLock createLock(java.lang.String lockName,
                   TibProperties props)
            throws FTLException

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:

• TibMap.set(String, Message, TibLock)
• TibMap.set(String[], Message[], TibLock)
• TibMap.get(String, TibLock)
• TibMap.getSize(TibLock)
• TibMap.remove(String, TibLock)
• TibMap.removeAll()
• TibMap.createIterator(TibLock, TibProperties)

Parameters:

lockName - The lock object represents the lock with this name in the store.

props - Optional. Supply null to omit.

Persistence property:

• TibLock.PROPERTY_DOUBLE_LOCK_ACQUIRE_RETRY_DURATION

Returns:

A new lock object.

Throws:

FTLException

Since:

4.2

createMap

TibMap createMap(java.lang.String endpointName,
                 java.lang.String mapName,
                 TibProperties props)
          throws FTLException

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 - Optional. Supply null to omit.

Persistence property:

• TibMap.PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

Other properties:

• TibMap.PROPERTY_STRING_LABEL

Returns:

A new map object.

Throws:

FTLException

Since:

4.2

removeMap

void removeMap(java.lang.String endpointName,
               java.lang.String mapName,
               TibProperties props)
        throws FTLException

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.

Throws:

FTLException

Since:

4.2

setLogLevel

void setLogLevel(java.lang.String level)
          throws FTLException

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

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".

Parameters:

level - The call sets the level or levels to this value.

Valid levels:

• FTL.TIB_LOG_LEVEL_OFF, off
• FTL.TIB_LOG_LEVEL_SEVERE, severe
• FTL.TIB_LOG_LEVEL_WARN, warn
• FTL.TIB_LOG_LEVEL_INFO, info
• FTL.TIB_LOG_LEVEL_VERBOSE, verbose
• FTL.TIB_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.

Throws:

FTLException

setLogFiles

void setLogFiles(java.lang.String filePrefix,
                 long maxFileSize,
                 int maxFiles,
                 TibProperties properties)
          throws FTLException

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.

Throws:

FTLException

setLogHandler

void setLogHandler(LogHandler handler,
                   TibProperties properties)
            throws FTLException

Register a log handler for the realm.

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

Parameters:

handler - FTL invokes this handler to process all log statements.

properties - Reserved for future use. To ensure forward compatibility, programmers must supply null.

Throws:

FTLException

getServerVersion

java.lang.String getServerVersion()

Return the version of the FTLserver the client is connected to.

Returns:

The FTLServer version.

Since:

6.5