public class TdbSession extends TdbMessageProvider implements com.tietoenator.trip.jxp.internal.utils.DOMSink
Modifier and Type | Method and 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
|
codeList, getLastCode, getLastMessage, hasMessages, messageList, resetMessages
cancel, getSession, isCancelable, setCancelable
public TdbActivityLogger getActivityLog()
public void setActivityLog(TdbActivityLogger logger)
logger
- The activity logger to use; set this to null to remove any
pre-existing loggerpublic TdbBackgroundTaskSink getBackgroundTaskSink()
public void setBackgroundTaskSink(TdbBackgroundTaskSink sink)
sink
- Background task event sinkpublic TdbNotificationSink getNotificationSink()
public void setNotificationSink(TdbNotificationSink sink) throws TdbException
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.
sink
- TdbNotificationSink object or nullTdbException
- Code TdbException.UNUSABLE_SESSION if the session is not of type TdbInterfaceType.NETTdbSession.enableNotification(TdbNotificationType,boolean)
,
TdbSession.enableNotification(TdbNotificationType,int)
public java.lang.String getSessionId()
public java.lang.String getUsername()
public java.util.List<java.lang.String> dateforms()
public java.lang.String getDateform(int ix)
ix
- The type of dateform string to retrievepublic TdbDateform getCurrentDateform() throws TdbException
TdbException
public java.util.List<java.lang.String> fieldTypes()
public java.lang.String getFieldType(int ft)
ft
- The field type for which to retrieve the namepublic int getFieldType(java.lang.String nm)
nm
- The name of the field type for which the ID is to be retrievedpublic java.util.List<java.lang.String> subsystemNames()
public java.lang.String getSubsystemName(int st)
st
- The subsystem type IDpublic int getSubsystemID(java.lang.String nm)
nm
- The name of the subsystempublic java.lang.String getDefaultQueueName()
public boolean isSystemManager()
public boolean isTicketsEnabled()
Consider using tokens instead of login tickets.
TdbSession.requestLoginTicket()
,
TdbSession.isTokensEnabled()
public boolean isTokensEnabled()
TdbSession.getApiKeyMode()
,
TdbSession.requestAccessToken(String,String)
,
refreshTokenPair(String,String)
public TdbApiKeyMode getApiKeyMode()
TdbSession.isTokensEnabled()
,
TdbSession.requestAccessToken(String,String)
,
refreshTokenPair(String,String)
public boolean isFileManager()
public boolean isUserManager()
public boolean isConnected()
public java.lang.String getVersion()
public java.lang.String getRevisionNumber()
public java.lang.String getBuildNumber()
public java.lang.String getPid()
public java.lang.String getCharacterSetName()
public TdbCharacterSet getCharacterSet()
public java.util.List<java.lang.String> licensedProducts()
public java.lang.String requestLoginTicket() throws TdbException
TdbException
TdbSession.isTicketsEnabled()
,
TdbSession.isTokensEnabled()
,
The returned value can be used instead of username and
password, enabling an SSO-like behavhior for applications,
in which the ticket would be stored as a cookie. To log in using
the ticket, pass it in the password parameter of the Login method
and set the username to an empty string.
Note that login tickets have been superseded by access
tokens.
When requesting a new login ticket, the new ticket will
replace any previous ticket assigned to the current user.
Subsequent ticket-based login for the user must use the new
ticket.
The login ticket feature requries TRIPsystem 8.0 or later
and must be explicitly enabled on the TRIP server in order to be
used as it is disabled by default.
Tickets time out after 30 days of inactivity by default.
This period can be configured. Refer to the TRIPsystem documentation
for more information.
public void revokeLoginTicket(java.lang.String ticket) throws TdbException
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.
ticket
- Empty string or login ticket to revokeTdbException
public TdbTokenPair requestAccessToken(java.lang.String apikey, java.lang.String tag) throws TdbException
apikey
- A valid API key if required by the connected TRIPsystem server, else null.tag
- A tag to assign the token for identificationTdbException
TdbException
- If the token request failedTdbSession.refreshAccessToken(String,String)
,
TdbSession.isTokensEnabled()
,
TdbSession.getApiKeyMode()
public TdbTokenPair refreshAccessToken(java.lang.String apikey, java.lang.String refreshToken) throws TdbException
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.
apikey
- A valid API key if required by the connected TRIPsystem server, else null.refreshToken
- A valid single-use refresh tokenTdbException
TdbException
- If the token refresh request failedTdbSession.requestAccessToken(String,String)
,
TdbSession.isTokensEnabled()
,
TdbSession.getApiKeyMode()
public int revokeToken(java.lang.String apikey, java.lang.String token) throws TdbException
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.
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 revokeTdbException
- If the revoke request failedpublic int revokeTokens(java.lang.String apikey, java.lang.String username, java.lang.String tag) throws TdbException
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.
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 usertag
- The tag for the token(s) to remove, or null or an empty string to remove all tokens for the userTdbException
- If the revoke request failedpublic boolean isLicensedFor(TdbProduct prod)
prod
- The product code to checkpublic TdbInterfaceType getSessionType()
public boolean isWorking()
public java.lang.String getServerName()
public void enableNotification(TdbNotificationType type, boolean enable) throws TdbException
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.
type
- Notification type to enable or disableenable
- True to enable and false to disableTdbException
TdbSession.setNotificationSink(TdbNotificationSink)
,
TdbSession.getNotificationSink()
public void enableNotification(TdbNotificationType type, int notificationInterval) throws TdbException
type
- Notification type to enablenotificationInterval
- Preferred interval in seconds between notifications (pass 0 for a server-chosen default)TdbException
public void writeActivityLog(java.lang.String value) throws TdbException
value
- The string to write to the logTdbException
public boolean supportsFeature(TdbTripFeature feature)
TdbTripFeature
public void validate(TdbInterfaceType type) throws TdbException
type
- The type of connection to validateTdbException
public void authenticate(java.lang.String username, java.lang.String password) throws TdbException
This method causes network I/O.
username
- The TRIP usernamepassword
- The TRIP password -- this gets encrypted for transmissionTdbException
public void login(java.lang.String username, java.lang.String password) throws TdbException
username
- The TRIP username to usepassword
- The TRIP password to useTdbException
To log in with an access token, pass the access token string as the
password. If token based login requires an API key, pass the API key
string as the username. Otherwise, pass an empty string as the username.
An API key is required if the getApiKeyMode() method returns
TdbApiKeyMode.Always.
To log in with a login ticket, pass an empty string as the username
and the ticket as the password. Note that login tickets have been superseded
by access token as per version 8.3-2 of TRIPjxp.
This method causes network I/O.
public void login(java.lang.String username, java.lang.String password, TdbLanguage language, boolean restart) throws TdbException
username
- The TRIP username to usepassword
- The TRIP password to use (this gets encrypted for transmission)language
- The CCL language dialect to userestart
- If set high, signal TRIP to attempt to restart from a previous sessionTdbException
To log in with an access token, pass the access token string as the
password. If token based login requires an API key, pass the API key
string as the username. Otherwise, pass an empty string as the username.
An API key is required if the getApiKeyMode() method returns
TdbApiKeyMode.Always.
To log in with a login ticket, pass an empty string as the username
and the ticket as the password. Note that login tickets have been superseded
by access tokens as per version 8.3-2 of TRIPjxp!
This method causes network I/O.
public void logout() throws TdbException
This method causes network I/O.
TdbException
public void logout(boolean save) throws TdbException
This method causes network I/O.
save
- Set true to signal the server to save the session file (*.SIF)TdbException
public TdbControlCacheManager getControlCache()
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.
public boolean isLoggedIn()
public void enableLogging(boolean apilog, boolean xpilog) throws TdbException
Session-specific server-side logging requires TRIPsystem 8.3-0 or later.
apilog
- True to enable API loggingxpilog
- True to enable XPI loggingTdbException
- If the feature is not supported or if logging could not be toggled.public boolean isApiLogEnabled()
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.
TdbSession.enableLogging(boolean,boolean)
public boolean isXpiLogEnabled()
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.
TdbSession.enableLogging(boolean,boolean)
public boolean hasLogCheckpoint()
TdbSession.setLogCheckpoint()
public void setLogCheckpoint() throws TdbException
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.
TdbException
- If the feature is not supported or if logging could not be toggled.TdbSession.enableLogging(boolean,boolean)
,
TdbSession.getServerApiLog(boolean)
,
TdbSession.getServerXpiLog(boolean)
public java.lang.String getServerApiLog(boolean fromCheckpoint) throws TdbException
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.
fromCheckpoint
- True to retrieve log contents from set checkpoint, and false to retrieve the entire log.TdbException
- If the feature is not supported or if logging could not be toggled.public java.lang.String getServerXpiLog(boolean fromCheckpoint) throws TdbException
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.
fromCheckpoint
- True to retrieve log contents from set checkpoint, and false to retrieve the entire log.TdbException
- If the feature is not supported or if logging could not be toggled.public java.util.Map<java.lang.String,java.util.List<java.lang.String>> getDefinedViews() throws TdbException
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.
TdbException
- If the feature is not supported or if the view definitions could not be retrieved