Why Should I Model?

I hear this question asked a lot and I think that it deserves a good answer. Perhaps people asked Frank LLoyd Wright “Are you going to doodle all day?”. I’m kidding here of course. Everyone knows that when embarking on a long, involved construction project requiring vision and determination, it is essential to be able to view the problem visually from a variety of view points. Oh, you’re building software? We just wing it around here. It is amazing that I have worked on many projects that cost more than the average American home and had no blue prints, yet even the cheapest homes were build using a set of drawings.

UML for the sake of UML really doesn’t add any value to the project. It is important to consider how UML or something like it can improve your communication with your work mates or clients and put these things to use in your projects.

Some Good Reasons to Model

There are many good reasons to model. Below is a partial list of the benefits of adding modeling to your development process.

• It allows you to zoom out and see how your imagined widgets might interact in a project.
• It allows you to zoom in and really map out what an entity might do.
• It allows you to concentrate on the business process you are modeling without worrying about how to actually design the application for a specific platform.
• It allows you to design the application by modeling your approach to a specific platform.
• It allows you to get involved with Model Driven Architecture by creating models and transforms that will build applications.
• It makes great marching orders for new people and employees.
• It improves your literacy in the industry of your choice. If you don’t learn to read and write UML, you’re going to be illiterate within the context of some projects. It is fairly easy to tell when people can’t read.

Getting Started

It’s easy to get started with modeling. There are some great free tools out there. I highly recommend anything built on Eclipse and ECore. Top Case D is my current favorite because it is ready to go with one simple download. I’ll be discussing Top Case in detail in other articles.

Sometimes it’s hard to accept that we aren’t going to be very good at something and this prevents us from getting started. This is a trap. I encourage you to make some terrible and terribly useful diagrams using pen and paper or a diagramming tool. The next time you start a small project, kick around your ideas for a solution with a low detail class diagram and get a feel for the process. The great thing about some of the tools is that they allow you to use a source repository for your model and even attach documents to model entities. It’s a great way to get organized and stay that way.

Conclusion

You will find that the more you create simplified snapshots in your own redneck dialect of UML, the more you will want to improve and formalize your understanding of the language. You should have heard my thick, southern cracker accent when I was a child. Hearing David Bowie made me want to learn proper English. UML is a language and the more you speak, the better you will get.

I understand that I haven’t given you concrete instructions on how to create a proper class diagram. Something tells me that you have seen plenty of examples of how to do this and still haven’t made the leap. I will be doing some tutorial videos on the topic in the future, but please don’t wait on me. I can recommend a pretty good book on the topic for a beginner. Check out UML a Beginner’s Guide by Jason T. Roff.

Draw baby draw!

The source file for the the entire framework may be downloaded here. We will be covering StringRangeRule.php.

The StringRangeRule Class

Using the abstract base class Rule which we created last time, we will build a class to solve a common validation problem. For the sake of database integrity and business goals, it is common to enforce length restrictions on some of the text properties of an object. Our string range validator can be configured to do the following.

• Set min and max length values so that the string length must fall within the range.
• Set min to zero and provide a max so that the string may be any length not exceeding the max.
• Set max to zero and provide a min so that the string may be any length as long as it is at least min characters in length.

Our class will provide a neat package for handling the tasks on the above list.

Let’s write some code!

 
We begin by using <strong>require_once</strong> to reference the <strong>Rule.php</strong> file containing our base class.  In my setup, the <strong>Rule.php</strong> file is in the same directory as  our new class.  We inherit from <strong>Rule</strong> using the <strong>extends</strong> key word.  We declare the <strong>Min</strong> and <strong>Max</strong> member variables.  These variables are declared as protected so that you could create other classes based on our new class which would have access to the Min and Max member variables.
<pre lang="php">// Public State Methods
 
	/**
	 * Minimum length allowed for string.
	 *
	 * @return number
	 */
	public function GetMin()
	{
		return $this-&gt;m_Min;
	}
 
	/**
	 * Sets minimum allowed length for string.
	 *
	 * @param number $value
	 */
	public function SetMin($value)
	{
		$this-&gt;m_Min = $value;
	}
 
	/**
	 * Maximum length allowed for string.
	 *
	 * @return number
	 */
	public function GetMax()
	{
		return $this-&gt;m_Max;
	}
 
	/**
	 * Sets maximum allowed length for string.
	 *
	 * @param number $value
	 */
	public function SetMax($value)
	{
		$this-&gt;m_Max = $value;
	}

