I am back after a short break. Let’s continue where we left off. Today I will talk about object oriented Lotusscript. We looked at functions in part 3 of this series, and while functions are very useful, you should consider building objects instead.
So why would you use classes? The short answer is that they are much more powerful and also much easier to maintain. The code is usually shorter and I get a better overview. It is modular and can easily be moved to other applications. It is easy to maintain and add functionality. And the calling code can be very compact and easy to understand as well.
You are already using objects/classes today, when you are writing Lotusscript code. The DOM (Domino Object Model) are made up of classes that let you access different Domino objects, like sessions, databases, views, documents, etc. You already know how to call and use classes, now we will look at creating your own. It is much easier than you probably think.
About 2 years ago, I wrote two articles about object oriented Lotusscript, but the code samples were scrambled when I moved my blog to WordPress. You can find the old articles here and here. But the article you are currently reading will be look at a more basic class, and explain more of the code.
I have posted several classes here on my blog in the past, doing different things:
Get latitude and longitude for an address – Win32 only
Mail Merge/Form Letters in Lotusscript
Mail Notification Class
Class for File Functions
HTML Retrieval Class – Win32 only
Accessing Windows Clipboard – Win32 only
Take a look at those article and you should get an understanding of how to write a class..
Your First Class
Let’s start with a very simple class. It will contain some math functions. We will start with just one, used to add two values together.
Option Public Option Declare Class MathClass Public value1 As Integer Public value2 As Integer %REM Sub New() Description: Constructor for the class %END REM Public Sub New() '*** We will add code here later End Sub %REM Function Add() Description: Adding value1 and value2 and retur result %END REM Public Function Add() As Integer Add = value1 + value2 End Function End Class
And this is how you use the class:
Sub Initialize Dim math As MathClass '*** Create new instance of MathClass Set math = New MathClass() '*** Set the two values in the class math.value1 = 4 math.value2 = 6 '*** Display the result of the Add() function MsgBox math.Add() End Sub
Easy, wasn’t it? However, we can expand a little on this. Instead of assigning the variables value1 and value2 after the math object is created, we can pass the values to the object at create time:
Option Public Option Declare Class MathClass Public value1 As Integer Public value2 As Integer %REM Sub New() Description: Constructor for the class, taking two integers as arguments %END REM Public Sub New(arg1 As Integer, arg2 As Integer) value1 = arg1 value2 = arg2 End Sub %REM Function Add() Description: Adding value1 and value2 and return result %END REM Public Function Add() As Integer Add = value1 + value2 End Function End Class
And here is the updated code to use the class:
Sub Initialize Dim math As MathClass '*** Create new instance of MathClass Set math = New MathClass(4,6) '*** Display the result of the Add() function MsgBox math.Add() End Sub
We can now easily add more functions to the class, for subtraction, multiplication, etc.
Get/Set properties of your class
Often it is a good idea to check the values you pass to the class. The easiest way is to use the Set properties. You use the corresponding Get property to read values from the class. In this example, we will check if the value is greater than 100, and if so we will reduce the value by 100 before storing it in the rivate variable used inside the class.
Option Public Option Declare Class MathClass Private p_value1 As Integer Private p_value2 As Integer %REM Sub New() Description: Constructor for the class %END REM Public Sub New() End Sub %REM Property Set value1 Description: Set value1 and subtract 100 if needed %END REM Property Set value1 If value1>100 Then p_value1 = value1 - 100 Else p_value1 = value1 End If End Property %REM Property Set value2 Description: Set value2 and subtract 100 if needed %END REM Property Set value2 If value2>100 Then p_value2 = value2 - 100 Else p_value2 = value2 End If End Property %REM Function Add() Description: Adding value1 and value2 and return result %END REM Public Function Add() As Integer Add = p_value1 + p_value2 End Function End Class
We call the class exactly like in our first example. But remember that we reduce the number by 100 if it is larger than 100. The output of this code is identical to the previous examples:
Sub Initialize Dim math As MathClass '*** Create new instance of MathClass Set math = New MathClass() '*** Set properties of the object math.value1 = 4 math.value2 = 106 '*** Display the result of the Add() function MsgBox math.Add() End Sub
Let’s say we want to add a function that subtract the first value from the second value. We then just add a Subtract() function to the class:
%REM Function Subtract() Description: Subtracting value1 from value2 and return result %END REM Public Function Subtract() As Integer Subtract = p_value2 - p_value1 End Function
Now you have the foundation of object oriented Lotusscript. Go forth and conquer!
You made small typo in the last example with the Subtract(); instead of
Add = p_value2 – p_value1
it should be
Subtract = p_value2 – p_value1
Pretty good starting examples, but I would not recommend using the “Property” syntax since I have experienced a lot of bugs with it; It is ok for setting/getting strings and integers, but it can’t handle more complex objects.
I would recommend using functions and subs, that has their direct equivalent in other object oriented languages, but Property hasn’t. By using functions You force the calling code to become much more clear in what it is supposed to do and expect:
Set math = New MathClass()
When adding, it really isn’t that big difference, but consider Your second example; when doing subtraction, it becomes extremely important which value is the left and which is the right. How is that determined by the properties?
math.value1 = 4
math.value2 = 6
state? Is it the left or the right that is considered to be value1? Ambigous in how to interpret the call to math.Subtract(). Should we expect 4 – 6 or 6 – 4? By declaring setter and getter functions that are named better You will follow the convention of other languages as Java etc that dosen’t have Property setters/getters. By doing this from the start, Your transition to other OO-languages will be easier to understand.
Properties lack the transparancy in what the programmer expects to find: If You add a value to a property – You don’t expect the data to be processed in any way. It should be simple unchanged data, fields should store whatever You tell it to store.
If You need to tell to the calling code “Hey, I’m going to do validation and maybe change Your data before storing it!” then use functions, since this is what is expected of functions.
If You do:
math.value1 = 235234
I would not think for a moment that reading value1 should render anything else than 235234, but if You do a Property method that for some odd reason change the data like Your example, I would find myself in deep deep trouble – how on earth can math.value1 = 235234 become 235134 when reading it? It simply doesn’t make any sense for class fields to changing input data before storing!
But use a function and I would know that the function is processing my input before storing.
Thanks for a great serie of articles!
Thanks, fixed that typo!
I agree that value1 and value2 is not very clear in the Subtract example. I could have created a much more complicated and more true to “real life” example, but I wanted to keep it simple. Perhaps I should have used multiplication instead.
And yes, in real life one would use more logical names for the variables/properties. But any programmer would be able to understand that, this series is (as I stated in my initial post) not a beginners guide to programming, but a list of tips for somewhat experienced Notes/Domino programmers to make them better programmers.
I think that it’s great that you’re sharing this sort of knowledge. Although many purists disparage LS as an inferior language, it’s still the most commonly used programming technology on the Notes platform. Like any language it can be abused by poor practices and get a bad name for the wrong reasons. References on good LS coding practice are hard to come by.
I try to be a programming-atheist and so I would prefer gets the job done, is maintainable and robust, over “pure” any day….Thanks for sharing.
Karl is absolutely right. Custom Classes and Object Oriented LotusScript Rock. I highly recommend anyone to try it.
And if you have an eye to XPages, or you’re there now. Java Beans in XPages is the equivalent of LotusScript Custom Classes. So if you start with OOP in LotusScript, you’re have a much easier time if you want to get into Java inside XPages.
The real power of “object-oriented”, is via the use of “Base” and “Derived” classes — where you can use the base class, to hold all the common automation (across a variety of similar but slightly different types of objects) — and then the derived classes can be easily used to deliver only the custom data or functions, for each of those slightly different types of objects.
Most importantly, via this level of OOP — it all becomes much more “Fun” — due to the ease of handling the common vs the differences, for similar types of objects.