com.tibco.ftl

## Class FTL

- java.lang.Object
- - com.tibco.ftl.FTL

-     public class FTL
      extends java.lang.Object

  The class FTL is the first entry point of an FTL program.

  Programs use it to create `Realm` and `TibProperties` objects, and to set log levels.

  Programs do not instantiate this class.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `TIB_LOG_LEVEL_DEBUG` Debug -- output trace entries for all events (debug, verbose, information, warning and severe events).
    `static java.lang.String` | `TIB_LOG_LEVEL_INFO` Info -- output trace entries for information, warning and severe events.
    `static java.lang.String` | `TIB_LOG_LEVEL_OFF` Off -- disable all tracing.
    `static java.lang.String` | `TIB_LOG_LEVEL_SEVERE` Severe -- output trace entries only for severe events.
    `static java.lang.String` | `TIB_LOG_LEVEL_VERBOSE` Verbose -- output trace entries for verbose, information, warning and severe events.
    `static java.lang.String` | `TIB_LOG_LEVEL_WARN` Warn -- output trace entries for warning and severe events.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Realm` | `connectToRealmServer(java.lang.String realmServerUrl, java.lang.String appName, TibProperties props)` Connect to an FTL server, and create a realm object.
    `static TibProperties` | `createProperties()` Create an empty property list object without any default values.
    `static java.lang.String` | `getVersionInformation()` Version of the FTL Java client library (Java archive file).
    `static void` | `setLogFiles(java.lang.String filePrefix, long maxFileSize, int maxFiles, TibProperties properties)` Arrange rotating log files.
    `static void` | `setLogFilesForRealm(long realm, java.lang.String filePrefix, long maxFileSize, int maxFiles, TibProperties properties)`
    `static void` | `setLogHandler(LogHandler handler, TibProperties properties)` Register a global log handler.
    `static void` | `setLogHandlerForRealm(long realm, LogHandler handler, TibProperties properties)`
    `static void` | `setLogLevel(java.lang.String level)` Set the global log trace level for low-level FTL internal calls.
    `static void` | `setLogLevelForRealm(long realm, java.lang.String level)`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### TIB_LOG_LEVEL_OFF

          public static final java.lang.String TIB_LOG_LEVEL_OFF

      Off -- disable all tracing.
      See Also:
        `setLogLevel`, Constant Field Values

    - #### TIB_LOG_LEVEL_SEVERE

          public static final java.lang.String TIB_LOG_LEVEL_SEVERE

      Severe -- output trace entries only for severe events.
      See Also:
        `setLogLevel`, Constant Field Values

    - #### TIB_LOG_LEVEL_WARN

          public static final java.lang.String TIB_LOG_LEVEL_WARN

      Warn -- output trace entries for warning and severe events.
      See Also:
        `setLogLevel`, Constant Field Values

    - #### TIB_LOG_LEVEL_INFO

          public static final java.lang.String TIB_LOG_LEVEL_INFO

      Info -- output trace entries for information, warning and severe events.
      See Also:
        `setLogLevel`, Constant Field Values

    - #### TIB_LOG_LEVEL_VERBOSE

          public static final java.lang.String TIB_LOG_LEVEL_VERBOSE

      Verbose -- output trace entries for verbose, information, warning and severe events.
      See Also:
        `setLogLevel`, Constant Field Values

    - #### TIB_LOG_LEVEL_DEBUG

          public static final java.lang.String TIB_LOG_LEVEL_DEBUG

      Debug -- output trace entries for all events (debug, verbose, information, warning and severe events).
      See Also:
        `setLogLevel`, Constant Field Values

  - ### Method Detail

    - #### createProperties

          public static TibProperties createProperties()
                                                throws FTLException

      Create an empty property list object without any default values.

      As a mechanism for configuring objects, some FTL creation calls accept a properties object, which contains paired property names and values.

      Returns:
        a new properties object
      Throws:
        `FTLException`

    - #### connectToRealmServer

          public static Realm connectToRealmServer(java.lang.String realmServerUrl,
                                                   java.lang.String appName,
                                                   TibProperties props)
                                            throws FTLException

      Connect to an FTL server, and create a realm object.

      The FTL server defines information about endpoints, transports and formats, which lets applications communicate within a realm. The realm object is a local copy (within your program) of the subset of the realm information that pertains to your application.

      Note: It is good practice that each application process maintain only one connection to each relevant FTL server. Realm objects are thread-safe; you can safely use the same realm object in all the threads of an application program. Do not duplicate connections to the same realm server in several threads, which would duplicate the realm object.

      Parameters:
        `realmServerUrl` - The call contacts the FTL server at this URL.
        `appName` - The call sends this application name to the FTL server. The server responds with an application-specific subset of the realm information. To use the default application, supply `null`.
        `props` - Properties configure interaction with the FTL server. Required for connecting to a secure FTL server, for authentication, and for fault tolerance. Otherwise optional; to omit, supply `null`.
        - TLS Secure FTL Server Properties
          - `Realm.PROPERTY_STRING_TRUST_FILE`
          - `Realm.PROPERTY_STRING_TRUST_PEM_STRING`
          - `Realm.PROPERTY_BOOL_TRUST_EVERYONE`
          - `Realm#PROPERTY_STRING_LONG_SECURITY_LEVEL`
        - Authenication Properties
          - `Realm.PROPERTY_STRING_USERNAME`
          - `Realm.PROPERTY_STRING_USERPASSWORD`
          - `Realm.PROPERTY_STRING_CLIENT_CERT`
          - `Realm.PROPERTY_STRING_CLIENT_PRIVATE_KEY`
          - `Realm.PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD`
          Note: If USERPASSWORD is specified, but USERNAME is not, the call will fail.
        - Application Instance Property
          - `Realm.PROPERTY_STRING_APPINSTANCE_IDENTIFIER`
        - Connection Attempts Properties
          - `Realm.PROPERTY_LONG_CONNECT_RETRIES`
          - `Realm.PROPERTY_DOUBLE_CONNECT_INTERVAL`

        The values for properties can be overridden, with the overriding values passed to an application via:
        `java -Dproperty_name=property_value`
        For example: `java -Dcom.tibco.ftl.client.label=TEST -Dcom.tibco.ftl.client.connect_retries=5`

      Returns:
        On success, this method returns a realm object.

        On failure, this method returns `null`.

      Throws:
        `FTLException`

    - #### setLogLevel

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

      Set the global log trace level for low-level FTL internal calls.

      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`

    - #### setLogLevelForRealm

          public static void setLogLevelForRealm(long realm,
                                                 java.lang.String level)
                                          throws FTLException

      Throws:
        `FTLException`

    - #### setLogFiles

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

      Arrange rotating log files.

      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`

    - #### setLogFilesForRealm

          public static void setLogFilesForRealm(long realm,
                                                 java.lang.String filePrefix,
                                                 long maxFileSize,
                                                 int maxFiles,
                                                 TibProperties properties)
                                          throws FTLException

      Throws:
        `FTLException`

    - #### setLogHandler

          public static void setLogHandler(LogHandler handler,
                                           TibProperties properties)
                                    throws FTLException

      Register a global log handler.

      If you register a log handler (at most one), then FTL directs all log statements 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`

    - #### setLogHandlerForRealm

          public static void setLogHandlerForRealm(long realm,
                                                   LogHandler handler,
                                                   TibProperties properties)
                                            throws FTLException

      Throws:
        `FTLException`

    - #### getVersionInformation

          public static java.lang.String getVersionInformation()

      Version of the FTL Java client library (Java archive file).

      Programs can use this string to output the FTL version in a start banner or in debug output.

      Returns:
        Version string.