<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="JCR.SessionLeakDetected">
  <title>Session Leak Detector</title>

    <section id="JCR.SessionLeakDetected.Introduction">
      <title>Introduction</title>

      <para>The session leak detector is able to help you debug your application based on JCR when you suspect that you have a bug related to a wrong usage of JCR sessions. It works by creating a queue of weak references to JCR sessions and the queue is periodically cleaned. When a session reference is dequeued and is not cleared it is considered as a leaked session. Obviously what matters here is the time by which a session is stale known as max age. If the max age is too short period it will suspect that many sessions are leaked although they are not. The default max age value is configured at 2 minutes.</para>
                  
    </section>

    <section id="JCR.SessionLeakDetected.Activation">
      <title>Activation</title>

      <para>Setting the virtual machine system property <emphasis role="bold">exo.jcr.session.tracking.active</emphasis> to true activates the session detector with a default time period of 2 minutes.</para>

      <para>You can set the max age with the virtual machine system property <emphasis role="bold">exo.jcr.jcr.session.tracking.maxage</emphasis> in seconds. The default value, if you don't override it is 120 (2 minutes).</para>

      <para>Example :</para>

      <para>You can do this easily in eXo.sh. For example : On Linux/Macs :</para>

      <programlisting>
        JCR_SESSION_TRACK="-Dexo.jcr.session.tracking.active=true -Dexo.jcr.jcr.session.tracking.maxage=60"
        JAVA_OPTS="$JCR_SESSION_TRACK $JAVA_OPTS $LOG_OPTS $SECURITY_OPTS $EXO_OPTS $EXO_CONFIG_OPTS $REMOTE_DEBUG"
      </programlisting>

      <para>on Windows :</para>

      <programlisting>
        set JCR_SESSION_TRACK=-Dexo.jcr.session.tracking.active=true -Dexo.jcr.jcr.session.tracking.maxage=60
        set JAVA_OPTS="%JCR_SESSION_TRACK% %JAVA_OPTS% %LOG_OPTS% %SECURITY_OPTS% %EXO_OPTS% %EXO_CONFIG_OPTS% %REMOTE_DEBUG%"
      </programlisting>

      <para>We activate the session tracking and configure a maxage of 1 minute. Any JCR session older than 1 minute will cause an alert.</para>

    </section>

  <section id="JCR.SessionLeakDetected.Report">
    <title>Report</title>

    <para>Each detector execution starts with</para>

    <programlisting>
        Starting detector task
    </programlisting>

    <para>and ends with</para>

    <programlisting>
        Finished detector task
    </programlisting>

    <para>When a session is considered as leaked, debug information is printed on the console with a stack trace of the code that created the session in order to help you find out where the leaked session was created at runtime.</para>

    <para>Example :</para>

    <programlisting language="java">
        java.lang.Exception
          at org.exoplatform.services.jcr.impl.core.SessionReference.&lt;init&gt;(SessionReference.java:113)
          at org.exoplatform.services.jcr.impl.core.TrackedXASession.&lt;init&gt;(TrackedXASession.java:32)
          at org.exoplatform.services.jcr.impl.core.SessionFactory.createSession(SessionFactory.java:128)
          at org.exoplatform.services.jcr.impl.core.RepositoryImpl.getSystemSession(RepositoryImpl.java:314)
          at org.exoplatform.services.jcr.impl.core.RepositoryImpl.getSystemSession(RepositoryImpl.java:71)
          at org.exoplatform.services.jcr.ext.common.SessionProvider.getSession(SessionProvider.java:157)
          at org.exoplatform.faq.service.impl.JCRDataStorage.getFAQServiceHome(JCRDataStorage.java:323)
          ...
    </programlisting>
    
    <para>In this Stacktrace we learn that the method <emphasis role="bold">org.exoplatform.faq.service.impl.JCRDataStorage.getFAQServiceHome</emphasis> has opened a session that seems to be leaked. You need to verify in the code if Session.logout() is properly called in all cases (calling it in finally clause usually resolves the issue).</para>

  </section>
</section>
