AHashMap.m

Go to the documentation of this file.

classdef AHashMap<mxberry.core.cont.ondisk.IOnDiskBranchedStorage
    
    properties (Constant,Abstract,GetAccess=protected)
        IGNORE_EXTENSIONS
        ALLOWED_EXTENSIONS
        
    end
    properties (Access=protected,Hidden)
        storageLocation
        storageLocationRoot
        isPutErrorIgnored=false
        isBrokenStoredValuesIgnored=false
        fileExtension
        isHashedPath=true
        isHashedKeys=false
        saveFunc=@(x,y,z)1
        loadKeyFunc=@(x)1
        loadValueFunc=@(x)1
        storageFormat='none'
        isMissingKeyBlamed=false
        isStorageContentChecked=true;
        storageBranchKey
    end
    methods
        function isHashedPath=getIsHashedPath(self)
            isHashedPath=self.isHashedPath;
        end
        function isHashedKeys=getIsHashedKeys(self)
            isHashedKeys=self.isHashedKeys;
        end
        function self=AHashMap(varargin)
            import mxberry.core.parseparext;
            import mxberry.core.cont.DiskBasedHashMap;
            %
            [~,~,isStorageBranchKeySkipped,storageLocationRoot,...
                storageBranchKey,self.isPutErrorIgnored,...
                self.isBrokenStoredValuesIgnored,self.storageFormat,...
                self.isHashedPath,self.isHashedKeys,...
                self.isStorageContentChecked,...
                ~,isStorageLocSpec,isStorageBranchKeySpec]=...
                mxberry.core.parseparext(varargin,...
                {'skipStorageBranchKey','storageLocationRoot',...
                'storagebranchkey','ignoreputerrors',...
                'ignorebrokenstoredvalues','storageformat',...
                'usehashedpath','usehashedkeys',...
                'checkstoragecontent';...
                false,char(1,0),'default',self.isPutErrorIgnored,...
                self.isBrokenStoredValuesIgnored,self.storageFormat,...
                self.isHashedPath,self.isHashedKeys,...
                self.isStorageContentChecked;...
                'islogscalar(x)','isstring(x)',...
                'isstring(x)','islogscalar(x)',...
                'islogscalar(x)','isstring(x)',...
                'islogscalar(x)','islogscalar(x)',...
                'islogscalar(x)'},[0 1]);
            %
            if ~isStorageBranchKeySpec
                storageBranchKey='default';
            end
            %
            if self.isHashedPath
                storageBranchKey=mxberry.core.hash(storageBranchKey);
            end
            %
            if ~isStorageLocSpec
                metaClass=metaclass(self);
                storageLocationRoot=fileparts(which(metaClass.Name));
            end
            %
            %
            if isStorageBranchKeySkipped
                self.storageLocation=storageLocationRoot;
                storageBranchKey='';
            else
                self.storageLocation=[storageLocationRoot,filesep,...
                    storageBranchKey];
            end
            %
            self.storageLocationRoot=storageLocationRoot;
            %
            self.storageBranchKey=storageBranchKey;
            %
            if ~strcmpi(self.storageFormat,'none')
                if ~mxberry.io.isdir(self.storageLocation)
                    %check that a directory if exists, containts only mat files
                    mxberry.io.mkdir(self.storageLocation);
                else
                    self.checkStorageDir(self.storageLocation);
                end
            end
            %
        end
        %
        function fullFileName=getFileNameByKey(self,keyStr,varargin)
            import mxberry.core.throwerror;
            import mxberry.core.parseparext;
            [~,~,isPresenceChecked]=parseparext(varargin,...
                {'checkForPresence';true;'islogical(x)&&isscalar(x)'},0);
            fullFileName=self.genfullfilename(keyStr);
            if isPresenceChecked&&...
                    (~self.isKey(keyStr)&&self.isMissingKeyBlamed)
                throwerror('noRecord',...
                    ['The specified key %s is not present ',...
                    'in this container, dirName: %s'],keyStr,...
                    fileparts(fullFileName));
            end
        end
        %
        function [isKeyVec,fullFileNameCVec]=isKey(self,keyList)
            import mxberry.core.throwwarn;
            if isa(keyList,'char')
                keyList={keyList};
            end
            fullFileNameCVec=cellfun(@self.genfullfilename,keyList,...
                'UniformOutput',false);
            isKeyVec=false(1,length(fullFileNameCVec));
            nKeys=length(isKeyVec);
            for iKey=1:nKeys
                try
                    isKeyVec(iKey)=self.checkKey(fullFileNameCVec{iKey});
                catch meObj
                    if self.isBrokenStoredValuesIgnored
                        throwarn('brokenKeyValue',...
                            'a value stored for a specified is broken: %s',...
                            meObj.message);
                    else
                        rethrow(meObj);
                    end
                end
            end
            
        end
        %
        function branchKey=getStorageBranchKey(self)
            branchKey=self.storageBranchKey;
        end
        %
        function storageLocationRoot=getStorageLocationRoot(self)
            
            storageLocationRoot=self.storageLocationRoot;
        end
        %
        function storageLocation=getStorageLocation(self)
            
            storageLocation=self.storageLocation;
        end
        function put(self,keyList,valueObjList,varargin)
            import mxberry.core.throwerror;
            if ~iscell(valueObjList)
                valueObjList={valueObjList};
            end
            if ~iscell(keyList)
                keyList={keyList};
            end
            %
            isnCellVec=~cellfun(@iscell,varargin);
            varargin(isnCellVec)=cellfun(@(x){x},varargin(isnCellVec),...
                'UniformOutput',false);
            %
            if ~mxberry.core.checksize(keyList,size(valueObjList))
                throwerror('wrongInput',...
                    'keyList and valueObjList should be of the same size');
            end
            %
            cellfun(@self.putOne,keyList,valueObjList,varargin{:});
        end
        function [valueList,varargout]=get(self,keyList,varargin)
            import mxberry.core.parseparext;
            [~,~,isUniformOutput]=parseparext(varargin,...
                {'uniformOutput';true;@(x)islogical(x)&&isscalar(x)},0);
            %
            if ~iscell(keyList)
                keyList={keyList};
            end
            %
            varargout=cell(1,nargout-1);
            %
            if isUniformOutput&&length(keyList)==1
                [valueList,varargout{:}]=self.getOne(keyList{1});
            else
                [valueList,varargout{:}]=cellfun(...
                    @self.getOne,keyList,...
                    'UniformOutput',isUniformOutput);
            end
        end
        function keyList=getKeyList(self)
            SFileProp=dir([self.storageLocation,filesep,...
                ['*.',self.fileExtension]]);
            isDirVec=[SFileProp.isdir];
            fileNameList={SFileProp(~isDirVec).name};
            fileNameList=cellfun(@(x)([self.storageLocation,filesep,x]),...
                fileNameList,'UniformOutput',false);
            %
            [~,keyList]=cellfun(@(x)self.checkKey(x),fileNameList,...
                'UniformOutput',false);
        end
        function remove(self,keyList)
            if ~iscell(keyList)
                keyList={keyList};
            end
            cellfun(@self.removeOne,keyList,'UniformOutput',false);
        end
        function removeAll(self)
            storageLocation=self.getStorageLocation(); %#ok<*PROP>
            delete([storageLocation,filesep,['*.',self.fileExtension]]);
        end
        %
    end
    methods (Access=protected)
        function [isPositive,keyStr]=checkKey(self,fileName)
            import mxberry.core.throwerror;
            import mxberry.core.throwwarn;
            isPositive=mxberry.io.isfile(fileName);
            if isPositive
                warnState=warning('off','MATLAB:load:variableNotFound');
                try
                    S=self.loadKeyFunc(fileName);
                catch meObj
                    meCauseObj=throwerror('unknownFailure',...
                        'failed to load file %s',fileName);
                    meObj=meObj.addCause(meCauseObj);
                    rethrow(meObj);
                end
                warning(warnState.state,'MATLAB:load:variableNotFound');
                isPositive=isfield(S,'keyStr');
                if isPositive
                    keyStr=S.keyStr;
                else
                    keyStr='';
                    throwwarn('incorrectKeyValueFile',...
                        'key value file is invalid and will be updated');
                end
                supposedFileName=self.genfilename(keyStr);
                [~,actualFileName]=fileparts(fileName);
                if ~strcmp(supposedFileName,actualFileName)
                    throwerror('badKeyValuePair',...
                        ['key %s assumes the key value file name to be %s ',...
                        'while the actual file name is %s'],...
                        keyStr,supposedFileName,fileName);
                end
            end
        end
        function removeOne(self,keyStr)
            fullFileName=self.genfullfilename(keyStr);
            if mxberry.io.isfile(fullFileName)
                delete(fullFileName);
            end
        end
        function fullFileName=genfullfilename(self,keyStr)
            import mxberry.core.throwerror;
            if ~mxberry.core.isrow(keyStr)
                throwerror('wrongInput',...
                    'keyStr is expected to be a row-string');
            end
            fullFileName=[self.storageLocation,filesep,...
                self.genfilename(keyStr),['.',self.fileExtension]];
        end
        function putOne(self,keyStr,valueObj)
            import mxberry.core.throwwarn;
            fullFileName=self.genfullfilename(keyStr);
            try
                self.saveFunc(fullFileName,'valueObj','keyStr');
            catch meObj
                if mxberry.io.isfile(fullFileName)
                    delete(fullFileName);
                end
                %
                if self.isPutErrorIgnored
                    throwwarn('saveFailure',...
                        'cannot save the key value: %s',...
                        meObj.message);
                    return;
                else
                    rethrow(meObj);
                end
            end
        end
        %
        function valueObj=getOne(self,keyStr)
            import mxberry.core.throwerror;
            [isKey,fullFileNameCVec]=self.isKey(keyStr);
            if ~isKey
                throwerror('noRecord',...
                    'The specified key is not present in this container');
            end
            valueObj=getfield(self.loadValueFunc(fullFileNameCVec{1}),...
                'valueObj'); %#ok<GFLD>
        end
        function isPositive=isStorageDir(self,dirName)
            SFileList=dir(dirName);
            isDirVec=[SFileList.isdir];
            isIgnoredOrAllowedExtVec=self.isFileExt({SFileList.name},...
                [self.IGNORE_EXTENSIONS,self.ALLOWED_EXTENSIONS]);
            isPositive=all(isDirVec|isIgnoredOrAllowedExtVec|...
                ~self.isStorageContentChecked);
        end
        function checkStorageDir(self,dirName)
            import mxberry.core.cont.DiskBasedHashMap;
            import mxberry.core.throwerror;
            if ~self.isStorageDir(dirName)
                throwerror('wrongLocation',...
                    ['cannot create a storage at the specified location %s ',...
                    'as it contains some foreign files'],dirName);
            end
        end
    end
    methods (Access=protected,Static)
        function isPositiveVec=isFileExt(fileNameList,extList)
            regExpStr=strcat(extList,'|');
            regExpStr=[regExpStr{:}];
            regExpStr=['\.(',regExpStr(1:end-1),')$'];
            isPositiveVec=cellfun(@(x)~isempty(x),regexp(fileNameList,regExpStr));
        end
    end
    methods (Access=protected)
        function fileName=genfilename(self,inpStr)
            if self.isHashedKeys
                inpStr=mxberry.core.hash(inpStr);
            end
            %
            if ~isempty(inpStr)
                nChars=length(inpStr);
                nBlocks=fix(nChars/namelengthmax);
                blockSizeVec=[repmat(namelengthmax,1,nBlocks),rem(nChars,namelengthmax)];
                inpCutStrCVec=mat2cell(inpStr,1,blockSizeVec);
                %
                inpCutStrCVec=cellfun(@genvarname,inpCutStrCVec,'UniformOutput',false);
                fileName=[inpCutStrCVec{:}];
            else
                fileName=inpStr;
            end
            %
        end
    end
    
end