Package com.progress.open4gl.dynamicapi

Class Session

java.lang.Object
com.progress.open4gl.dynamicapi.Session
public class Session extends Object
The Session class implements a (Dynamic API) proxy for a 4GL server connection.

The most important part of the Session object context is the Broker reference. The Broker is the client side object that represets the broker system. The Broker object is the Session's connections to the outside world, it allow the Session object to send and receive data from the 4GL server. A 4GL procedure is executed in (at most) five stages - two for sending input data and three to receive output data. A Send/Recive cycle is called A conversation: 1) Put the scalar input values onto the stream. 2) Put the input result sets onto the stream. 3) Receive the schema of the output temp-tables (or an Error stream). 4) Receive the scalar output values. (or an Error stream). 5) Prepare handles to the output result sets. If there is no relational (Temp-Table) data to be sent or received then an execution of a 4GL procedure would go thru the (1) and (4) steps only - that is the minimum. The session object can be CONNECTED or DISCONNECTED. A CONNECTED object Can be: IDLE or RUNNING or STREAMING. RUNNING: We are inside the PersistentProc() method. STREAMING: There is (are) an open output result set(s). The Seesion "knows" that it is STREAMING when by having outputSetsChain variable referencing the chain of output result sets. IDLE: It's not RUNNING or STREAMING. The Open4GLException exception is the ONLY way the Session object communicates errors the caller (the user of the Dynamic API). The Open4GLException class is further extended to describe different 4GL errors and conditions: STOP, ERROR and QUIT. But for a programmer that Does not want to get familiar with 4GL details it is generaly enough to handle Open4GLException exceptions ( sine StopException, for example, IS A, object oriented wise, Open4GLException. Normal (user) errors are not handled by a special Session state: Error data is handled like any other output data. When a FGLErrorException exception is caught, the Session object calls an ErrorMessageReader object to decode the error information. At any point where the Session object is willing to get interrupted, it sets the interrupt varable with an Interruptable object. For example, when the input result sets are being marshaled onto the stream, the interrupt variable is set to the InputTableStreamerNoSchema streamer object, so when Session.setStop() is called, setStop() calls interrupt.stop() and that triggers InputTableStreamerNoSchema.stop() that caueses the streaming process to stop. The Session object is referenced by the the output ResultSet objects. That is important because the user of the Dynamic API (which is, indirectly, the application), pulls data from the server after the Session.runProcedure() method already returned. So if there is an error in the process of streaming the output data, the ResultSet object can notify the Session by calling the non private version of Session.handleOutputErrors().