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 java.lang.String	DEST_BROWSER_PROPERTY_STRING_DURABLE_NAME
static long	HTTPS_CONNECTION_TRUST_EVERYONE Deprecated. Trust any FTL server; property value constant. This constant is deprecated. There is no need to use Realm.PROPERTY_LONG_TRUST_TYPE. Use Realm.PROPERTY_BOOL_TRUST_EVERYONE instead. 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.
static long	HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE Deprecated. Trust an FTL server if its certificate is in a trust file; property value constant. This constant is deprecated. There is no need to use Realm.PROPERTY_LONG_TRUST_TYPE. 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.
static long	HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING Deprecated. Trust an FTL server if its certificate is in a trust string; property value constant. This constant is deprecated. There is no need to use Realm.PROPERTY_LONG_TRUST_TYPE. 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.
static java.lang.String	PROPERTY_BOOL_TRUST_EVERYONE Property name for skipping TLS certificate validation; boolean.
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_SECURITY_LEVEL Property name for TLS security level; long.
static java.lang.String	PROPERTY_LONG_TRUST_TYPE Deprecated. Property name for secure FTL server trust type; long. This property is deprecated. Omit this property; instead, use Realm.PROPERTY_STRING_TRUST_FILE, Realm.PROPERTY_STRING_TRUST_PEM_STRING, or Realm.PROPERTY_BOOL_TRUST_EVERYONE. To use the system trust store, omit all of these properties. Supply this property to FTL.connectToRealmServer. Its value determines trust in the FTL server's certificate.
static java.lang.String	PROPERTY_STRING_APPINSTANCE_IDENTIFIER Property name for application instance identifier; string.
static java.lang.String	PROPERTY_STRING_CLIENT_CERT Property name for client identity certificate; string.
static java.lang.String	PROPERTY_STRING_CLIENT_LABEL Property name for client label; string.
static java.lang.String	PROPERTY_STRING_CLIENT_PRIVATE_KEY Property name for client certificate's private key; string.
static java.lang.String	PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD Property name for client certificate's private key password; 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_OAUTH2_ACCESS_TOKEN Property name to specify OAuth 2.0 access token.
static java.lang.String	PROPERTY_STRING_OAUTH2_CLIENT_ID Property name for OAuth 2.0 client id, this client id is required.
static java.lang.String	PROPERTY_STRING_OAUTH2_CLIENT_SECRET Property name for OAuth 2.0 client secret, this client secret is required to get the OAuth 2.0 access token; string
static java.lang.String	PROPERTY_STRING_OAUTH2_SERVER_TRUST_FILE Property name for OAuth 2.0 server specific trust file.
static java.lang.String	PROPERTY_STRING_OAUTH2_SERVER_URL Property name for OAuth 2.0 server URL.
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.
TibBrowser	createBrowser(java.lang.String endpointName, java.lang.String durableName, TibProperties props) Create a browser.
ContentMatcher	createContentMatcher(java.lang.String matchString) Create a content matcher.
TibBrowser	createDestBrowser(java.lang.String dest, TibProperties props) Create a Destination Browser object.
DestPublisher	createDestPublisher(java.lang.String dest, TibProperties props) Create a destPublisher object.
DestSubscriber	createDestSubscriber(java.lang.String dest, TibProperties props) Create a destination subscriber object
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.
TibMap	createMapOnDest(java.lang.String dest, 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	removeMapOnDest(java.lang.String dest, TibProperties props) Remove a map object on dest.
void	rewindDest(java.lang.String dest, TibProperties props) Rewind either the durable on the destination or the queue The destination name.
void	rewindSubscription(java.lang.String endpointName, java.lang.String durableName, TibProperties props) Rewind a durable.
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.
void	unsubscribe(java.lang.String endpointName, java.lang.String dynamicDurableName, TibProperties props) Destroy a dynamic durable.
void	unsubscribeDest(java.lang.String dest, java.lang.String durableName, TibProperties props) Destroy a durable on a destination.

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

@Deprecated
static final long HTTPS_CONNECTION_TRUST_EVERYONE

Deprecated. Trust any FTL server; property value constant.

This constant is deprecated. There is no need to use Realm.PROPERTY_LONG_TRUST_TYPE. Use Realm.PROPERTY_BOOL_TRUST_EVERYONE instead.

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

@Deprecated
static final long HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE

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

This constant is deprecated. There is no need to use Realm.PROPERTY_LONG_TRUST_TYPE.

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

@Deprecated
static final long HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING

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

This constant is deprecated. There is no need to use Realm.PROPERTY_LONG_TRUST_TYPE.

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

@Deprecated
static final java.lang.String PROPERTY_LONG_TRUST_TYPE

Deprecated. Property name for secure FTL server trust type; long.

This property is deprecated. Omit this property; instead, use Realm.PROPERTY_STRING_TRUST_FILE, Realm.PROPERTY_STRING_TRUST_PEM_STRING, or Realm.PROPERTY_BOOL_TRUST_EVERYONE. To use the system trust store, omit all of these properties.

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.

Use this property to indicate the location of the trust file for TLS connections to FTL server. The file must contain one or more certificiates in PEM format.

If the trust file contains only an FTL-issued root certificate (ftl-trust.pem), the library will also try to verify FTL server's certificate against the system trust store.

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.

Use this property to supply a trust string for TLS connections to FTL server. The string must contain one or more certificates in PEM format.

If the trust string contains only an FTL-issued root certificate, the library will also try to verify FTL server's certificate against the system trust store.

See Also:

Constant Field Values

PROPERTY_BOOL_TRUST_EVERYONE

static final java.lang.String PROPERTY_BOOL_TRUST_EVERYONE

Property name for skipping TLS certificate validation; boolean.

Supply this property to 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

PROPERTY_LONG_SECURITY_LEVEL

static final java.lang.String PROPERTY_LONG_SECURITY_LEVEL

Property name for TLS security level; long.

Supply this property to FTL.connectToRealmServer.

The value of this property must be an integer between 0 and 5, inclusive.

If the administrator has configured a user-defined certificate at FTL server, the given security level is applied to all TLS connections to FTL server. In general, increasing the security level enforces stricter requirements for certificate keys, signatures, and ciphers. In particular, if the user-provided certificate does not meet the key requirements, the TLS connection will fail. The default security level is 2. FTL will enforce a minimum TLS version of 1.2 regardless of the actual security level.

If the administrator instead uses FTL-issued certificates for TLS, the given security level cannot be greater than 4. FTL will enforce a minimum TLS version of 1.3 when using FTL-issued certificates.

Refer to the openssl documentation for a precise definition of the openssl security level.

See Also:

Constant Field Values

PROPERTY_STRING_CLIENT_CERT

static final java.lang.String PROPERTY_STRING_CLIENT_CERT

Property name for client identity certificate; string.

Supply this property to FTL.connectToRealmServer.

As an alternative to user/password, client applications may use a TLS certificate to authenticate to FTL server. A TLS connection is required. Applications must also specify the private key alongside the certificate.

The value of this property must be a PEM file containing the certificate. The PEM file may also include intermediate certificates.

Administrators are responsible for distributing client certificates to applications. The client's auth roles should be encoded as a comma- separated list in the common name (CN) field of the client certificate.

See Also:

PROPERTY_STRING_CLIENT_PRIVATE_KEY, PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD, Constant Field Values

PROPERTY_STRING_CLIENT_PRIVATE_KEY

static final java.lang.String PROPERTY_STRING_CLIENT_PRIVATE_KEY

Property name for client certificate's private key; string.

Supply this property to FTL.connectToRealmServer.

When using a TLS certificate to authenticate to FTL server, the corresponding private key and passphrase must be specified as well.

The value of this property must be a PEM file containing the private key.

See Also:

PROPERTY_STRING_CLIENT_CERT, PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD, Constant Field Values

PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD

static final java.lang.String PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD

Property name for client certificate's private key password; string.

Supply this property to FTL.connectToRealmServer.

When using a TLS certificate to authenticate to FTL server, the corresponding private key and passphrase must be specified as well.

The value of this property must be a passphrase used to decrypt the private key.

See Also:

PROPERTY_STRING_CLIENT_CERT, PROPERTY_STRING_CLIENT_PRIVATE_KEY, Constant Field Values

PROPERTY_STRING_OAUTH2_SERVER_URL

static final java.lang.String PROPERTY_STRING_OAUTH2_SERVER_URL

Property name for OAuth 2.0 server URL.

When this parameter is specified along with PROPERTY_STRING_OAUTH2_CLIENT_SECRET and PROPERTY_STRING_OAUTH2_CLIENT_ID, FTL client library will connect to the OAuth 2.0 server specified to get the OAuth 2.0 access token prior to connecting to the FTL Server. If this url scheme starts with https:// then specify PROPERTY_STRING_OAUTH2_SERVER_TRUST_FILE

Supply this property to FTL.connectToRealmServer.

See Also:

Constant Field Values

PROPERTY_STRING_OAUTH2_CLIENT_ID

static final java.lang.String PROPERTY_STRING_OAUTH2_CLIENT_ID

Property name for OAuth 2.0 client id, this client id is required. to get the OAuth 2.0 access token; string

When this parameter is specified along with TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_URL and TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_SECRET, FTL client library will connect to the OAuth 2.0 server specified to get the OAuth 2.0 access token prior to connecting to the FTL Server.

Supply this property to FTL.connectToRealmServer.

See Also:

Constant Field Values

PROPERTY_STRING_OAUTH2_CLIENT_SECRET

static final java.lang.String PROPERTY_STRING_OAUTH2_CLIENT_SECRET

Property name for OAuth 2.0 client secret, this client secret is required to get the OAuth 2.0 access token; string

When this parameter is specified along with REALM_PROPERTY_STRING_OAUTH2_SERVER_URL and REALM_PROPERTY_STRING_OAUTH2_CLIENT_ID, FTL client library will connect to the OAuth 2.0 server specified to get the OAuth 2.0 access token prior to connecting to the FTL Server

Supply this property to FTL.connectToRealmServer.

See Also:

Constant Field Values

PROPERTY_STRING_OAUTH2_SERVER_TRUST_FILE

static final java.lang.String PROPERTY_STRING_OAUTH2_SERVER_TRUST_FILE

Property name for OAuth 2.0 server specific trust file.

When the connection to the OAuth 2.0 server is secure, specify this trust file, so the client knows who to trust.

Supply this property to FTL.connectToRealmServer.

See Also:

Constant Field Values

PROPERTY_STRING_OAUTH2_ACCESS_TOKEN

static final java.lang.String PROPERTY_STRING_OAUTH2_ACCESS_TOKEN

Property name to specify OAuth 2.0 access token.

When this parameter is specified, the FTL client library will use this access token to connect to FTL server.

If this property is specified then FTL client library will not attempt to fetch an access token from the OAuth 2.0 server.

>

Supply this property to FTL.connectToRealmServer.

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.

This property applies only to tibRealm_Connect and does not affect reconnects if the client loses connection to the FTL server.

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'

This property applies only to tibRealm_Connect and does not affect reconnects if the client loses connection to the FTL server.

See Also:

Constant Field Values

DEST_BROWSER_PROPERTY_STRING_DURABLE_NAME

static final java.lang.String DEST_BROWSER_PROPERTY_STRING_DURABLE_NAME

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
• Publisher.PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER
• Publisher.PROPERTY_INT_MAX_BATCH_COUNT

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

unsubscribe

void unsubscribe(java.lang.String endpointName,
                 java.lang.String dynamicDurableName,
                 TibProperties props)
          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.

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.

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

Persistence property:

• Subscriber.PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

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

Persistence property:

• TibMap.PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

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

createBrowser

TibBrowser createBrowser(java.lang.String endpointName,
                         java.lang.String durableName,
                         TibProperties props)
                  throws FTLException

Create a browser.

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

See TibBrowser.next() and TibBrowser.deleteMessage(com.tibco.ftl.Message).

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

Properties:

• TibBrowser.PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION
• TibBrowser.PROPERTY_STRING_LABEL
• TibBrowser.PROPERTY_STRING_MATCHER

Returns:

a new browser object

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

rewindSubscription

void rewindSubscription(java.lang.String endpointName,
                        java.lang.String durableName,
                        TibProperties props)
                 throws FTLException

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.

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

Throws:

FTLException

createDestSubscriber

DestSubscriber createDestSubscriber(java.lang.String dest,
                                    TibProperties props)
                             throws FTLException

Create a destination subscriber object

Destination 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)