The code above contains “getters and setters” for our member variables. Notice that I am documenting these methods per our discussion about coding style and documentation in the first article.

	// Constructors
 
	/**
	 * Constructor
	 * @param string $_ruleName
	 * @param string $_propertyName
	 * @param string $_min
	 * @param string $_max
	 *
	 */
	public function __construct($_ruleName, $_propertyName, $_min, $_max)
	{
		parent::__construct($_ruleName, $_propertyName, '');
 
		$this->m_Min = $_min;
		$this->m_Max = $_max;
 
		// check the max and min values
		$this->CheckValues();
 
		// set the display text
		$this->CalculateDisplayText();
 
	}

The constructor above takes in the rule name and property names, as does our base class, and adds two new parameters representing the min and max values for our new class. We call the constructor on the base class in line 70 using the parent::_construct() method and passing along the rule name and property name values. Values for Max and Min are then assigned based on the appropriate parameter values. In lines 76 and 79, we call helper functions in our class to check for proper min and max values and to construct a good user description based on the values for min and max.

// Overrides
 
	public function Validate($_objectToValidate)
	{
		// Check the values again to make sure the rule is set up properly.
 
		$_MethodName = 'Get' . $this->m_PropertyName;
		$this->m_PropertyValue = $_objectToValidate->$_MethodName();
 
		$this->CheckValues();
 
		$_MinOnly = $this->m_Min > 0 && $this->m_Max == 0;
		$_MaxOnly = $this->m_Max > 0 && $this->m_Min == 0;
		$_MaxAndMin = $this->m_Min > 0 && $this->m_Max > 0 && $this->m_Min < $this->m_Max;
		$_Len = strlen($this->m_PropertyValue);
 
		if($_MinOnly == true)
		{
			$this->m_IsValid = $_Len >= $this->m_Min;
			return;
		}
 
		if($_MaxOnly == true)
		{
			$this->m_IsValid = $_Len <= $this->m_Max;
			return;
		}
 
		if($_MaxAndMin == true)
		{
			$this->m_IsValid = ($_Len >= $this->m_Min)
			&& ($_Len <= $this->m_Max);
 
			return;
		}
 
	}

