{"id":2945,"date":"2022-12-14T03:30:50","date_gmt":"2022-12-14T08:30:50","guid":{"rendered":"https:\/\/blogs.mathworks.com\/developer\/?p=2945"},"modified":"2022-12-14T03:30:50","modified_gmt":"2022-12-14T08:30:50","slug":"the-power-of-encapsulation","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/developer\/2022\/12\/14\/the-power-of-encapsulation\/","title":{"rendered":"Han Solo Revisited"},"content":{"rendered":"

A long time ago in a blog post far, far away… Andy wrote about Han Solo Encapsulation<\/a> – to keep Jabba’s “system working as designed he needed to encapsulate his system behind a rock solid interface”.<\/p>

By a stroke of good fortune, or judicious design choices depending on your perspective, a recent refactoring job that I thought could have far reaching consequences turned into a few changes in a single class, ultimately saving much time. Let’s have a look.<\/p>

My scenario is that I have a DataProvider<\/tt> that accepts a DataRequest<\/tt> and returns some data:<\/p>

\r\nclassdef<\/span> DataProvider\r\n    \r\n    methods<\/span>\r\n        \r\n        function<\/span> data = getData(dataProvider,dataRequest)\r\n\r\n            arguments<\/span>\r\n                dataProvider (1,1) DataProvider\r\n                dataRequest (1,1) DataRequest\r\n            end<\/span>\r\n\r\n            % Implementation continues...<\/span>\r\n\r\n        end<\/span>\r\n        \r\n    end<\/span>\r\n    \r\nend<\/span>\r\n<\/pre>\r\n
The DataRequest<\/tt> looks like this:<\/p>
\r\nclassdef<\/span> DataRequest\r\n    \r\n    properties<\/span>\r\n        Make (1,1) string = missing\r\n        Model (1,1) string = missing\r\n        ManufacturingYear (1,1) datetime = missing\r\n    end<\/span>\r\n    \r\nend<\/span>\r\n<\/pre>\r\n
To form its query, the DataProvider<\/tt> must extract the values of each property. To do this, it needs to know that “unset” is represented by “missing” and therefore it should be ignored from the search condition.<\/p>
Here’s one possible implementation in DataProvider<\/tt>:<\/p>
\r\nclassdef<\/span> DataProvider\r\n    \r\n    methods<\/span>\r\n        \r\n        function<\/span> data = getData(dataProvider,dataRequest)\r\n\r\n            arguments<\/span>\r\n                dataProvider (1,1) DataProvider\r\n                dataRequest (1,1) DataRequest\r\n            end<\/span>\r\n            \r\n            searchTerms = {};\r\n            propsToGet = [\"Make\"<\/span> \"ManufacturingYear\"<\/span> \"Model\"<\/span>];\r\n            \r\n            for<\/span> prop = propsToGet\r\n                if<\/span> ~ismissing(dataRequest.(prop))\r\n                    searchTerms = [searchTerms {prop} {dataRequest.(prop)}];\r\n                end<\/span>\r\n            end<\/span>\r\n\r\n            result = dataProvider.search(searchTerms{:});\r\n\r\n            % Implementation continues...<\/span>\r\n\r\n        end<\/span>\r\n        \r\n    end<\/span>\r\n    \r\nend<\/span>\r\n<\/pre>\r\n
The problem here is that DataProvider<\/tt>, and any other code<\/i> that makes use of DataRequest<\/tt>, is coupled to how DataRequest<\/tt> represents its “unset” values. That’s something that should be encapsulated within the DataRequest<\/tt>. What my DataProvider<\/tt> really wants is an array of name-value pairs of non-missing property names and values.<\/p>
(We could also describe this as an instance of the tell don’t ask<\/i> principle<\/a> since we’re not actually hiding DataRequest<\/tt>’s properties from the outside world.)<\/p>
Let’s refactor the DataRequest<\/tt> to add a method that does just that. I’ve called it namedargs2cell<\/tt> due to its similarity to the built-in MATLAB function<\/a>.<\/p>
\r\nclassdef<\/span> DataRequest\r\n    \r\n    properties<\/span>\r\n        Make (1,1) string = missing\r\n        Model (1,1) string = missing\r\n        ManufacturingYear (1,1) datetime = missing\r\n    end<\/span>\r\n    \r\n    methods<\/span>\r\n        \r\n        function<\/span> paramCell = namedargs2cell(dataRequest)\r\n            \r\n            arguments<\/span>\r\n                dataRequest (1,1) DataRequest\r\n            end<\/span>\r\n            \r\n            paramCell = {};\r\n            propsToGet = [\"Make\"<\/span> \"ManufacturingYear\"<\/span> \"Model\"<\/span>];\r\n            \r\n            for<\/span> prop = propsToGet\r\n                if<\/span> ~ismissing(dataRequest.(prop))\r\n                    paramCell = [paramCell {prop} {dataRequest.(prop)}];\r\n                end<\/span>\r\n            end<\/span>\r\n            \r\n        end<\/span>\r\n        \r\n    end<\/span>\r\n    \r\nend<\/span>\r\n<\/pre>\r\n
This makes our DataProvider<\/tt> much simpler:<\/p>
\r\nclassdef<\/span> DataProvider\r\n    \r\n    methods<\/span>\r\n        \r\n        function<\/span> data = getData(dataProvider,request)\r\n\r\n            arguments<\/span>\r\n                dataProvider (1,1) DataProvider\r\n                request (1,1) DataRequest\r\n            end<\/span>\r\n\r\n            searchTerms = namedargs2cell(request);\r\n            result = dataProvider.search(searchTerms{:});\r\n\r\n            % Implementation continues...<\/span>\r\n\r\n        end<\/span>\r\n        \r\n    end<\/span>\r\n    \r\nend<\/span>\r\n<\/pre>
Returning to our encapsulation principle, what do we achieve? In my real-life case, I wanted to change the DataRequest<\/tt> to allow multiple values to be specified for a given property rather than just scalars. It therefore makes sense to represent “unset” with an empty rather that with a scalar missing. Since all knowledge of how “unset” is represented is contained within the DataRequest<\/tt>, the only changes<\/i> I needed to make were within DataRequest<\/tt> itself. No other code had to be touched:<\/p>
\r\nclassdef<\/span> DataRequest\r\n    \r\n    properties<\/span>\r\n        Make (1,:) string\r\n        Model (1,:) string\r\n        ManufacturingYear (1,:) datetime\r\n    end<\/span>\r\n    \r\n    methods<\/span>\r\n        \r\n        function<\/span> paramCell = namedargs2cell(dataRequest)\r\n            \r\n            arguments<\/span>\r\n                dataRequest (1,1) DataRequest\r\n            end<\/span>\r\n            \r\n            paramCell = {};\r\n            propsToGet = [\"Make\"<\/span> \"ManufacturingYear\"<\/span> \"Model\"<\/span>];\r\n            \r\n            for<\/span> prop = propsToGet\r\n                if<\/span> ~all(isempty(dataRequest.(prop)))\r\n                    paramCell = [paramCell {prop} {dataRequest.(prop)}];\r\n                end<\/span>\r\n            end<\/span>\r\n            \r\n        end<\/span>\r\n        \r\n    end<\/span>\r\n    \r\nend<\/span>\r\n<\/pre>\r\n
In the above, note how ismissing<\/tt> has become all(isempty(…))<\/tt>.<\/p>
In conclusion, by providing the right interface to your classes, code changes can become much more limited in scope and easier to implement.<\/p>
It defines relevant properties that the DataProvider<\/tt> needs to serve up the data. All the values are scalar and have default values of missing<\/a> to represent the fact that they are “unset” by the user.<\/p>