# HG changeset patch # User Daniele Nicolodi # Date 1274652877 -7200 # Node ID c706c10a76bdc6b913a284a52a7dc979ed5ba977 # Parent b4f2f4c10918a8a8a24189ff6c28b67cf1f5463e Add help comments. diff -r b4f2f4c10918 -r c706c10a76bd LTPDAConnectionManager.m --- a/LTPDAConnectionManager.m Sun May 23 22:12:05 2010 +0200 +++ b/LTPDAConnectionManager.m Mon May 24 00:14:37 2010 +0200 @@ -18,11 +18,22 @@ methods(Static) function reset() - setappdata(0, LTPDAConnectionManager.appdataKey, []); + % RESET Resets the state of the connection manager. + % + % 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 @@ -30,7 +41,18 @@ 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()); @@ -73,7 +95,14 @@ 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) @@ -90,14 +119,31 @@ 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 @@ -162,6 +208,16 @@ 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 @@ -170,9 +226,18 @@ 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 @@ -181,9 +246,11 @@ 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(); @@ -257,6 +324,8 @@ function ids = findCredentialsId(cm, varargin) + % FINDCREDENTIALSID Find credentials in the cache and returns their IDs. + import utils.const.* ids = []; @@ -277,6 +346,8 @@ function cred = findCredentials(cm, varargin) + % FINDCREDENTIALS Find credentials in the cache and returns them in a list. + % default cred = []; @@ -291,6 +362,8 @@ function cacheCredentials(cm, c) + % CACHECREDENTIALS Adds to or updates the credentials cache. + import utils.const.* % find entry to update @@ -324,7 +397,9 @@ 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 }; @@ -360,7 +435,9 @@ 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})); @@ -388,8 +465,15 @@ 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.*