We arrive at our only override from the Rule base class in line 84. We declared this method to be abstract in the Rule base class, so we are required to implement the method in our new class. In line 91, we set out to get the value of the correct property from the object which has been passed in. Since we are using a convention of “getters and setters”, we can construct the proper “get” call to grab the value from the object. For example, if our rule is set to validate the LastName of a Person object at runtime, the call to get that value would be GetLastName(). Another call is placed to CheckValues() to make sure that the values are still good. We do this because the object could have been edited with the interface methods since the initial call to the constructor. Lines 96 to 99 create member variables representing how the object has been configured based on the min and max values. The length of the property value is recorded for comparison to the min and max values. Lines 101 to 119 set the m_IsValid variable for the correct configuration scenario.

	// Helper Methods
 
	/**
	 * Figures out how to display the rule text to the user based on the
	 * values of Min and Max.
	 *
	 */
	private function CalculateDisplayText()
	{
		if($this->m_Min == 0 && $this->m_Max > 0)	// we have a rule where only the max has been set
		{
			$this->m_DisplayText = $this->m_PropertyName . ' may be no longer than ' . $this->m_Max . ' characters in length.';
		}
 
		if($this->m_Min > 0 && $this->m_Max == 0)	// we have a rule where only the min has been set
		{
			$this->m_DisplayText = $this->m_PropertyName . ' must be at least ' . $this->m_Min . ' characters in length.';
		}
 
		if($this->m_Min > 0 && $this->m_Max > 0 && $this->m_Min < $this->m_Max)	// we have a rule where min and max have been set
		{
			$this->m_DisplayText = $this->m_PropertyName . ' must be between ' . $this->m_Min . ' and ' . $this->m_Max . ' characters in length.';
		}
	}
 
	/**
	 * Checks values for min and max set by the programmer.
	 * Min must be less than max if max is greater than zero.
	 * Max must be greater than min if min is greater than zero.
	 * Neither may be a negative number.
	 * Both values may not be equal to zero at the same time.
	 *
	 */
	private function CheckValues()
	{
		// check for negative values
		if($this->m_Min < 0 || $this->m_Max < 0)
		{
			throw new Exception('Min or Max values may not be less than zero.');
		}
 
		// check for double zeros.
		if($this->m_Min == 0 && $this->m_Max == 0)
		{
			throw new Exception('Min or Max values may not both be set to zero.');
		}
 
		// check for min less than max when max is set
		if($this->m_Max > 0 && $this->m_Min >= $this->m_Max)
		{
			throw new Exception('If Max is set to a non zero number, Min must be less than Max.');
		}
 
		// check for max greater than min when min is set
		if($this->m_Min > 0 && $this->m_Max <= $this->m_Min && $this->m_Max != 0)
		{
			throw new Exception('If Min is set to a non zero number, Max must be greater than Min.');
		}
 
	}
 
}
?>

CalculateDisplayText() creates a message for the user based on how the min and max values are set. You can see that CheckValues() is throwing an exception if there are crazy values set up for an object of our class. These kinds of errors would be the result of improper coding while using the class. Their audience is the developer. I feel that it is important to provide this kind of feedback for others.

Conclusion

We now have a base class and a product of that class to use going forward with our framework. Hopefully, you’re thinking of a few other classes you might create to handle some common validation situations that you run in to. Feel free to send in your code. I will add them to the framework and discuss the new classes on the blog. In the next article, we are going to build another abstract base class which makes use of the validation classes we have created so far. I know it’s a long road, but we’ll have some really cool development tools as we move forward.

Also Available in This Series

• A Business Objects Framework for Wordpress
• Building Monkey Wrench – The Rule Classes

The Normal Way

Suppose that you have a few config settings in the config file. Our example has three settings. Two of the settings are strings and the last one should be cast to a long. Let us also suppose that we want to throw an exception reminding the developer that the application is not configured correctly if either of the string settings are missing. For the long setting, we do not wish to throw an error if the setting is missing. We would prefer to assume a default value unless the config file says otherwise. If we don’t have a class in which to house these policies, the code gets pretty messy. Below is and example of a few simple calls with no wrapper.

public void Before()
{
    // get the connection string for the database
 
    if (ConfigurationManager.ConnectionStrings["CacheDBConnection"] == null)
        throw new Exception("Config setting 'CacheDBConnection' does not exist in the config file.");
 
    // if the exception doesn’t throw, we can keep going
    string _ConnectionString = ConfigurationManager.ConnectionStrings["CacheDBConnection"].ConnectionString;
 
    // get the default size for the cache from the config file
 
    long _CacheSize = 0;
 
    if (ConfigurationManager.ConnectionStrings["CacheSizeLimit"] != null)
        _CacheSize = long.Parse(ConfigurationManager.AppSettings["CacheSizeLimit"]);
}

The above approach has many disadvantages including the following items.

• It is verbose
• Making several calls like this would generate a lot of duplicate code. This is a real problem for maintenance.
• It is likely that many people would not put in repetitious checks for a valid configuration out of sheer laziness.
• You have to remember the name of the config settings without any help from intellisense while you’re in the heat of coding.

A Solution to Messy Config Code

