Class TdbSession

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void authenticate​(java.lang.String username, java.lang.String password)
      Authenticate with a grid.
      java.util.List<java.lang.String> dateforms()
      Retrieve the list of available date forms supported by the server
      void enableLogging​(boolean apilog, boolean xpilog)
      Enable or disable server-side API and/or XPI logging for the current sesssion.
      void enableNotification​(TdbNotificationType type, boolean enable)
      Enables or disables notifications.
      void enableNotification​(TdbNotificationType type, int notificationInterval)
      Enables search and sort comforter notifications with a specified preferred interval.
      java.util.List<java.lang.String> fieldTypes()
      Retrieve the list of available field types supported by the server
      TdbActivityLogger getActivityLog()
      Retrieve a reference to the activity logger currently in use
      TdbApiKeyMode getApiKeyMode()
      Returns the API key mode the server is configured to use.
      TdbBackgroundTaskSink getBackgroundTaskSink()
      Retrieve a reference to the background task completion event sink currently in use
      java.lang.String getBuildNumber()
      Retrieves the server's build version number string
      TdbCharacterSet getCharacterSet()
      Retrieves the TRIP character set in use on the server
      java.lang.String getCharacterSetName()
      Retrieves the name of the TRIP character set in use on the server
      TdbControlCacheManager getControlCache()
      Get the CONTROL object cache manager associated with this session.
      TdbDateform getCurrentDateform()
      Returns a TdbDateform instance for the current date format.
      java.lang.String getDateform​(int ix)
      Retrieves the dateform string for the dateform with the supplied type
      java.lang.String getDefaultQueueName()
      Retrieves the name of the default background task submission queue on the server
      java.util.Map<java.lang.String,​java.util.List<java.lang.String>> getDefinedViews()
      Retrieves a dictionary of the views defined in the current session.
      java.lang.String getFieldType​(int ft)
      Retrieves the name of the field type specified
      int getFieldType​(java.lang.String nm)
      Retrieves the ID of the named field type
      TdbNotificationSink getNotificationSink()
      Returns the current notification sink.
      java.lang.String getPid()
      Retrieves session pid on server
      java.lang.String getRevisionNumber()
      Retrieves the server's revision number string
      java.lang.String getServerApiLog​(boolean fromCheckpoint)
      Retieves the API log for the current session from the server.
      java.lang.String getServerName()
      The name of the TRIP server that the session is connected to.
      java.lang.String getServerXpiLog​(boolean fromCheckpoint)
      Retieves the XPI log for the current session from the server.
      java.lang.String getSessionId()
      Retrieve the established session ID -- this is obsolete as of TRIP6
      TdbInterfaceType getSessionType()
      Retrieves the connection type for this session
      int getSubsystemID​(java.lang.String nm)
      Retrieves the ID of the classification subsystem with the supplied name
      java.lang.String getSubsystemName​(int st)
      Retrieves the name of classification subsystem with the supplied ID
      java.lang.String getUsername()
      Retrieve the calling user's TRIP username
      java.lang.String getVersion()
      Retrieves the server's version string
      boolean hasLogCheckpoint()
      Returns true if the session-specific server-side logging has been checkpointed.
      boolean isApiLogEnabled()
      Check if server-side API logging is enabled for the current sesssion.
      boolean isConnected()
      Returns true if there is a physical or networked connection to the server.
      boolean isFileManager()
      Returns true if the calling user has file manager privilege
      boolean isLicensedFor​(TdbProduct prod)
      Check if the server to which this session is connected is licensed for the supplied product code
      boolean isLoggedIn()
      Returns true is session is connected and authenticated.
      boolean isSystemManager()
      Returns true if the calling user is the SYSTEM user
      boolean isTicketsEnabled()
      Returns true if login tickets are enabled on the server.
      boolean isTokensEnabled()
      Returns true if access tokens are enabled on the server.
      boolean isUserManager()
      Returns true if the calling user has user manager privilege
      boolean isWorking()
      Check if the session (in reality the underlying HIF) is busy
      boolean isXpiLogEnabled()
      Check if server-side XPI logging is enabled for the current sesssion.
      java.util.List<java.lang.String> licensedProducts()
      Retrieves a collection of named products for which the server is licensed
      void login​(java.lang.String username, java.lang.String password)
      Login to a TRIP server, using English CCL dialect, and disallowing restart.
      void login​(java.lang.String username, java.lang.String password, TdbLanguage language, boolean restart)
      Login to a TRIP server.
      void logout()
      Logout from the current session without saving state.
      void logout​(boolean save)
      Logout from a session created with login.
      TdbTokenPair refreshAccessToken​(java.lang.String apikey, java.lang.String refreshToken)
      Request a new access/refresh token pair.
      TdbTokenPair requestAccessToken​(java.lang.String apikey, java.lang.String tag)
      Request a new acceess/refresh token pair.
      java.lang.String requestLoginTicket()
      Request a new login ticket for the currently logged on user.
      void revokeLoginTicket​(java.lang.String ticket)
      Revoke the login ticket owned by the current user, or for the SYSTEM super user to revoke the ticket for another user.
      int revokeToken​(java.lang.String apikey, java.lang.String token)
      Revoke a specific token.
      int revokeTokens​(java.lang.String apikey, java.lang.String username, java.lang.String tag)
      Revoke tokens for the named or current user.
      void setActivityLog​(TdbActivityLogger logger)
      Set the activity logger reference for this session
      void setBackgroundTaskSink​(TdbBackgroundTaskSink sink)
      Establish the background task completion event sink to use
      void setLogCheckpoint()
      Set a checkpoint mark in the session-specific server-side logs from which log content can be retrieved.
      void setNotificationSink​(TdbNotificationSink sink)
      Assign a notification sink.
      java.util.List<java.lang.String> subsystemNames()
      Retrieve the list of available classification subsystems supported by the server
      boolean supportsFeature​(TdbTripFeature feature)
      Returns true if the version of TRIPsystem this session is connected to supports the specified feature.
      void validate​(TdbInterfaceType type)
      Validate that this session refers to a compatible connection type
      void writeActivityLog​(java.lang.String value)
      Write an arbitrary string to the activity log (if any) associated with this session
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • getActivityLog

        public TdbActivityLogger getActivityLog()
        Retrieve a reference to the activity logger currently in use
        Returns:
        The logger instance in use
      • setActivityLog

        public void setActivityLog​(TdbActivityLogger logger)
        Set the activity logger reference for this session
        Parameters:
        logger - The activity logger to use; set this to null to remove any pre-existing logger
      • getBackgroundTaskSink

        public TdbBackgroundTaskSink getBackgroundTaskSink()
        Retrieve a reference to the background task completion event sink currently in use
        Returns:
        Any event sink in use
      • setBackgroundTaskSink

        public void setBackgroundTaskSink​(TdbBackgroundTaskSink sink)
        Establish the background task completion event sink to use
        Parameters:
        sink - Background task event sink
      • getNotificationSink

        public TdbNotificationSink getNotificationSink()
        Returns the current notification sink.
        Returns:
        A TdbNotificationSink instance or null if no notification sink is defined
      • setNotificationSink

        public void setNotificationSink​(TdbNotificationSink sink)
                                 throws TdbException
        Assign a notification sink.

        This method does not cause the server to activate comforter notifications - they must still be explicitly enabled per type. The reason for this is to minimize unnecessary network communications. Only enable the notifications you actually are going to need.

        The detail level reported with of graph analysis notifications is set on the TdbGraph object being used.

        Parameters:
        sink - TdbNotificationSink object or null
        Throws:
        TdbException - Code TdbException.UNUSABLE_SESSION if the session is not of type TdbInterfaceType.NET
        See Also:
        enableNotification(TdbNotificationType,boolean), enableNotification(TdbNotificationType,int)
      • getSessionId

        public java.lang.String getSessionId()
        Retrieve the established session ID -- this is obsolete as of TRIP6
        Returns:
        Any available session ID token
      • getUsername

        public java.lang.String getUsername()
        Retrieve the calling user's TRIP username
        Returns:
        The user's TRIP username
      • dateforms

        public java.util.List<java.lang.String> dateforms()
        Retrieve the list of available date forms supported by the server
        Returns:
        The list of available date forms
      • getDateform

        public java.lang.String getDateform​(int ix)
        Retrieves the dateform string for the dateform with the supplied type
        Parameters:
        ix - The type of dateform string to retrieve
        Returns:
        The appropriate dateform string or null if ix is invalid
      • fieldTypes

        public java.util.List<java.lang.String> fieldTypes()
        Retrieve the list of available field types supported by the server
        Returns:
        The list of available field types
      • getFieldType

        public java.lang.String getFieldType​(int ft)
        Retrieves the name of the field type specified
        Parameters:
        ft - The field type for which to retrieve the name
        Returns:
        The field type name
      • getFieldType

        public int getFieldType​(java.lang.String nm)
        Retrieves the ID of the named field type
        Parameters:
        nm - The name of the field type for which the ID is to be retrieved
        Returns:
        The field type identifier
      • subsystemNames

        public java.util.List<java.lang.String> subsystemNames()
        Retrieve the list of available classification subsystems supported by the server
        Returns:
        The list of available subsystem names
      • getSubsystemName

        public java.lang.String getSubsystemName​(int st)
        Retrieves the name of classification subsystem with the supplied ID
        Parameters:
        st - The subsystem type ID
        Returns:
        The name of the subsystem
      • getSubsystemID

        public int getSubsystemID​(java.lang.String nm)
        Retrieves the ID of the classification subsystem with the supplied name
        Parameters:
        nm - The name of the subsystem
        Returns:
        The ID of the subsystem, or null if not found
      • getDefaultQueueName

        public java.lang.String getDefaultQueueName()
        Retrieves the name of the default background task submission queue on the server
        Returns:
        The name of the default queue
      • isSystemManager

        public boolean isSystemManager()
        Returns true if the calling user is the SYSTEM user
        Returns:
        true / false depending on the calling user's SM status
      • isTicketsEnabled

        public boolean isTicketsEnabled()
        Returns true if login tickets are enabled on the server.

        Consider using tokens instead of login tickets.

        Returns:
        true / false depending on if login tickets are enabled or not
        Since:
        8.0-4
        See Also:
        requestLoginTicket(), isTokensEnabled()
      • isFileManager

        public boolean isFileManager()
        Returns true if the calling user has file manager privilege
        Returns:
        true / false depending on the calling user's FM status
      • isUserManager

        public boolean isUserManager()
        Returns true if the calling user has user manager privilege
        Returns:
        true / false depending on the calling user's UM status
      • isConnected

        public boolean isConnected()
        Returns true if there is a physical or networked connection to the server. This property always holds the value 'true' if the session is web or local.
        Returns:
        True if connected
      • getVersion

        public java.lang.String getVersion()
        Retrieves the server's version string
        Returns:
        The server's version string
      • getRevisionNumber

        public java.lang.String getRevisionNumber()
        Retrieves the server's revision number string
        Returns:
        The server's revision number string
      • getBuildNumber

        public java.lang.String getBuildNumber()
        Retrieves the server's build version number string
        Returns:
        The server's build version number string
      • getPid

        public java.lang.String getPid()
        Retrieves session pid on server
        Returns:
        Session pid on server
      • getCharacterSetName

        public java.lang.String getCharacterSetName()
        Retrieves the name of the TRIP character set in use on the server
        Returns:
        The name of the active character set
      • getCharacterSet

        public TdbCharacterSet getCharacterSet()
        Retrieves the TRIP character set in use on the server
        Returns:
        The ID of the active character set
      • licensedProducts

        public java.util.List<java.lang.String> licensedProducts()
        Retrieves a collection of named products for which the server is licensed
        Returns:
        The collection of currently licensed product names
      • revokeLoginTicket

        public void revokeLoginTicket​(java.lang.String ticket)
                               throws TdbException
        Revoke the login ticket owned by the current user, or for the SYSTEM super user to revoke the ticket for another user.

        To revoke the login ticket for the current user, the ticket parameter can be null or an empty string. Specifying the login ticket explicitly is only required if the current user is SYSTEM and the goal is to revoke the ticket for another user.

        Parameters:
        ticket - Empty string or login ticket to revoke
        Throws:
        TdbException
        Since:
        8.0-4
      • refreshAccessToken

        public TdbTokenPair refreshAccessToken​(java.lang.String apikey,
                                               java.lang.String refreshToken)
                                        throws TdbException
        Request a new access/refresh token pair.

        This method does not require the session to be logged in. The TdbSession instance must exist and be connected to a TRIPsystem server, but the logout method must not have been called.

        Parameters:
        apikey - A valid API key if required by the connected TRIPsystem server, else null.
        refreshToken - A valid single-use refresh token
        Returns:
        A TdbTokenPair instance describing the new token pair
        Throws:
        TdbException
        TdbException - If the token refresh request failed
        See Also:
        requestAccessToken(java.lang.String,java.lang.String), isTokensEnabled(), getApiKeyMode()
      • revokeToken

        public int revokeToken​(java.lang.String apikey,
                               java.lang.String token)
                        throws TdbException
        Revoke a specific token.

        This method does not require the session to be logged in if a valid API key is given. In this case, the TdbSession instance must be connected to a TRIPsystem server, but the logout method must not have been called.

        If no API key is given and none is required by the connected TRIPsystem server, the session must be logged in. The token must in this case either be owned by the currently logged in user, or the currently logged in user must either be SYSTEM or the user manager (UM) of the user owning the token.

        Parameters:
        apikey - A valid API key if required by the connected TRIPsystem server, else null or an empty string.
        token - The access or refresh token for the token pair to revoke
        Returns:
        The number of tokens revoked
        Throws:
        TdbException - If the revoke request failed
      • revokeTokens

        public int revokeTokens​(java.lang.String apikey,
                                java.lang.String username,
                                java.lang.String tag)
                         throws TdbException
        Revoke tokens for the named or current user.

        If the username parameter is not specified (i.e. is null or an empty string), the operation will revoke tokens for the currently logged on user. If the username parameter is specified, it must either be the name of the currently logged on user, or the currently logged on user must be its user manager (UM) or SYSTEM.

        Parameters:
        apikey - A valid API key if required by the connected TRIPsystem server, else null or an empty string.
        username - The name of the user for whom to revoke tokens, or null or an empty string for the current user
        tag - The tag for the token(s) to remove, or null or an empty string to remove all tokens for the user
        Returns:
        The number of tokens revoked
        Throws:
        TdbException - If the revoke request failed
      • isLicensedFor

        public boolean isLicensedFor​(TdbProduct prod)
        Check if the server to which this session is connected is licensed for the supplied product code
        Parameters:
        prod - The product code to check
        Returns:
        true if the server is licensed for the product, false otherwise
      • getSessionType

        public TdbInterfaceType getSessionType()
        Retrieves the connection type for this session
        Returns:
        The connection type
      • isWorking

        public boolean isWorking()
        Check if the session (in reality the underlying HIF) is busy
        Returns:
        true if the server is currently doing something for us, otherwise false
      • getServerName

        public java.lang.String getServerName()
        The name of the TRIP server that the session is connected to. This property returns the name or IP address of the TRIP server host that the session is connected to. For session types such as the TdbGridSession that do not connect to a single host known and specified by the JXP application, this method will return an empty string.
      • enableNotification

        public void enableNotification​(TdbNotificationType type,
                                       boolean enable)
                                throws TdbException
        Enables or disables notifications.

        When using this method to enable a notification type, a default interval will be used. This is 5 seconds for comforters. To enable a notification type with custom interval, use "EnableNotification(TdbNotificationType,int) instead.

        For your application to be able to react on notifications, you must also register a notification sink.

        Parameters:
        type - Notification type to enable or disable
        enable - True to enable and false to disable
        Throws:
        TdbException
        See Also:
        setNotificationSink(TdbNotificationSink), getNotificationSink()
      • enableNotification

        public void enableNotification​(TdbNotificationType type,
                                       int notificationInterval)
                                throws TdbException
        Enables search and sort comforter notifications with a specified preferred interval. For your application to be able to react on notifications, you must also register a notification sink.
        Parameters:
        type - Notification type to enable
        notificationInterval - Preferred interval in seconds between notifications (pass 0 for a server-chosen default)
        Throws:
        TdbException
      • writeActivityLog

        public void writeActivityLog​(java.lang.String value)
                              throws TdbException
        Write an arbitrary string to the activity log (if any) associated with this session
        Parameters:
        value - The string to write to the log
        Throws:
        TdbException
      • supportsFeature

        public boolean supportsFeature​(TdbTripFeature feature)
        Returns true if the version of TRIPsystem this session is connected to supports the specified feature.
        See Also:
        TdbTripFeature
      • validate

        public void validate​(TdbInterfaceType type)
                      throws TdbException
        Validate that this session refers to a compatible connection type
        Parameters:
        type - The type of connection to validate
        Throws:
        TdbException
      • authenticate

        public void authenticate​(java.lang.String username,
                                 java.lang.String password)
                          throws TdbException
        Authenticate with a grid.

        This method causes network I/O.

        Parameters:
        username - The TRIP username
        password - The TRIP password -- this gets encrypted for transmission
        Throws:
        TdbException
      • logout

        public void logout()
                    throws TdbException
        Logout from the current session without saving state.

        This method causes network I/O.

        Throws:
        TdbException
      • logout

        public void logout​(boolean save)
                    throws TdbException
        Logout from a session created with login. This method must only be called from physical connections, and cannot be used with grid connections.

        This method causes network I/O.

        Parameters:
        save - Set true to signal the server to save the session file (*.SIF)
        Throws:
        TdbException
      • getControlCache

        public TdbControlCacheManager getControlCache()
        Get the CONTROL object cache manager associated with this session.

        Applicatons will normally request database design information with a high frequency, either explicitly or implicitly. The cache manager keeps such information locally when possible in order to keep network I/O to a minimum, resulting in a moderate performance boost.

      • isLoggedIn

        public boolean isLoggedIn()
        Returns true is session is connected and authenticated.
        Returns:
        true if logged in.
      • enableLogging

        public void enableLogging​(boolean apilog,
                                  boolean xpilog)
                           throws TdbException
        Enable or disable server-side API and/or XPI logging for the current sesssion.

        Session-specific server-side logging requires TRIPsystem 8.3-0 or later.

        Parameters:
        apilog - True to enable API logging
        xpilog - True to enable XPI logging
        Throws:
        TdbException - If the feature is not supported or if logging could not be toggled.
      • isApiLogEnabled

        public boolean isApiLogEnabled()
        Check if server-side API logging is enabled for the current sesssion.

        This property only returns true if API logging has been enabled via enableLogging method of the TdbSession class. Note that API logging globally enabled via the server-side tdbs.conf TRIPsystem configuration file is not reported here.

        Returns:
        True if session-specific server-side API logging is enabled for the current session.
        See Also:
        enableLogging(boolean,boolean)
      • isXpiLogEnabled

        public boolean isXpiLogEnabled()
        Check if server-side XPI logging is enabled for the current sesssion.

        This property only returns true if XPI logging has been enabled via enableLogging method of the TdbSession class. Note that API logging globally enabled via the server-side tdbs.conf TRIPsystem configuration file is not reported here.

        Returns:
        True if session-specific server-side XPI logging is enabled for the current session.
        See Also:
        enableLogging(boolean,boolean)
      • hasLogCheckpoint

        public boolean hasLogCheckpoint()
        Returns true if the session-specific server-side logging has been checkpointed.
        Returns:
        True if a log checkpoint has been set
        See Also:
        setLogCheckpoint()
      • setLogCheckpoint

        public void setLogCheckpoint()
                              throws TdbException
        Set a checkpoint mark in the session-specific server-side logs from which log content can be retrieved.

        Use checkpointing in order to retrieve the latest section of intrest from the session-specific server-side logs instead of the full session logs.

        Session-specific server-side logging requires TRIPsystem 8.3-0 or later.

        Throws:
        TdbException - If the feature is not supported or if logging could not be toggled.
        See Also:
        enableLogging(boolean,boolean), getServerApiLog(boolean), getServerXpiLog(boolean)
      • getServerApiLog

        public java.lang.String getServerApiLog​(boolean fromCheckpoint)
                                         throws TdbException
        Retieves the API log for the current session from the server.

        If no checkpoint has been set, the full API log for the session will be returned instead.

        Session-specific server-side logging requires TRIPsystem 8.3-0 or later.

        Parameters:
        fromCheckpoint - True to retrieve log contents from set checkpoint, and false to retrieve the entire log.
        Throws:
        TdbException - If the feature is not supported or if logging could not be toggled.
      • getServerXpiLog

        public java.lang.String getServerXpiLog​(boolean fromCheckpoint)
                                         throws TdbException
        Retieves the XPI log for the current session from the server.

        If no checkpoint has been set, the full XPI log for the session will be returned instead.

        Session-specific server-side logging requires TRIPsystem 8.3-0 or later.

        Parameters:
        fromCheckpoint - True to retrieve log contents from set checkpoint, and false to retrieve the entire log.
        Throws:
        TdbException - If the feature is not supported or if logging could not be toggled.
      • getDefinedViews

        public java.util.Map<java.lang.String,​java.util.List<java.lang.String>> getDefinedViews()
                                                                                               throws TdbException
        Retrieves a dictionary of the views defined in the current session.

        If the view is based on a field group declaration in the design of one of the databases currently open for search, each field name will be prefixed by the database name (e.g. CORR.SCOUNTRY).

        If the view was created by a "DEFINE VIEW" call, the field names will not have a database prefix.

        This method requires TRIPsystem 8.4-0 or later.

        Returns:
        An immutable Map of defined views, keyed on view name with the value being a list of the names of the fields in the view
        Throws:
        TdbException - If the feature is not supported or if the view definitions could not be retrieved