ltpda-connection-manager: LTPDAConnectionManager.m comparison

comparison LTPDAConnectionManager.m @ 4:c706c10a76bd

Add help comments.

author	Daniele Nicolodi <daniele@science.unitn.it>
date	Mon, 24 May 2010 00:14:37 +0200
parents	d5fef23867bb
children	35f1cfcaa5a9

comparison

equal deleted inserted replaced

-:b4f2f4c10918
+:c706c10a76bd
 end % dependent properties
 methods(Static)
 function reset()
-setappdata(0, LTPDAConnectionManager.appdataKey, []);
+% RESET Resets the state of the connection manager.
-end
+%
+% This static method removes the LTPDAConnectionManager instance data from
+% the appdata storage. Causes the reset of the credentials cache and the
+% removal of all the connections from the connection pool.
+rmappdata(0, LTPDAConnectionManager.appdataKey);
+end
 function key = appdataKey()
-% defined as static method to be acessible by the reset static method
+% APPDATAKEY Returns the key used to store instance data in appdata.
+%
+% This is defined as static method, and not has an instance constant
+% property, to to be accessible by the reset static method.
 key = 'LTPDAConnectionManager';
 end
 end % static methods
 methods
-function cm = LTPDAConnectionManager(pl)
+function cm = LTPDAConnectionManager()
+% LTPDACONNECTIONMANAGER Manages credentials and database connections.
+%
+% This constructor returns an handler to a LTPDAConnectionManager class
+% instance. Database connections can be obtained trough the obtained
+% object with the connect() method.
+%
+% The purpose of this class it to keep track of open database connections
+% and to cache database credentials. It must be used in all LTPDA toolbox
+% functions that required to obtain database connections. Its behaviour can
+% be configured via LTPDA toolbox user preferences. The object status is
+% persisted trough the appdata matlab facility.
 % load state from appdata
 acm = getappdata(0, cm.appdataKey());
 if isempty(acm)
 val = p.cm.maxConnectionsNumber;
 end
 function n = count(cm)
+% COUNT Returns the number of open connections in the connections pool.
+%
+% This method has the side effect of removing all closed connections from
+% the connections pool, so that the underlying objects can be garbage
+% collected.
 import utils.const.*
 % find closed connections in the pool
 mask = false(numel(cm.connections), 1);
 for kk = 1:numel(cm.connections)
 if cm.connections{kk}.isClosed()
 utils.helper.msg(msg.PROC1, 'connection id=%d closed', kk);
 % count remainig ones
 n = numel(cm.connections);
 end
 function clear(cm)
-% remove all cached credentials
+% CLEAR Removes all cached credentials from the connection manager.
 cm.credentials = {};
 end
 function conn = connect(cm, varargin)
+% CONNECT Uses provided credential to establish a database connection.
+%
+% CONNECT(hostname, database, username, password) Returns an object
+% implementing the java.sql.Connection interface handing a connection to
+% the specified database. Any of the parameter is optional. The user will
+% be queried for the missing information.
+%
+% The returned connection are added to a connections pool. When the number
+% of connections in the pool exceeds a configurable maximum, no more
+% connection are instantiated. Closed connections are automatically
+% removed from the pool.
+%
+% CONNECT(pl) Works as the above but the parameters are obtained from the
+% plist object PL. If the 'connection' parameter in the plist contains an
+% object implementing the java.sql.Connection interface, this object is
+% returned instead that opening a new connection. In this case the
+% connection in not added to the connection pool.
 import utils.const.*
 % save current credentials cache
 cache = cm.credentials;
 end
 end
 function close(cm, ids)
+% CLOSE Forces connections to be closed.
+%
+% In the case bugs in other routines working with database connections
+% produce orphan connections, this method can be used to force the close
+% of those connections.
+%
+% CLOSE(ids) Closes the connections with the corresponding IDs in the
+% connections pool. If no ID is given all connections in the pool are
+% closed.
 if nargin < 2
 ids = 1:numel(cm.connections);
 end
 cellfun(@close, cm.connections(ids));
 end
 function add(cm, c)
+% ADD Adds credentials to the credentials cache.
+%
+% This method can be used to initialize or add to the cache, credentials
+% that will be used in subsequent connections attempts. This method accepts
+% only credentials in the form of utils.jmysql.credentials objects.
+% check input arguments
 if nargin < 2 || ~isa(c, 'credentials')
 error('### invalid call');
 end
+% add to the cache
 cm.cacheCredentials(c);
 end
 end % methods
 methods(Access=private)
 function conn = getConnection(cm, varargin)
+% GETCONNECTION Where the implementation of the connect method really is.
 import utils.const.*
+% handle variable number of arguments
 switch numel(varargin)
 case 0
 [hostname, database, username] = cm.selectDatabase();
 conn = cm.getConnection(hostname, database, username);
 end
 function ids = findCredentialsId(cm, varargin)
+% FINDCREDENTIALSID Find credentials in the cache and returns their IDs.
 import utils.const.*
 ids = [];
 for kk = 1:numel(cm.credentials)
 % invalidate expired passwords
 end
 end
 function cred = findCredentials(cm, varargin)
+% FINDCREDENTIALS Find credentials in the cache and returns them in a list.
 % default
 cred = [];
 % search
 ids = findCredentialsId(cm, varargin{:});
 end
 end
 function cacheCredentials(cm, c)
+% CACHECREDENTIALS Adds to or updates the credentials cache.
 import utils.const.*
 % find entry to update
 id = findCredentialsId(cm, c.hostname, c.database, c.username);
 end
 end
 function [username, password, cache] = inputCredentials(cm, cred)
-% this is a stubb
+% INPUTCREDENTIALS Queries the user for database username and password.
+% this is a stubb that must be replaced by a graphical interface
 % build a cell array of usernames and passwords
 users = { cred(:).username };
 passw = { cred(:).password };
 end
 end
 function [hostname, database, username] = selectDatabase(cm)
-% this is a stubb
+% SELECTDATABASE Makes the user choose to which database connect to.
+% this is a stubb that must be replaced by a graphical interface
 for kk = 1:numel(cm.credentials)
 fprintf('% 2d.  %s\n', char(cm.credentials{kk}));
 end
 fprintf('%d. NEW (default)\n', numel(cm.credentials)+1);
 end % private methods
 end % classdef
-% this should become utils.jmysql.connect
 function conn = connect(hostname, database, username, password)
+% CONNECT Opens a connection to the given database.
+%
+% This function returns a Java object implementing the java.sql.Connection
+% interface connected to the given database using the provided credentials.
+% If the connection fails because the given username and password pair is not
+% accepted by the server an utils:jmysql:connect:AccessDenied error is thrown.
+% this should become utils.jmysql.connect
 % informative message
 import utils.const.*
 utils.helper.msg(msg.PROC1, 'connection to mysql://%s/%s username=%s', hostname, database, username);

Mercurial > hg > ltpda-connection-manager

comparison LTPDAConnectionManager.m @ 4:c706c10a76bd