The manager class I created here was built for a caching manager, so it is called ObjectCacheConfig. You can build your config class to your own specifications taking some inspiration from the class presented. The class file may be downloaded by clicking here.

I built this class as a static class to avoid the need for an instance. This is a fairly common pattern in .Net and I use it frequently for utility classes which need no state. The public static properties access the appropriate config file settings and perform any validity checks and casting required. The VerifyAppSetting() helper method allows some flexibility in your policy regarding missing config settings. VerifyConnectionString() will throw an error if the connection string does not exist.

Note: In the code example below, I was unable to include my usual XML documentation comments due to formatting problems with my source code display plugin. The XML comments are included with the actual source file.

using System;
using System.Text;
using System.Configuration;
 
namespace ObjectCacheCore
{
 
    public class ObjectCacheConfig
    {
 
        #region Static Properties
 
        public static string CacheDBConnection
        {
            get
            {
                VerifyConnectionString("CacheDBConnection");
 
                return ConfigurationManager.ConnectionStrings["CacheDBConnection"].ConnectionString;
            }
        }
 
        public static string CacheDBTable
        {
            get
            {
                VerifyAppSetting("CacheDBTable", true);
 
 
                return ConfigurationManager.ConnectionStrings["CacheDBTable"].ConnectionString;
            }
 
        }
 
        public static long CacheSizeLimit
        {
            get
            {
                long _SizeLimit = 0;
                if (VerifyAppSetting("CacheSizeLimit", false))
                {
                    _SizeLimit = long.Parse(ConfigurationManager.AppSettings["CacheSizeLimit"]);
                }
 
                return _SizeLimit;
            }
 
        }
 
        #endregion
 
        #region Helper Methods
 
        private static bool VerifyAppSetting(string settingName, bool throwIfNull)
        {
            bool _Exists = ConfigurationManager.AppSettings[settingName] != null;
 
            if (!_Exists && throwIfNull)
            {
                string _Message = "Application setting '" + settingName + "' does not exist in the config file.";
                throw new ConfigurationErrorsException(_Message);
            }
 
            return _Exists;
        }
 
        private static void VerifyConnectionString(string connectionName)
        {
            bool _Exists = ConfigurationManager.ConnectionStrings[connectionName] != null;
 
            if (!_Exists)
            {
                string _Message = "Connection string '" + connectionName + "' does not exist in the config file.";
                throw new ConfigurationErrorsException(_Message);
            }
 
        }
 
        #endregion
    }
 
}

Life After the Config Class

Let’s see what our access code would look like now that the config manager class has been written. The code below accomplishes the same result as our first code sample in the article.

public void After()
{
    // get the connection string
    string _ConnectionString = ObjectCacheConfig.CacheDBConnection;
 
    // get the configured cache size limit
    long _CacheSize = ObjectCacheConfig.CacheSizeLimit;
 
}

In Conclusion

Using a pattern similar to the above class can really clean up your application code with regard to config access. We reduced the code size and eliminated duplicate code. Now, while coding, Visual Studio will give you a drop down menu of your config settings with full documentation for the setting if you have your xml comments in place. It is a simple pattern, yet it could change your code dramatically if you use a lot of config settings.

Happy coding!

Monkey Wrench Core Classes

The following UML diagram shows the basic class structure for the earliest version of our framework.  I’ll go over each class in detail over the next several articles.  This article will focus on dealing with validation rules.

Monkey Wrench Class Diagram

The above diagram isn’t perfect UML.  I have simplified the classes to basic properties and operations for the sake of clarity.  The actual implementation will be more elaborate.  The green classes are abstract.  The blue classes are concrete classes built by inheriting from the base classes.

The Abstract Rule Class

As mentioned in Part I of this series of articles, part of Monkey Wrench’s charter is to provide built in validation of our business objects.  We will need a way to represent a validation rule for our objects.  Validation may take on many forms, so it would be clunky to try and create a one-size-fits-all rule class.  Instead, let’s create an abstract base class from which to create rule classes that will do their own work.  Over time, you can build a nice library of validators and use them in your projects.  Custom one-off rule classes may be created for elaborate, specific validation tasks that are unique to a specific object.

