Click here to Skip to main content
Click here to Skip to main content

The Essence Pattern in C#

, 7 Oct 2013
Rate this:
Please Sign up or sign in to vote.
An implementation of the Essence Pattern in C#

Introduction

The Essence Pattern provides a way to enforce users of an object to enter valid properties for that object. A full description of the pattern can be found in the original paper here (PDF). In this article, I shall provide a C# implementation of this pattern.

Background 

If you are providing an external interface to your code either as an API or because your code forms a tier in an n-tier system, then the Essence Pattern can be used to force other programmers to put valid, required fields into an object before they start using that object. One common situation where this is required is for key fields to be saved to a database. The user of the object must not attempt to save that object to the database without the key properties, or the database will complain.

Of course, you could simply provide just one constructor that forces the programmer to enter all the required properties. In the simple case this is perfectly acceptable. However, if you are exposing an external interface, you may also want it to be COM wrappable. In this case, you can only have one, parameterless constructor which disallows that particular strategy. Also, what if there are a lot of required parameters, some of which need to be calculated or read from a data source? Are you going to make the user of your object store all these in local variables before they can construct your object?

The Example Code

The code sample with this article shows a very simple implementation of the Essence Pattern for a small class representing a contact. The Contact class has 5 properties, three of which are required (FirstName, LastName and Email), and two of which are optional (PhoneNumber and PostalAddress ).

The first thing we do is create the ContactEssence class as an internal class of the Contact class. The ContactEssence contains only the required properties for the contact (FirstName, LastName and Email), and allows read and write access to them all.

One of the two important methods of the ContaceEssence is the Validate method (shown below). This method essentially checks that all the required parameters are present and correct. Only when the Validate method returns true can the class advance to the next stage.

// Validates the essence fields.
private bool Validate()
{

  // Check we have a firstname
  if (mFirstName.Length == 0)
    return false;

  // ... and a last name
  if (mLastName.Length == 0)
    return false;

  // Check email exists and if it does, then check it's valid.
  if (mEmail.Length == 0)
    return false;
  else
  {
    // Use a regular expression to match an email address.
    System.Text.RegularExpressions.Regex emailReg = 
      new System.Text.RegularExpressions.Regex(
      @"^[\w-]+(?:\.[\w-]+)*@(?:[\w-]+\.)+[a-zA-Z]{2,7}$", 
      System.Text.RegularExpressions.RegexOptions.CultureInvariant);
    System.Text.RegularExpressions.MatchCollection results = 
      emailReg.Matches(mEmail, 0);

    // If we didn't get a mtach, fail the validation
    if (results.Count == 0)
      return false;
  }

  // Getting this far means validation is good
  return true;

}

The next stage is the creation of the real Contact class, which is done through a call to the ContactEssence.CreateContact method.

/// <summary>
/// Creates a <c>Contact</c> instance based on this essence.
/// </summary>
/// <returns>A new <c>Contact</c> 
/// if this <c>ContactEssence</c> is valid, 
/// otherwise a <c>null</c> reference.</returns>
public Contact CreateContact()
{
  if (this.Validate() == true)
    return new Contact(this);
    
  return null;
}

As you can see, if the ContactEssence is validated correctly, a Contact is returned.

The final part of the puzzle is the Contact class itself. The first area to look at are the constructors:

 // Private constructor can only be accessed by internal classes.
private Contact(ContactEssence xEssence) 
{
  // Copy required, immutable properties from essence
  mEmail = xEssence.Email;
  mFirstName = xEssence.FirstName;
  mLastName = xEssence.LastName; 
}

The constructor is private. ContactEssence is an internal class to the Contact, so it has access to the private constructor. This means that the Contact class can only be created by the ContactEssence class.

When the Contact is created from the ContactEssence, it simply copies all the required fields. Additional (optional) fields are left in their original initialised state. 

Finally, in the Contact class, the required fields are exposed as read-only properties, while the optional fields are read-write. This means that once the required fields are created, they cannot be changed.

So how do we use the Contact class?

The example code shows the role of the ContactEssence and the validation of required Contact properties:

// Cannot create contact directly this line 
// of code will create an error
//Essence.Contact c = new Contact(new Contact.ContactEssence());

// Create the essence
Contact.ContactEssence essence = new Contact.ContactEssence();

// Add the first required field
essence.Email = "me@mydomain.com";

// Cannot create Contact yet ...
Contact invalidContact = essence.CreateContact();
if (invalidContact == null)
  Console.WriteLine("Created NULL contact!");


