public interface Realm
The realm interface has methods to create messages, message field references, publishers, subscribers, event queues and content matchers.
Customers do not implement this interface.
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.
|
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.
|
static final java.lang.String PROPERTY_STRING_USERNAME
Supply this property to
FTL.connectToRealmServer
,
which identifies your program to the FTL server with
the username value you supply.
static final java.lang.String PROPERTY_STRING_USERPASSWORD
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.
static final java.lang.String PROPERTY_STRING_SECONDARY_SERVER
static final java.lang.String PROPERTY_STRING_APPINSTANCE_IDENTIFIER
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.
static final java.lang.String PROPERTY_STRING_CLIENT_LABEL
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.
static final long HTTPS_CONNECTION_TRUST_EVERYONE
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 final long HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE
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 final long HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING
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 final java.lang.String PROPERTY_LONG_TRUST_TYPE
Supply this property to
FTL.connectToRealmServer
.
Its value determines
trust in the FTL server's certificate.
static final java.lang.String PROPERTY_STRING_TRUST_FILE
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.
static final java.lang.String PROPERTY_STRING_TRUST_PEM_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.
static final java.lang.String PROPERTY_LONG_CONNECT_RETRIES
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).
static final java.lang.String PROPERTY_DOUBLE_CONNECT_INTERVAL
FTL.connectToRealmServer
.
The connect call waits this interval (in seconds) between connection attempts.
The default value is 1.0 seconds.
static final java.lang.String PROPERTY_STRING_LOG_LEVEL
ContentMatcher createContentMatcher(java.lang.String matchString)
An application can create a matcher to register interest in a stream of messages.
Match Syntax:
{ "
fieldname1":
value1, ... ,"
fieldnameN":
valueN }
true
or false
. Match Semantics:
true
,
that field must be present in the message in order to match. false
,
that field must be absent from the message in order to match. matchString
- This string determines message interest.MessageFieldRef createMessageFieldRef(java.lang.String fieldName)
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.
fieldName
- The method embeds this field name in the new field reference object. null
.Publisher createPublisher(java.lang.String endpointName) throws FTLException
Applications use publisher objects to send messages.
endpointName
- The endpoint identifies the publisher's
data stream within the realm.
To use the default endpoint, supply null
. null
.FTLException
Publisher createPublisher(java.lang.String endpointName, TibProperties props) throws FTLException
Applications use publisher objects to send messages.
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:
Message ownership property:
Other properties:
null
.FTLException
Subscriber createSubscriber(java.lang.String endpointName, ContentMatcher matcher) throws FTLException
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.
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.FTLException
Subscriber createSubscriber(java.lang.String endpointName, ContentMatcher matcher, TibProperties props) throws FTLException
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.
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:
Other properties:
FTLException
InboxSubscriber createInboxSubscriber(java.lang.String endpointName) throws FTLException
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.
endpointName
- The endpoint identifies the subscriber's data stream within the realm.
To use the default endpoint, supply null
.FTLException
InboxSubscriber createInboxSubscriber(java.lang.String endpointName, TibProperties props) throws FTLException
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.
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:
Other properties:
FTLException
void unsubscribe(java.lang.String endpointName, java.lang.String dynamicDurableName) throws FTLException
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.
endpointName
- The call destroys a dynamic durable
in the store associated with this endpoint.dynamicDurableName
- The call destroys the dynamic durable
with this name.FTLException
Message createMessage(java.lang.String formatName)
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
.
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).Message createMessage(byte[] bytes, int length)
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.
bytes
- The method reads the serialized message from this byte-array.length
- The method copies only this number of bytes from the byte-array.EventQueue createEventQueue()
EventQueue.PROPERTY_BOOL_INLINE_MODE
EventQueue createEventQueue(TibProperties props)
props
- Optional.
Properties configure event queue behavior.
Supply null
to omit.EventQueue.PROPERTY_BOOL_INLINE_MODE
void setNotificationHandler(NotificationHandler handler) throws FTLException
Programs may register at most one notification handler per realm.
It is good practice for all programs do so.
For background information, see NotificationHandler
handler
- The method registers this notification handler on the realm.FTLException
void close() throws FTLException
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.
FTLException
java.lang.String getServerUrl() throws FTLException
This call returns a copy of the URL string that your program supplied to
FTL.connectToRealmServer
FTLException
TibProperties getProperties() throws FTLException
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
.
FTLException
TibLock createLock(java.lang.String lockName, TibProperties props) throws FTLException
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.
lockName
- The lock object represents the lock with this name
in the store.props
- Optional. Supply null to omit.
Persistence property:
FTLException
TibMap createMap(java.lang.String endpointName, java.lang.String mapName, TibProperties props) throws FTLException
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.
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:
Other properties:
FTLException
void removeMap(java.lang.String endpointName, java.lang.String mapName, TibProperties props) throws FTLException
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
.FTLException
void setLogLevel(java.lang.String level) throws FTLException
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".
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:
FTLException
void setLogFiles(java.lang.String filePrefix, long maxFileSize, int maxFiles, TibProperties properties) throws FTLException
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.
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.FTLException
void setLogHandler(LogHandler handler, TibProperties properties) throws FTLException
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.
handler
- FTL invokes this handler to process all log statements.properties
- Reserved for future use.
To ensure forward compatibility, programmers must supply null
.FTLException
java.lang.String getServerVersion()