Our Rule object should inform the user about the particulars of a validation or business rule.  It should also take in some parameters and evaluate the object.

Properties of the Rule Class

• Name - A unique name to identify the Rule instance in a list.  Example:  “Last Name Length”
• DisplayText – A full description of the Rule to be displayed in the User Interface at run time.  Example:  “Last Name must be at least 5 characters in length.”
• PropertyName - Name of the property of our business object to which the validation rule instance is attached.  Example:  “LastName”.

Operations of the Rule Class

• IsValid() – Returns the result of the validation.
• SetRuleValue() – Allows for the manual setting of the IsValid() value.  We’ll need this sometimes, but most often our Rule subclass will take care of setting this value.
• Validate() – An abstract method to be implemented by the subclasses.  This is where the object performs the actual validation.  The object to validate is passed in as a parameter to the Validate() method.

The Rule Class Implementation

The source file for the the entire framework may be downloaded here.  We’ll be looking at the Rule.php file.

This following section of code defines our abstract base class and a few protected member variables which may be accessed by our concrete subclasses.  All of the variables were explained earlier with the exception of the m_PropertyValue variable.  The m_PropertyValue variable is used to contain the actual data represented by the PropertyName on the object which is being validated.  So, if you have an object called Person with a LastName property, our subclass would fetch the value stored in Person->LastName and store that value in m_PropertyValue.

Notice that I am using JavaDoc style comments here.  The Doygen documentation tool can generate API documents from these comments.  This is a personal preference, but a useful artifact in your code if you want good documentation.  IDE’s such as PHPEclipse read these comments in real time and give you more feedback as to what your functions do with tooltips and prompts.

Also, I preface the class level variables with an “m_”.  I do this so that it is easy to tell the scope of the variable when you are down in a function.  Modern IDE’s like PHPEclipse make it easier to track down where a variable is declared.  Having a convention for scope is very handy when you don’t have a fancy IDE.

1
2
3
4
5
6
7
8
9
10
11
12

<?php
/**
 * Class representing a business or validation rule. *
 */
abstract class Rule
{
	// Member Variables
	protected $m_Name = '';
	protected $m_DisplayText = '';
	protected $m_PropertyName = '';
	protected $m_PropertyValue = '';
	protected $m_IsValid = false;

The next section has  the “getters” and “setters” one would expect in Java and other curly brace languages.  It is times like these when I really miss C#.  Maybe one day PHP will have properties.  For the Rule class, this is not required, but I’m trying to keep reasonable form here.

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

	// Public State Methods
 
	/**
	 * Unique Name for the rule.
	 *
	 * @return string
	 */
	public function GetName()
	{
		return $this->m_Name;
	}
 
	/**
	 * Sets unique Name for the rule.
	 *
	 * @param string $value
	 */
	public function SetName($value)
	{
		$this->m_Name = $value;
	}
 
	/**
	 * Name of the Property to be validated.
	 *
	 * @return string
	 */
	public function GetPropertyName()
	{
		return $this->m_PropertyName;
	}
 
	/**
	 * Sets the name of the Property to be validated.
	 *
	 * @param string $value
	 */
	public function SetPropertyName($value)
	{
		$this->m_PropertyName = $value;
	}
 
	/**
	 * Display text for the rule.
	 * Used to notify the user of the exact purpose of the rule.
	 *
	 * @return string
	 */
	public function GetDisplayText()
	{
		return $this->m_DisplayText;
	}
 
	/**
	 * Sets Display text for the rule.
	 *
	 * @param string $value
	 */
	public function SetDisplayText($value)
	{
		$this->m_DisplayText = $value;
	}

In the last bit of code, we have the IsValid() and SetRuleValue() methods described earlier in the article.  There is also a constructor and an abstract declaration for the Validate() method.

78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

