Typical scenario for PostreDebugSession

plugins/org.jkiss.dbeaver.ext.postgresql.debug.core/src/org/jkiss/dbeaver/ext/postgresql/debug/internal/impl/PostgreDebugSession.java

@@ -42,6 +42,21 @@ import org.jkiss.dbeaver.model.exec.DBCExecutionContext;
 import org.jkiss.dbeaver.model.impl.jdbc.JDBCExecutionContext;
 import org.jkiss.dbeaver.model.runtime.VoidProgressMonitor;
 
+/**
+ * Typical scenario for debug session <br/>
+ * <br/>
+ * 0. create session (now it can only attached to target Procedure)<br/><br/>
+ * 1. attach to target this method attaches to a debugging target and listening on the given port - 
+ *    waiting for run procedure in other session(s) debugger client should invoke this function after creation
+ *    also created implicit breakpoint for target procedure, after this call debug session in <b>WAITING</b> state - 
+ *    isDone returns false and is isWaiting returns true<br/><br/>
+ * 2. when target procedure will called debug session implicit breakpoint will be reached
+ *    and session goes in state <b>READY</b> (isDone - true, isWaiting - true) in this state possible to call
+ *    getStack, getVariables, setVariables, setBreakpoint or execStepXXX\continue<br/><br/>
+ * 3. when execStepXXX or continue will called session goes in <b>WAITING</b> state until next breakpoint or end of 
+ *    procedure will be reached     <br/>
+ *
+ */
 @SuppressWarnings("nls")
 public class PostgreDebugSession implements DBGSession {
 
@@ -81,12 +96,21 @@ public class PostgreDebugSession implements DBGSession {
 
     private List<PostgreDebugBreakpoint> breakpoints = new ArrayList<PostgreDebugBreakpoint>(1);
     
-    private PostgreDebugBreakpoint entry;
+    private PostgreDebugBreakpoint entry = null;
 
     private FutureTask<Void> task;
 
     private Thread workerThread = null;
 
+    /**
+     * This method attach debug session to debug object (procedure) 
+     * and wait forever while target or any (depend on targetPID) session will run target procedure  
+     * 
+     * @param connection - connection for debug session after attach this connection will forever belong to debug
+     * @param OID - OID for target procedure
+     * @param targetPID - target session PID (-1 for any target)
+     * @throws DBGException
+     */
     public void attach(JDBCExecutionContext connection,int OID,int targetPID) throws DBGException {
 
         lock.writeLock().lock();
@@ -112,7 +136,7 @@ public class PostgreDebugSession implements DBGSession {
             PostgreDebugBreakpointProperties properties = new PostgreDebugBreakpointProperties(true);
             PostgreDebugObject obj = new PostgreDebugObject(OID,"ENTRY","SESSION","THIS","PG"); 
             
-            entry = new PostgreDebugBreakpoint(this,obj,properties);
+            this.entry = new PostgreDebugBreakpoint(this,obj,properties);
             
             runAsync(SQL_ATTACH.replaceAll("\\?sessionid", String.valueOf(sessionId)),
                     String.valueOf(sessionId) + " global attached to " + String.valueOf(sessionManagerInfo.pid));
@@ -133,6 +157,14 @@ public class PostgreDebugSession implements DBGSession {
 
     }
 
+    /**
+     * Create session with two description 
+     * after creation session need to be attached to postgres procedure by attach method
+     * 
+     * @param sessionManagerInfo - manager (caller connection) description
+     * @param sessionDebugInfo - session (debugger client connection) description
+     * @throws DBGException
+     */
     public PostgreDebugSession(PostgreDebugSessionInfo sessionManagerInfo, PostgreDebugSessionInfo sessionDebugInfo) throws DBGException {
         this.sessionManagerInfo = sessionManagerInfo;
         this.sessionDebugInfo = sessionDebugInfo;
@@ -140,10 +172,16 @@ public class PostgreDebugSession implements DBGSession {
 
     }
 
+    /**
+     * @param connectionTarget - DBCExecutionContext of debug client (will be used in debug process)
+     * @return Connection - java.sql.Connection
+     * @throws SQLException
+     */
     private static Connection getConnection(DBCExecutionContext connectionTarget) throws SQLException {
         return ((JDBCExecutionContext) connectionTarget).getConnection(new VoidProgressMonitor());
     }
 
+
     @Override
     public DBGSessionInfo getSessionInfo() {
         return sessionDebugInfo;
@@ -212,6 +250,14 @@ public class PostgreDebugSession implements DBGSession {
 
     }
 
+    /**
+     * Execute step SQL command  asynchronously, set debug session name to 
+     * [sessionID] name [managerPID] 
+     * 
+     * @param commandSQL - SQL command for execute step
+     * @param name - session 'name' part
+     * @throws DBGException
+     */
     public void execStep(String commandSQL, String name) throws DBGException {
 
         acquireWriteLock();
@@ -363,6 +409,12 @@ public class PostgreDebugSession implements DBGSession {
         return stack;
     }
 
+    /**
+     * Return connection used in debug session 
+     * 
+     * @return java.sql.Connection
+     * @throws DBGException
+     */
     public Connection getConnection() throws DBGException {
         try {
             return getConnection(connection);
@@ -382,11 +434,21 @@ public class PostgreDebugSession implements DBGSession {
     public Integer getSessionId() {
         return sessionId;
     }
-
+    
+    /**
+     * Return true if session up and running debug thread
+     * 
+     * @return boolean
+     */
     public boolean isWaiting() {
         return (task == null ? false : !task.isDone()) && (workerThread == null ? false : workerThread.isAlive());
     }
 
+    /**
+     * Return true if session waiting target connection (on breakpoint, after step or continue) in debug thread
+     * 
+     * @return boolean
+     */
     public boolean isDone(){
 
         if (task == null)
@@ -410,10 +472,22 @@ public class PostgreDebugSession implements DBGSession {
 
     }
     
+    /**
+     * Return true if debug session up and running on server 
+     * 
+     * @return boolean
+     */
     public boolean isAttached() {
         return (connection != null && sessionId > 0);
     }
 
+    /**
+     *  Start thread for SQL command
+     * 
+     * @param commandSQL
+     * @param name
+     * @throws DBGException
+     */
     private void runAsync(String commandSQL, String name) throws DBGException {
 
         Connection connection = getConnection();
@@ -437,6 +511,11 @@ public class PostgreDebugSession implements DBGSession {
         }
     }
 
+    /**
+     * Try to acquire shared lock 
+     * 
+     * @throws DBGException
+     */
     private void acquireReadLock() throws DBGException {
 
         try {
@@ -466,6 +545,11 @@ public class PostgreDebugSession implements DBGSession {
 
     }
 
+    /**
+     *  Try to acquire exclusive lock 
+     * 
+     * @throws DBGException
+     */
     private void acquireWriteLock() throws DBGException {
 
         try {

plugins/org.jkiss.dbeaver.ext.postgresql.debug.core/src/org/jkiss/dbeaver/ext/postgresql/debug/internal/impl/PostgreDebugSessionInfo.java

@@ -26,6 +26,16 @@ import org.jkiss.dbeaver.debug.DBGSessionInfo;
 @SuppressWarnings("nls")
 public class PostgreDebugSessionInfo implements DBGSessionInfo {
 
+    public static final String QUERY_PROP = "query";
+
+    public static final String STATE_PROP = "state";
+
+    public static final String APP_PROP = "application";
+
+    public static final String USER_PROP = "user";
+
+    public static final String PID = "pid";
+
     public static final String CREATE_LISTEN = "CREATE LISTEN";
 
     final int pid;
@@ -69,13 +79,12 @@ public class PostgreDebugSessionInfo implements DBGSessionInfo {
     }
 
     public Map<String, Object> toMap() {
-        //FIXME: declare constants elsewhere, it is the part of metadata
         Map<String, Object> map = new HashMap<String, Object>();
-        map.put("pid", pid);
-        map.put("user", user);
-        map.put("application", application);
-        map.put("state", state);
-        map.put("query", query);
+        map.put(PID, pid);
+        map.put(USER_PROP, user);
+        map.put(APP_PROP, application);
+        map.put(STATE_PROP, state);
+        map.put(QUERY_PROP, query);
         return map;
     }