Parameters:

dest - The destination name.

props - The properties object

DestSubscriber.DEST_SUBSCRIBER_PROPERTY_STRING_NAME DestSubscriber#DEST_SUBSCRIBER_PROPERTY_STRING_LABEL DestSubscriber#DEST_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME DestSubscriber#DEST_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK DestSubscriber#DEST_SUBSCRIBER_PROPERTY_X_DURABLE_TYPE (Shared, Standard, LastValue) DestSubscriber#DEST_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK DestSubscriber#DEST_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION DestSubscriber#DEST_SUBSCRIBER_PROPERTY_LONG_PREFETCH_SIZE DestSubscriber#DEST_SUBSCRIBER_PROPERTY_BOOL_NOLOCAL_MESSAGE_DELIVERY DestSubscriber#DEST_SUBSCRIBER_PROPERTY_STRING_MATCHER (for a given dest, if matcher is specfied then maatcher is applied after the dest is matched)

Throws:

FTLException

createDestPublisher

DestPublisher createDestPublisher(java.lang.String dest,
                                  TibProperties props)
                           throws FTLException

Create a destPublisher object.

A DestPublisher 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 name have to be prefixed with Q: e.g Q:foo1) 2. or NULL (NULL is used for late binding) The library will attempt to find the store associated with this dest (i.e if this dest is specific) from the realm config it receives as part of realm connect and if found it will synthesize an endpoint associated with the store and create the store publisher id and the internal store publisher object. If the destination is NON NULL then the mapping from destination to store has to exist, if not we return an error.

