|Original Model||New Model|
|DbServer has one connection, initiated on startup.||DbServer has no connections. ConnectionManager has N connections, created on DbServer startup by ConnectionManager.start. N is determined by either environment variable SAM_DB_CONNECTIONS or by Defaults.py setting.|
|DbServer returns ServantFactory.||DbServer returns SessionFactory.|
|SessionFactory.createSession returns Session. This is a DbServer session; it will not have a database connection upon instantiation.|
|Session.createServant(in ServantType servantType)
ServantType is enum of allowable servants
|Client calls Session.start to start an active database connection for their session. Actually, this simply gets a database connection from the ConnectionManager's pool of available connections by calling ConnectionManager.open.|
|Client talks to Servant,
|Client talks to Servant,
Yes, these calls will be identical to the original method.
|Client may or may not have to commit, depending on whether or not the method is transactional or atomic. Also, the client may or may not be able to rollback any errors.
This is inconsistent and not documented well.
|Client has complete control of commit/rollback. There are no atomic methods. Session.commit and Session.rollback perform the requisite commit/rollback, and then give the database connection back to the ConnectionManager for others to reuse.|
|If commit/rollback issued, client must call Session.start again to obtain another database connection from ConnectionManager.|
|Client calls more servant methods.||Client calls more servant methods.|
|add||Add more connections to the pool. Currently called when trying to open a connection and all available are already in use.|
|substract||Give connections back if an abundant amount were grabbed and are no longer in use.|
|open||Secures a connection from the pool for a session, called by Session.start.|
|close||Gives back a session's connection, called by Session.commit/rollback.|
|start||Starts the initial connections, called when the DbServer is started.|
For IDL interface definitions, see the sam_db_server_idl in progress. These are not 100% accurate, as the Session was originally inherited from ServantFactory as a shortcut for putting the actual Servant creation into the Session. In the end, it is proposed to change this, just to make sure clients do not think they can create Servants using the old ServantFactory method.
For a sample client, see client-multi.py. This client uses multiple disjoint sessions in the same client, as a proof that it works, and also that the transactional commit/rollback statements are properly reflected in the separate transactions. It also restarts the sessions' database connections after commiting/rolling back.
This new design for sessions makes no provisions for atomic functions. All transactional control is in the hands of the client programmer. If atomic functions are desidered, it is recommended that an AtomicServantFactory be created which only serves up the interfaces that provide any atomic functions. These interfaces would be of the nature AtomicFile, AtomicProject, etc. They would include only the methods that allow for atomic transactions. This would simplify the implementation logic required for providing both atomic and transactional methods.
The Session.commit and Session.rollback operations release the database connection, giving it back to the ConnectionManager's pool. If this is a concern, methods such as commitKeep and rollbackKeep could be created to allow a session to keep its connection following a commit/rollback.