AdFactum ObjectMapper .NET Blog

Official blog of the AdFactum ObjectMapper .NET

Attribute: [VirtualLink]

Posted by Gerhard Stephan on May 7th, 2007

The Virtual Link functionality is the most powerful feature the AdFactum ObjectMapper .NET offers.

What are Virtual Links?

Using Virtual Links you can implement objects that acts like database views. This enables you to join directly the values of your foreign key tables to your business entity.

What is the advantage?

The advantage is, that you don’t need to re-load Foreign Key Tables in order to get the display value of a foreign key. This saves you one SQL re-load per foreign key, and this without any further overhead.

If you are using the translation functionality of the AdFactum ObjectMapper .NET, the display values are already translated into your favoured language.

How can I use Virtual Links?

You can tag properties of your class with the [VirtualLink] attribute. Properties that are tagged with that attribute are only relevant when loading the entity. But they will be ignored when storing the entity to database.

        /// <summary>

        /// Department Key

        /// </summary>

        [PropertyName("DEPARTMENT")]

        [PropertyLength(4)]

        public string DepartmentKey

        {

            get { return departmentKey; }

            set { departmentKey = value; }

        }

 

        /// <summary>

        /// Department Text

        /// </summary>

        [VirtualLink(typeof(DepartmentText), "Value", "Key", "DepartmentKey")]

        public string DepartmentText

        {

            get { return departmentText; }

            set { departmentText = value; }

        }

 

In this example the Virtual Link would join the property "Key" of the class "DepartmentText" with the property "DepartmentKey" of the current class. As a result the property "DepartmentText" would be filled with the property "Value". And that represents the display value of the foreign key "DepartmentKey".

Because the VirtualLink represents a foreign key constraint, you don’t have to use the [ForeignKey] attribute on top of the property "Department Key". It would be a duplicate information.

And the best. It’s all working in background. You only have to load your business entity as usual.

How can I use Virtual Links for translation?

Imagine the property "DepartmentText" would be a translated value. E.g. different department descriptions for german and english. In that case you need to add a translation parameter which you can set when loading the business entity.

        public const string LOCALE_PARAMETER = "@LOCALE";

 

        /// <summary>

        /// Department Text

        /// </summary>

        [VirtualLink(typeof(DepartmentText), "Value", "Key", "DepartmentKey", "Locale", LOCALE_PARAMETER)]

        public string DepartmentText

        {

            get { return departmentText; }

            set { departmentText = value; }

        }

 

The property "Locale" of the class "DepartmentText" would hold the localization value, eg. "de-DE" or "en-GB". When loading the business entity, it’s necessary to set the global parameter in order to set the language for the virtual link.

     Hashtable globalParameter = new Hashtable();

     globalParameter[LOCALE_PARAMETER] = "de-DE"; // or another value like "en-GB"

 

     Company company = mapper.FlatLoad(typeof (Company), companyId, globalParameter) as Company;

 

The method "Load" of the AdFactum ObjectMapper .NET joins the global parameters, specified by the given hashtable, with the virtual links that are specified by the company business entity. The whole class DepartmentText would be implemented like:

    public class DepartmentText : ValueObject

    {

        public const int KEY_UNIQUE_GROUP = 1;

        public const int VALUE_UNIQUE_GROUP = 2;

 

        private string valueText;

        private string key;

        private string locale;

 

        [PropertyLength(4)]

        [Unique(KEY_UNIQUE_GROUP)]

        [Required]

        public string Key

        {

            get { return key; }

            set { key = value; }

        }

 

        [PropertyLength(512)]

        [Unique(VALUE_UNIQUE_GROUP)]

        public string Value

        {

            get { return valueText; }

            set { valueText = value; }

        }

 

        /// <summary>

        /// Language setting in standard .NET (e.g. en-US ; de-DE)

        /// </summary>

        [PropertyLength(5)]

        [Required]

        [Unique(KEY_UNIQUE_GROUP)]

        [Unique(VALUE_UNIQUE_GROUP)]

        public string Locale

        {

            get { return locale

            set { locale = value; }

        }

    }

 

What is the pitfall?

Like everything Virtual Links have their pitfalls too. If a class contains a lot of Virtual Links it can slowdown your database query. It depends on your database, your tables and the data within the tables to define how many virtual links are necessary to slowdown your query. Out of my experience I would say about 10 virtual links in one class is the limit. If you need more virtual links, I would load them in a second step after loading the plain object. In that case, you have to tag such empty properties with the attribute [Ignore]. If you have less than 10 virtual links within a class file, the Virtual Link functionality speed up your database query logic and saves you a lot of implementation work.

Conclusion: Virtual Links can be used for a very wide range of use cases. And it can save you a lot of coding time if you use them properly. 

Leave a Reply

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>