If the destination is NULL, the library will create an empty destPublisher and the internal store destPublisher object/s (and the corresponding destPublisher id/s) will be created when the first message is sent on the destination. Essentially is the late binding feature

Parameters:

dest - The destination name.

props - The properties object. The following properties are possible item> FTL.DEST_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS FTL.DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION FTL.DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER FTL.DEST_PUBLISHER_PROPERTY_STRING_LABEL FTL.DEST_PUBLISHER_PROPERTY_INT_SEND_POLICY FTL.DEST_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT (total across all the individual topics)

Throws:

FTLException

rewindDest

void rewindDest(java.lang.String dest,
                TibProperties props)
         throws FTLException

Rewind either the durable on the destination or the queue The destination name. The properties object.

Throws:

FTLException

unsubscribeDest

void unsubscribeDest(java.lang.String dest,
                     java.lang.String durableName,
                     TibProperties props)
              throws FTLException

Destroy a durable on a destination.

Destroying a durable removes it from the store. If one client destroys a durable while other clients have subscribers to it, subsequent behavior is undefined.

Parameters:

dest - The destination name.

durableName - The name of the durable to destroy.

props - The properties object.

Throws:

FTLException

createDestBrowser

TibBrowser createDestBrowser(java.lang.String dest,
                             TibProperties props)
                      throws FTLException

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

Parameters:

dest - The destination can be either a topic or a queue name (queue name have to be prefixed with Q: e.g Q:foo1)

props - Optional. see cref="FTL.TIB_BROWSER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION" see cref="FTL.TIB_BROWSER_PROPERTY_STRING_LABEL" see cref="FTL.TIB_BROWSER_PROPERTY_STRING_MATCHER" see cref="FTL.TIB_DEST_BROWSER_PROPERTY_STRING_DURABLE_NAME"

Throws:

FTLException

createMapOnDest

TibMap createMapOnDest(java.lang.String dest,
                       TibProperties props)
                throws FTLException

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.

Parameters:

dest - The dest on which to create the map object. (dest name have to have a prefix of M:<>)

props - Optional.

Throws:

FTLException

removeMapOnDest

void removeMapOnDest(java.lang.String dest,
                     TibProperties props)
              throws FTLException

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

Parameters:

dest - The dest on which to remove the map object. (dest name have to have a prefix of M:<>)

props - Optional.

Throws:

FTLException