// Fill in the rest of the required fields
essence.FirstName = "Dermot";
essence.LastName = "Gubbins";

// Try creating contact again
Contact validContact = essence.CreateContact();
if(validContact == null)
  Console.WriteLine("Oops! This should be valid!");
else
{
  // Add a phone number (optional)
  // but not an address.
  validContact.PhoneNumber = "(+44) 444 444";

  // Display the valid contact.
  Console.WriteLine("\nContact Created ...\n");
  Console.WriteLine(validContact.ToString());

}


Points of Interest

As explained in the original paper the Essence Pattern can be used in object creational patterns to create multiple valid classes by changing one or more of the required fields and then creating a new instance of the main class. Additionally, the Essence can also act as a builder class.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Dr Herbie
Team Leader
United Kingdom United Kingdom
After ten years studying biology and evolution, I threw it all away and became a fully paid up professional programmer. Since 1990 I have done C/C++ Windows 3.1 API, Pascal, Win32, MFC, OOP, C#, etc, etc.
 
PS. In the picture, I'm the one in blue. On the right.
 

Comments and Discussions

 
BugBroken Link? PinmemberDavid James21-Sep-13 15:14 
GeneralRe: Broken Link? PinmemberDr Herbie7-Oct-13 1:38 
GeneralVery useful article. Thanks a lot. Pinmemberjahfer18-Aug-13 5:45 
GeneralMy vote of 4 Pinmemberhichaeretaqua29-Jul-13 20:55 
BugMinor code improvment [modified] Pinmemberhichaeretaqua29-Jul-13 20:54 
GeneralRe: Minor code improvment PinmemberDr Herbie30-Jul-13 22:33 
QuestionQuestion PinmemberFatCatProgrammer8-Jul-13 5:45 
AnswerRe: Question PinmemberDr Herbie11-Jul-13 0:54 
QuestionDead links? Pinmembermrchief_200010-Jun-13 7:46 
GeneralMy vote of 4 PinmemberMattDavey8-Jun-13 13:43 
GeneralVery good. PinmemberPHS2418-Jun-13 10:43 
QuestionThe Essence Pattern in C# PinmemberFregate21-Dec-12 14:09 
AnswerRe: The Essence Pattern in C# PinmemberDr Herbie21-Dec-12 23:49 
GeneralRe: The Essence Pattern in C# Pinmemberbertkid8-Jun-13 13:57 
GeneralRe: The Essence Pattern in C# PinmemberJasmine250110-Jun-13 8:19 
GeneralRe: The Essence Pattern in C# PinmemberDr Herbie11-Jul-13 1:03 
GeneralRe: The Essence Pattern in C# PinmemberJasmine250112-Jul-13 5:08 
GeneralRe: The Essence Pattern in C# PinmemberDr Herbie12-Jul-13 5:59 
QuestionDo you see this as different from the Memento pattern? Pinmemberpanmanphil23-Jun-04 6:25 
AnswerRe: Do you see this as different from the Memento pattern? PinmemberDr Herbie23-Jun-04 21:38 
GeneralRe: Do you see this as different from the Memento pattern? Pinmemberpanmanphil24-Jun-04 4:58 
GeneralRe: Do you see this as different from the Memento pattern? PinmemberDr Herbie24-Jun-04 10:42 
GeneralRe: Do you see this as different from the Memento pattern? Pinmemberangrylala15-Mar-07 19:34 
GeneralMore like builder patther, Haha PinmemberHoly Joe18-Jun-04 17:38 
GeneralMore like builder patther, Haha PinmemberHoly Joe18-Jun-04 17:32 
GeneralRe: More like builder patther, Haha PinmemberDr Herbie20-Jun-04 23:11 
GeneralEase of understanding PinmemberClako0817-Jun-04 21:56 
GeneralRe: Ease of understanding PinmemberKlaus Luedenscheidt8-Jun-13 18:24 
GeneralDon't need the defautl constructor Pinmemberdgk9-Jun-04 12:27 
C# only produces a default constructor if no other constructor exists for the class.. so you shouldn't need to have private Contact().
 
Derek Kowald
dkowald@bigpond.net.au
GeneralRe: Don't need the defautl constructor PinmemberDr Herbie9-Jun-04 21:44 
GeneralRe: Don't need the defautl constructor PinmemberDr Herbie8-Jun-13 1:16 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web02 | 2.8.140902.1 | Last Updated 7 Oct 2013
Article Copyright 2004 by Dr Herbie
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid