canReconnectSession

The canReconnectSession method is called when the session values for user preferences do not match the values stored in Preferences. This situation arises because MicroStrategy Web does not have access to the preferences actually set by users at the time when a session is created and, as a result, the application must intelligently guess the values that should be used.

The following user preferences need to be applied at the time a session is created:

• Result working set size  

• Logout settings, such as how to handle inbox messages when the session is closed 

• Locale ID, used for date and number formatting and for localization of error messages from Intelligence Server

If the values of the user preferences in the session are different from the actual values stored in Preferences, the canReconnectSession method can decide whether the application recreates a new session using the values stored in Preferences— automatically and transparently to the ESM.

Since user preferences are saved in the metadata, MicroStrategy Web or the ESM must make an intelligent guess as to what these values should be when the session is created. After the session has been created, the values provided by MicroStrategy Web or the ESM are compared with the actual user preference values. If the values do not match, the application checks to see if there is enough information in the session to be able to reconnect. It first checks the authentication mode. If the authentication mode does not require a user log-in or if the authentication mode does require a log-in and a user ID is available, MicroStrategy Web invokes the canReconnectSession method. Otherwise, this method is not invoked and the current session values for preferences are used.

Because this method gets invoked when handlesAuthenticationRequest returns either USE_MSTR_DEFAULT_LOGIN or COLLECT_SESSION_NOW, canReconnectSession takes care of applying user preferences for customizations in which a custom ESM creates a session. This method is also invoked when a user changes one of these preferences through the application, if the "Enable seamless login" setting is turned on.

If the method returns "false", the session is not reconnected and the user preferences supplied during session creation are used, even if they are different from the actual user preference values.

The following information is provided to help you use this method when you create a custom External Security Module.

• Method signature  

• Parameters  

• Return values  

• Pre-conditions  

• Post-operations

Method signature

public boolean canReconnectSession(ContainerServices cntSvcs, WebIServerSession currentSession, int reason)

Parameters

The following parameters are passed into the canReconnectSession method:  

• cntSvcs

  This parameter provides a way for the External Security Module to directly interact with the container to do such things as inspecting session variables and other data values not exposed through the RequestKeys object or accessing values such as headers that are not available through the RequestKeys instance.  

• currentSession

  This parameter provides the WebIServerSession that will be reconnected.  

• reason

  This parameter informs the External Security Module why the reconnect request is being made. It has the following value:

  • MISMATCHED_PREFERENCES

    This reason is passed in if the user preferences used to create the session do not match the actual values stored in Preferences.

Return Values

The canReconnectSession() method returns a boolean value indicating whether the session should be disconnected and reconnected, allowing actual user preferences to be applied automatically during session creation.

• true (default)

  The session will be reconnected and the actual user preferences saved in Preferences will be used to create a new session.  

• false

  The session will not be reconnected and the user preferences supplied during initial session creation (that is, intelligently guessed at by MicroStrategy Web or the ESM) will be used.

Pre-conditions

This call is not made with every request. It is called whenever both of the following are true: 

• A valid session has been created, but the values used to create the session do not match the values stored in Preferences. 

• The session includes the information necessary to reconnect— that is, it includes the server, project, port, user, and password (typically, the maximum session state).

Post-operations

The following operations take place after the method call has finished, based on the return value:

• If this method returns "false", the application does not reconnect the session. The session contains the original preferences that were used when the session was created, rather than the actual user preferences stored in Preferences. 

• If this method returns "true", the application closes the existing session and tries to reconnect the session using the actual user preferences stored in Preferences.

  • If this is successful, a new session is created with the actual user preferences. 

  • If this is not successful, the application throws an exception and uses out-of-the-box logic to handle the exception.