+
−classdef LTPDADatabaseConnectionManager < handle
+
−
+
−  properties(SetAccess=private)
+
−
+
−    connections = {};
+
−    credentials = {};
+
−
+
−  end % private properties
+
−
+
−  properties(Dependent=true)
+
−
+
−    credentialsExpiry; % seconds
+
−    cachePassword; % 0=no 1=yes 2=ask
+
−    maxConnectionsNumber;
+
−
+
−  end % dependent properties
+
−
+
−  methods(Static)
+
−
+
−    function reset()
+
−    % RESET Resets the state of the connection manager.
+
−    %
+
−    % This static method removes the LTPDADatabaseConnectionManager
+
−    % 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, LTPDADatabaseConnectionManager.appdataKey);
+
−    end
+
−
+
−
+
−    function key = appdataKey()
+
−    % 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 = 'LTPDADatabaseConnectionManager';
+
−    end
+
−
+
−  end % static methods
+
−
+
−  methods
+
−
+
−    function cm = LTPDADatabaseConnectionManager()
+
−    % LTPDACONNECTIONMANAGER Manages credentials and database connections.
+
−    %
+
−    % This constructor returns an handler to a LTPDADatabaseConnectionManager
+
−    % 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.
+
−
+
−      % import credentials class
+
−      import utils.credentials
+
−
+
−      % load state from appdata
+
−      acm = getappdata(0, cm.appdataKey());
+
−
+
−      if isempty(acm)
+
−        % store state in appdata
+
−        setappdata(0, cm.appdataKey(), cm);
+
−
+
−        import utils.const.*
+
−        utils.helper.msg(msg.PROC1, 'new connection manager');
+
−      else
+
−        cm = acm;
+
−      end
+
−    end
+
−
+
−    function str = disp(cm)
+
−      disp(sprintf('%s()\n', class(cm)));
+
−    end
+
−
+
−
+
−    function val = get.credentialsExpiry(cm)
+
−      % obtain from user preferences
+
−      p = getappdata(0, 'LTPDApreferences');
+
−      val = double(p.getRepoPrefs().getExpiry());
+
−    end
+
−
+
−
+
−    function val = get.cachePassword(cm)
+
−      % obtain from user preferences
+
−      p = getappdata(0, 'LTPDApreferences');
+
−      val = double(p.getRepoPrefs().getCachePassword());
+
−    end
+
−
+
−
+
−    function val = get.maxConnectionsNumber(cm)
+
−      % obtain from user preferences
+
−      p = getappdata(0, 'LTPDApreferences');
+
−      val = double(p.getRepoPrefs().getMaxConnectionsNumber());
+
−    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);
+
−          mask(kk) = true;
+
−        end
+
−      end
+
−
+
−      % remove them
+
−      cm.connections(mask) = [];
+
−
+
−      % count remainig ones
+
−      n = numel(cm.connections);
+
−    end
+
−
+
−    function clear(cm)
+
−    % 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;
+
−
+
−      % count open connections in the pool
+
−      count = cm.count();
+
−
+
−      % check parameters
+
−      if numel(varargin) == 1 && isa(varargin{1}, 'plist')
+
−
+
−        % extract parameters from plist
+
−        pl = varargin{1};
+
−
+
−        % check if we have a connection parameter
+
−        conn = find(pl, 'conn');
+
−        if ~isempty(conn)
+
−          % check that it implements java.sql.Connection interface
+
−          if ~isa(conn, 'java.sql.Connection')
+
−            error('### connection is not valid database connection');
+
−          end
+
−          % return this connection
+
−          return;
+
−        end
+
−
+
−        % otherwise
+
−        hostname = find(pl, 'hostname');
+
−        database = find(pl, 'database');
+
−        username = find(pl, 'username');
+
−        password = find(pl, 'password');
+
−
+
−        % if there is no hostname ignore other parameters
+
−        if ~ischar(hostname) || isempty(hostname)
+
−          varargin = {};
+
−        % if there is no database ignore other parameters
+
−        elseif ~ischar(database) || isempty(database)
+
−          varargin = {hostname};
+
−        % if there is no username ignore other parameters
+
−        elseif ~ischar(username) || isempty(username)
+
−          varargin = {hostname, database};
+
−        % password can not be null but can be an empty string
+
−        elseif ~ischar(password)
+
−          varargin = {hostname, database, username};
+
−        else
+
−          varargin = {hostname, database, username, password};
+
−        end
+
−      end
+
−
+
−      % check number of connections
+
−      if count > cm.maxConnectionsNumber
+
−        error('### too many open connections');
+
−      end
+
−
+
−      % connect
+
−      try
+
−        conn = cm.getConnection(varargin{:});
+
−
+
−        % add connection to pool
+
−        utils.helper.msg(msg.PROC1, 'add connection to pool');
+
−        cm.connections{end+1} = conn;
+
−
+
−      catch ex
+
−        % restore our copy of the credentials cache
+
−        utils.helper.msg(msg.PROC1, 'undo cache changes');
+
−        cm.credentials = cache;
+
−
+
−        % hide implementation details
+
−        ex.throw();
+
−      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));
+
−
+
−      % remove closed connections from pool
+
−      cm.count();
+
−    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.credentials objects.
+
−
+
−      % check input arguments
+
−      if nargin < 2 || ~isa(c, 'utils.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
+
−          % find credentials
+
−          [hostname, database, username] = cm.selectDatabase([cm.credentials{:}]);
+
−          conn = cm.getConnection(hostname, database, username);
+
−
+
−        case 1
+
−          % find credentials
+
−          cred = cm.findCredentials(varargin{:});
+
−          if numel(cred) == 0
+
−            cred = utils.credentials(varargin{:});
+
−          end
+
−          [hostname, database, username] = cm.selectDatabase(cred);
+
−          conn = cm.getConnection(hostname, database, username);
+
−
+
−        case 2
+
−          % find credentials
+
−          cred = cm.findCredentials(varargin{:});
+
−          switch numel(cred)
+
−            case 0
+
−              conn = cm.getConnection(varargin{1}, varargin{2}, []);
+
−            case 1
+
−              conn = cm.getConnection(cred.hostname, cred.database, cred.username);
+
−            otherwise
+
−              [hostname, database, username] = cm.selectDatabase(cred);
+
−              conn = cm.getConnection(hostname, database, username);
+
−          end
+
−
+
−        case 3
+
−          % find credentials
+
−          cred = cm.findCredentials(varargin{1}, varargin{2}, varargin{3});
+
−          switch numel(cred)
+
−            case 0
+
−              % no credentials found
+
−              usernames = { varargin{3} };
+
−              if isempty(varargin{3})
+
−                % use usernames for same hostname
+
−                tmp = cm.findCredentials(varargin{1});
+
−                if ~isempty(tmp)
+
−                  usernames = { tmp(:).username };
+
−                end
+
−              end
+
−              % build credentials objects
+
−              tmp = {};
+
−              for kk = 1:numel(usernames)
+
−                tmp{kk} = utils.credentials(varargin{1}, varargin{2}, usernames{kk});
+
−              end
+
−              % convert from cell array to array
+
−              cred = [tmp{:}];
+
−            case 1
+
−              % credentials in cache
+
−              utils.helper.msg(msg.PROC1, 'use cached credentials');
+
−            otherwise
+
−              % we should not have more than one credentials set
+
−              error('### more than one credentials set matching');
+
−          end
+
−
+
−          cache = false;
+
−          if (numel(cred) > 1) || ~cred.complete
+
−            % ask for password
+
−            [username, password, cache] = cm.inputCredentials(cred);
+
−
+
−            % cache credentials
+
−            cred = utils.credentials(varargin{1}, varargin{2}, username);
+
−            cm.cacheCredentials(cred);
+
−
+
−            % add password to credentials
+
−            cred.password = password;
+
−          end
+
−
+
−          % try to connect
+
−          try
+
−            conn = utils.mysql.connect(cred.hostname, cred.database, cred.username, cred.password);
+
−          catch ex
+
−            % look for access denied errors
+
−            if strcmp(ex.identifier, 'utils:mysql:connect:AccessDenied')
+
−              % ask for new new credentials
+
−              utils.helper.msg(msg.IMPORTANT, ex.message);
+
−              conn = cm.getConnection(varargin{1}, varargin{2}, varargin{3});
+
−            else
+
−              % error out
+
−              throw(ex);
+
−            end
+
−          end
+
−
+
−          % cache password
+
−          if cache
+
−            utils.helper.msg(msg.PROC1, 'cache password');
+
−            cm.cacheCredentials(cred);
+
−          end
+
−
+
−        case 4
+
−          % connect
+
−          conn = utils.mysql.connect(varargin{1}, varargin{2}, varargin{3}, varargin{4});
+
−
+
−          if cm.cachePassword == 1
+
−            % cache credentials with password
+
−            cred = utils.credentials(varargin{1}, varargin{2}, varargin{3}, varargin{4});
+
−          else
+
−            % cache credentials without password
+
−            cred = utils.credentials(varargin{1}, varargin{2}, varargin{3});
+
−          end
+
−          cm.cacheCredentials(cred);
+
−
+
−        otherwise
+
−          error('### invalid call')
+
−      end
+
−
+
−    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
+
−        if expired(cm.credentials{kk})
+
−          utils.helper.msg(msg.PROC1, 'cache entry id=%d expired', kk);
+
−          cm.credentials{kk}.password = [];
+
−          cm.credentials{kk}.expiry = 0;
+
−        end
+
−
+
−        % match input with cache
+
−        if match(cm.credentials{kk}, varargin{:})
+
−          ids = [ ids kk ];
+
−        end
+
−      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{:});
+
−
+
−      % return a credentials objects array
+
−      if ~isempty(ids)
+
−        cred = [cm.credentials{ids}];
+
−      end
+
−    end
+
−
+
−
+
−    function cacheCredentials(cm, c)
+
−    % CACHECREDENTIALS Adds to or updates the credentials cache.
+
−
+
−      import utils.const.*
+
−
+
−      % find entry to update
+
−      ids = findCredentialsId(cm, c.hostname, c.database, c.username);
+
−
+
−      % set password expiry time
+
−      if ischar(c.password)
+
−        c.expiry = double(time()) + cm.credentialsExpiry;
+
−      end
+
−
+
−      if isempty(ids)
+
−        % add at the end
+
−        utils.helper.msg(msg.PROC1, 'add cache entry %s', char(c));
+
−        cm.credentials{end+1} = c;
+
−      else
+
−        for id = ids
+
−          % update only if the cached informations are less than the one we have
+
−          if length(c) > length(cm.credentials{id})
+
−            utils.helper.msg(msg.PROC1, 'update cache entry id=%d %s', id, char(c));
+
−            cm.credentials{id} = c;
+
−          else
+
−            % always update expiry time
+
−            cm.credentials{id}.expiry = c.expiry;
+
−          end
+
−        end
+
−      end
+
−    end
+
−
+
−
+
−    function [username, password, cache] = inputCredentials(cm, cred)
+
−    % INPUTCREDENTIALS Queries the user for database username and password.
+
−
+
−      % build a cell array of usernames
+
−      users = {};
+
−      for id = 1:numel(cred)
+
−        if ~isempty(cred(id).username)
+
−          users = [ users { cred(id).username } ];
+
−        end
+
−      end
+
−      users = sort(unique(users));
+
−
+
−      parent = com.mathworks.mde.desk.MLDesktop.getInstance().getMainFrame();
+
−      dialog = javaObjectEDT('connectionmanager.CredentialsDialog', ...
+
−          parent, cred(1).hostname, cred(1).database, users, cm.cachePassword);
+
−      dialog.show();
+
−      if dialog.cancelled
+
−        throw(MException('utils:mysql:connect:UserCancelled', '### user cancelled'));
+
−      end
+
−      username = char(dialog.username);
+
−      password = char(dialog.password);
+
−      cache    = logical(dialog.cache);
+
−    end
+
−
+
−
+
−    function [hostname, database, username] = selectDatabase(cm, credentials)
+
−    % SELECTDATABASE Makes the user choose to which database connect to.
+
−
+
−      parent = com.mathworks.mde.desk.MLDesktop.getInstance().getMainFrame();
+
−      dialog = javaObjectEDT('connectionmanager.DatabaseSelectorDialog', parent);
+
−      for c = credentials
+
−        dialog.add(c.hostname, c.database, c.username);
+
−      end
+
−      dialog.show();
+
−      if dialog.cancelled
+
−        throw(MException('utils:mysql:connect:UserCancelled', '### user cancelled'));
+
−      end
+
−      hostname = char(dialog.hostname);
+
−      database = char(dialog.database);
+
−      username = char(dialog.username);
+
−      if isempty(username)
+
−        username = [];
+
−      end
+
−    end
+
−
+
−  end % private methods
+
−
+
−end % classdef