	/**
	 * Indicates whether or not the rule has passed validation.
	 *
	 * @return boolean
	 */
	public function IsValid()
	{
		return $this->m_IsValid;
	}
 
	/**
	 * Sets the value of the IsBroken member variable
	 * to the parameter value
	 *
	 * @param  boolean $value
	 */
	public function SetRuleValue($value)
	{
		$this->m_IsValid = $value;
	}
 
	// Constructors
 
	/**
	 * Constructor: sets name and display text.
	 *
	 * @param  string $_name;
	 * @param  string $_displayText;
	 * @param  string $_propertyName;
	 */
	public function __construct($_name, $_propertyName, $_displayText)
	{
		$this->m_Name = $_name;
		$this->m_PropertyName = $_propertyName;
		$this->m_DisplayText = $_displayText;		
	}
 
 
	// Abstract Methods
 
	public abstract function Validate($_objectToValidate);
 
}
?>

Although our code doesn’t do very much, we have laid a reasonable foundation from which to build validators.  In the next article, we will use the Rule class to build a validator for string ranges.  Frameworks aren’t the most exciting things to read about, but I promise that you’ll be able to see the payoff if you hang in there with me.

Also Available in This Series

• A Business Objects Framework for Wordpress
• Creating a String Range Rule with Monkey Wrench

Why Build a Framework?

Frameworks are useful for many reasons. Below is a short list of some of the most common benefits of developing a business objects framework.  For an exhaustive presentation on the rationale for using frameworks as well as a complete discussion of the design of a complete framework, I recommend Expert C# 2008 Business Objects.

• Separation of Concerns – Code for the business logic and persistence details may exist in one or more layers.  This keeps database concerns and business logic out of the UI code.  A layered architecture makes it easier to build a variety of user interfaces for the same code base.
• Specialization of Tasks -   The layered architecture allows people on a team to work on the programming tasks for which they are most suited.  I am a terrible web developer.  I like the fact that I can build a robust core and let the people with black turtlenecks put a slick user interface on top of it.  It is also a relief to designers that they can concentrate on the interface and use a simple, clean API which has been prepared for them by the core programmers.
• Coding Standards – Frameworks set a good example by helping to establish coding style and methods for all of the developers on a team.  Even when working alone, the establishment of styles and patterns is very helpful and increases productivity.
• Collaboration – All of the above items result in better collaboration in a team environment.  It is easy to get help from others when you have a clean and easy to follow code base.  New trainees also get up to speed a lot faster in the presence of a framework.  This builds confidence very early for new people and it also means that they are actually helping out on day one.
• Code Generation – Established style and methodology make it easy to generate a significant percentage of your boring, boiler plate, error prone work using a code generation tool.  It is fairly easy to write code generation tools and there are a few really nice free tools to do the job as well.  We’ll get in to this in other articles.

What Will Our Framework Do?

The framework we are going to design will take care of the following tasks.

• CRUD - Creation, Retrieval, Update and Deletion of records in the database.
• Validation – Our objects will be self validating.  All validation rules for fields and business logic for the entities will be represented as classes.

Our framework will be implemented in one layer.  I am creating the framework for use with the Wordpress blogging system, so I’ll make use of some of the nice database features built in to Wordpress.  The framework may be used outside the Wordpress environment by including the proper files which allow use of $wpdb.  For more information of $wpdb, go here.  Of course, you could use another database.  It is also possible to separate the actual data access code into another suite of classes.  This takes a lot of extra work, but it does allow you to swap out your database technology without changing the rest of your code. This approach makes sense if you might switch database platforms.

Before we continue and actually build the framework, we should give it a name. I am tired of typing “the framework”.  For a working title, let’s call it Monkey Wrench. My wife, Jana, is rather fond of monkeys, so I’m sure she would approve.

Coming Up. Building Monkey Wrench

In the next article, we will begin building the Monkey Wrench framework.  See you next time!

Also Available in This Series

• Building Monkey Wrench – The Rule Classes
• Creating a String Range Rule with Monkey Wrench