= !MapGuide RFC 66 - Prevent session timeout, and give better error messages =

This page contains an change request (RFC) for the !MapGuide Open Source project.
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status ==

||RFC Template Version||(1.0)||
||Submission Date||(June 16, 2009)||
||Last Modified||(Christine Bao Thu Jun 25 02:22:17 2009)||
||Author||Christine Bao||
||RFC Status||adopted||
||Implementation Status||completed||
||Proposed Milestone||2.2||
||Assigned PSC guide(s)||Tom Fukushima||
||'''Voting History'''||July 06, 2009||
||+1||Tom, Jason, Paul, Bruce, Kenneth||
||+0||||
||-0||||
||-1||||
||no vote||Haris, Bob, Andy ||

== Overview ==

This RFC adds features keep sessions alive while the browser is open; and to improve user feedback to monitor state between client and server tier, while detect and report cases of failure in both Ajax and Fusion web layout.

== Motivation ==

Customer reports that if leave the browser open for some while without any operation, the session will timeout and can’t get informed. If server is down the error message is not easy to read and user can’t figure out what happens.[[BR]]
The use cases would be:[[BR]]
1.	If the Http session is timeout, the user should be informed about the fact instead of getting some script errors or meaningless error messages.[[BR]]
2.	If the !MapGuide Server session is timeout, the user should be informed about the fact instead of getting some script errors or some meaningless error messages.[[BR]]
3.	If the connection to !MapGuide Server is broken, the user should be informed by a friendly message which helps the user know what's happening instead of getting a kind of "exception stack trace" message box.

== Proposed Solution ==

The possible solutions could be:[[BR]]
1.	To avoid timeout (either from browser to web tier, or from web tier to !MapGuide server), implement a script which pings the servers periodically to keep the both sessions alive. [[BR]]
2.	Refine the code handling the exceptions like "connection broken" to provide more friendly messages.

Detail implementation:


1.	Keep alive


   a.   Fusion already pings server periodically by calling "Common.php", so there is no plan to change Fusion's behavior.


   b.   Ajax viewer doesn’t ping server to keep-alive so far. If open an Ajax viewer and leave it open for a while more than the timeout interval, it can’t continue work. To keep Ajax viewer alive, the approach is:[[BR]]
     1).  Create a server API !GetSessionTimeout(), return the timeout setting from server side. [[BR]]
The API is in !MgSiteConnection class, declare as[[BR]]
{{{
class MG_MAPGUIDE_API !MgSiteConnection  : public MgGuardDisposable
{
    /////////////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Gets the session time out value.
    ///
    /// \remarks
    /// Resources placed into the session repository will exist until
    /// the session expires or the session is destroyed by using
    /// DestroySession. The session timeout value is the lifttime of session
    /// repository.
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// string GetSessionTimeout();
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// String GetSessionTimeout();
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// string GetSessionTimeout();
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \return
    /// The timeout value of session measured in second, for example
    /// "300".
    ///
    /// \exception [[To be documented]]
    ///
    /// \todo
    ///   [[What are the exceptions?]]
    ///
    INT32 GetSessionTimeout();
}
}}}
[[BR]]

     2).  Call !GetSessionTimeout() from mainframe.templ periodically.[[BR]]
!MapAgent.fcgi operation sample is:[[BR]]
{{{
[MapAgent URL]\MapAgent.fcgi?OPERATION=GETSESSIONTIMEOUT&VERSION=1.0.0&SESSION=[session Id]&LOCALE=[locale]&CLIENTAGENT=[client];    
}}}
[[BR]]

     3).  User doesn’t need to set the time interval of pinging. It’s read from server timeout setting and divided by 5. User can turn the ping on/off by setting <!EnablePingServer>=1/0 of basic web layout. [[BR]]

Web Layout schema should be updated from 1.0.0 to 1.1.0 for adding <!EnablePingServer> tag. [[BR]]
{{{
  <xs:complexType name="WebLayoutType">
    <xs:sequence>
      <xs:element name="Title" type="xs:string"/>
      <xs:element name="Map" type="MapType"/>
      <xs:element name="EnablePingServer" type="xs:boolean" />
      <xs:element name="ToolBar" type="ToolBarType"/>
      <xs:element name="InformationPane" type="InformationPaneType"/>
      <xs:element name="ContextMenu" type="ContextMenuType"/>
      <xs:element name="TaskPane" type="TaskPaneType"/>
      <xs:element name="StatusBar" type="StatusBarType"/>
      <xs:element name="ZoomControl" type="ZoomControlType"/>
      <xs:element name="CommandSet" type="CommandSetType"/>
    </xs:sequence>
  </xs:complexType>
}}}


2.	Refine exception handling such as “connection broken”[[BR]]
   a.   Fusion does not handle exception message well. It shows long unreadable message when exception happens. For example if connection broken the error message is "FATAL: xml2json: invalid XML document: !MgConnectionFailedException : !http://127.0.0.1/mapguide2010/mapagent/mapagent.fcgi?version=1.0.0&locale=en&clientagent=Fusion%20Viewer&operation=QUERYMAPFEATURES&session=40d3e074-3ee5-102c-8000-005056c00008_en_7F0000010AFC0AFB0AFA&mapname=Sheboygan4a3b609791c82&geometry=POLYGON((-87.730254250931%2043.73763292302%2C%20-87.730254250931%2043.737069942268%2C%20-87.729691270179%2043.737069942268%2C%20-87.729691270179%2043.73763292302%2C%20-87.730254250931%2043.73763292302))&maxFeatures=1&persist=0&selectionVariant=INTERSECTS&layerNames=&layerAttributeFilter=5 type=0". This is no user-friendly. The error message should show exception message such as "Fussion error: Cannot establish connection".[[BR]]
   b.   Ajax viewer shows exception messages and they are user-friendly. No improvements needed for Ajax viewer.


== Implications ==


== Test Plan ==

Test both Ajax viewer and Fusion viewer.

== Funding/Resources ==

Supplied by Autodesk.