Category Archives: ASNA Visual RPG

ASNA Visual RPG – Using The List Class with Generic Types

One of my most favorite classes in the .NET Framework has to be the List Class in the System.Collections.Generic namespace. More specifically, the generic list class as List(T) where T represents a generic type. According to Microsoft Developer Network (MSDN), the list class represents a strongly typed list of objects that can be accessed by index. The List class also provides methods to search, sort, and manipulate lists.

Collections Vs. Arrays

In many applications it is desirable to create and manage groups of related objects. The .NET Framework offers two ways to group objects;

  1. Creating arrays of objects
  2. Creating collections of objects

Arrays are most useful for creating and working with a fixed number of strongly-typed objects.

Collections provide a more flexible way to work with groups of objects. Unlike arrays, the group of objects you work with can grow and shrink dynamically as the needs of the application change.

If your collection contains elements of only one data type, you can use one of the classes in the System.Collections.Generic namespace. A generic collection enforces type safety so that no other data type can be added to it. When you retrieve an element from a generic collection, you do not have to determine its data type or convert it.

A collection is a class, so you must declare a new collection before you can add elements to it. Here is an example where I created a collection of Guitar objects, and used the add method of the List class, to load the collection with guitar objects;

Sorting
The List class has great sorting capabilities. The List Class contains a Sort method that is easy to use when the collection contains simple value types like strings or integers. However when the collection of objects are complex types, with multiple properties, sorting by the value of specific properties does get a little more complicated. Here is an example;

I created a class called guitar with multiple properties as follows;

Now, lets say I want to sort a collection of guitar objects by price. With the sort method of the List class I can delegate sorting by price to another class, whose sole purpose is to perform the sort function. I can accomplish this by inheriting from another class in the System.Collections namespace called Comparer and overriding its Compare method.
Here is the class I wrote for this purpose;

Anytime I need to sort a collection of guitars by price, I can simply pass an instance of the SortGuitarsByPrice class, as an argument to the List Sort method. Here is a code snippet;

Here is another example for sorting the collection of guitars by builder and model;

To Array

Converting the generic list of objects to a simple array of objects can be very handy in a number of situations. For example, a generic list of objects can be very powerful in a web service application. However, it may be necessary to convert the generic list to an array, in order to support Java and other types of web service consumers. To accomplish this the List class also contains a ToArray() method. Here’s a code snippet;

In my next post I’ll discuss the search capabilities of the List class. I’ll also cover the object-oriented design concept of delegation with an example that utilizes the FindAll() method of the list class.

Customized Configuration File Sections

The Microsoft .NET framework supports application figuration files for Windows applications, and web applications. An application configuration file is an XML document which contains settings specific to an application. The file contains configuration settings that the common language runtime can read. It can also contain settings that the application itself can read.

In this post I’ll show you how to create custom configuration file sections and how to access the configuration settings in an AVR.NET program. In order to demonstrate this concept, I have created an example AVR.NET application dealing with geometric shapes. In the application configuration file, I want to provide settings that an application administrator can manipulate, without modifying or rebuilding the application. For this example the settings will control the order in which geometric shapes will be drawn by the application.

Here is the XML of the App.config file

In this configuration example, everything is contained in the configuration section. Within the configSections element I describe my custom section with a sectionGroup element. On line 4 of the XML file I declare a sectionGroup named “shapeConfiguration” and a section named “shapeOrder”. I also specified that this section consists of name/value pairs by giving the type attribute a value of “System.Configuration.NameValueSectionHandler”. The type attribute is required, and specifies the name of the configuration section handler class, that handles the processing of the configuration settings that are in the section or element that is specified in the name attribute.

Accessing The Configuration File In AVR.NET

Accessing the configuration settings in an AVR.NET class will require two using statements;

The AVR.NET example will use the ConfigurationManager Class and the NameValueCollection class. The ConfigurationManager class will access the settings in the shapeOrder element of the configuration file. The NameValueCollection class will store the settings in memory as a collection of key/value pairs.

Here is the AVR.NET Code

The ConfigurationManager Class has a GetSection method that takes a string argument. Notice how the string is in file path notation for navigation to the shapeOrder element in the configuration file. The GetSection method returns a type of System.Object, so I used the AVR *As keyword to cast the name/value pairs of the shapeOrder element to a NameValueCollection. This type cast is also facilitated by the NameValueSectionHandler class I specified in the configuration file.

Now I can use the name value collection to assign a sorting rank to each instance of shape.

Here is the AVR.NET code

The NameValueCollection class has a Get method that accepts a string argument, which represents a key associated with a value in the collection. The Get method retrieves the value associated with the key. Notice how I used the Type class and the GetType method of each shape to form the key to get from the name value collection. This ensures that I retrieve the correct sort ranking associated with each shape object, no matter what the new instance of the shape class is called.

Each shape object has a RankOrder property which can be set based on the shapeOrder settings in the configuration file.

The GetShapesWithRank function in the above code snippet returns a generic list of shape objects. In my next post I’ll show you how to sort the generic list of shapes based on the RankOrder property of each shape.

Object Oriented Programming Stuff

Each shape class is derived from a shape base class which implements a shape interface. In the code snippet below, you can see that the IShape interface provides an abstraction for all shape entities referenced by the application. The interface defines only the essential elements of a shape;

  • Rank Order – a property that defines the rank of a shape in a hierarchy
  • Draw – a method for drawing a shape

The Shape class implements the IShape interface. You can see that the implementation of the Rank Order property is now concrete. However, the Draw method remains abstract and it is defined as a virtual method by the Modifier keyword with a value of *Overridable.

The concrete implementation of shape is completed in the Square class and the Circle class. They inherit from the Shape base class and override the Draw method with their own unique implementation. The Modifier keyword with a value of *Overrides facilitates the concrete implementation.

The following code sample demonstrates how well AVR.NET supports object oriented programming concepts like abstraction and inheritance. This design makes the AVR.NET code more flexible, reusable and maintainable. This design is much less vulnerable to the impact of ever changing requirements.

Here is the AVR.NET code where the shapes object model is defined

The complete source code of the application developed for this post can be downloaded here.

Overloading Methods with ASNA Visual RPG

Today I’ll be discussing another great feature of the ASNA Visual RPG (AVR) for .NET language. This feature is called method overloading and it provides two great benefits to your coding efforts;

  1. Simplifies complex coding requirements
  2. Enhances code performance

In AVR, method overloading simply means that functions in an AVR class can have the same name but with different parameters passed to it. The name of a function, combined with the set of parameters passed to it, form what is called the signature of the method. Here is an example of an overloaded method called GetItem, with three different signatures;

The AVR.NET compiler will compile all three methods to the intermediate language code as expected. One thing to remember, is that when it comes to overloading a method, the value returned by the method is not considered part of the method signature. As you can see in the second overloaded example of GetItem, it returns a different type from the other two overloaded methods.

Method overloading gives us the ability to provide multiple, unique implementations of the method, while at the same reducing the complexity of the code required to satisfy application requirements. Without the ability to overload the GetItem method, there could only be one implementation of the method. This single implementation would be much more complex, because it would have to perform tests, to determine what kind of argument was passed into each parameter and then branch to the appropriate code, based on the results of each test. All of this testing and branching degrades the runtime performance and efficiency of the method.

Method overloading also provides consumers of the GetItem method with the kind of flexibility and ease-of-use they have come to expect, when interfacing with other .NET classes and methods. The public interface of the ItemDbContext class illustrated above, will expose three methods for retrieving an item object, either with its associated order object or without the order. The consumer of these methods simply has to code the appropriate arguments when invoking the GetItem method and the compiler and common language runtime, will take care of calling the appropriate method. The consumer does not have to be concerned with how these methods are implemented. Their only concern is to satisfy the requirements of the public class interface.

When writing code in Visual Studio that will invoke the GetItem method, the IntelliSense feature of Visual Studio will automatically present each signature of GetItem to the programmer for them to choose from, as illustrated here.

Overloaded Method GetItem Signature 1

Overloaded Method GetItem Signature 1


Overloaded Method GetItem Signature 2

Overloaded Method GetItem Signature 2


Overloaded Method GetItem Signature 3

Overloaded Method GetItem Signature 3


Please feel free to share your thoughts on this post by clicking the leave reply above, or post your comments on Twitter #ASNAVisualRPG.

Below is the complete code for the ItemDbContext class used in the example above. The example application developed for this post, and all of the source code can be downloaded at the following link;

Method Overload Example

The sample database files, which are included with the example application download, can be imported into a local DataGate database on your PC.

Overriding Properties with ASNA Visual RPG (AVR)

In this post I’ll demonstrate how to override properties in an AVR Class.

The example application developed for this post, and all of the source code can be downloaded at the following link;

Property Override Example

The sample database files, which are included with the example application download, can be imported into a local DataGate database on your PC.

Lets start off by describing a business domain object model defined by the following classes.

  • Order – represents an order header with a collection of one-to-many line items
  • Item – represents a line item of an order

These are the same classes I used in my previous post on navigation properties in AVR.

Here are code snippets from these two classes;

Order Class

Item Class

In the business application I want to have two versions of the Item object.

  • Version One – The Order property of the Item is populated with the actual Order that the item belongs to. In this case the Item is a stand alone object.
  • Version Two – The item object is part of a collection of items that will populate the Items property of an Order. In this case it would be redundant to populate the Order property of each Item. I want the Order property of the Items to have an instance of the Order object with unpopulated properties

I solved this problem using the class inheritance and class member override capabilities in AVR. There are three features of the Item class that support class inheritance and class member overrides;

  1. The class declaration includes the Modifier keyword with a value of *Extensible as follows;
    BegClass Item Access(*Public) Modifier(*Extensible). This means the Item class can be inherited by sub-classes.
  2. The Order property is defined with the Modifier keyword with a value of *Overridable as follows;
    BegProp Order Type(Order) Access(*Public) Modifier(*Overridable). This means the Order property can be implemented in a completely different way by child-classes that are derived from the Item parent-class.
  3. The _order field that the Order property is based on is declared with the Access keyword with a value of *Protected a follows;
    DclFld _order Type(Order) Access(*protected). This means the _order field is only accessible by members of the Item class and any classes derived from the Item class.

Now I can create a sub-class of Item that overrides the Order property with a completely different implementation of the setter method. Here is the source code for a class that I called ItemOrder;

There are three elements of the ItemOrder class that support class inheritance and overriding class members;

  1. The class declaration includes the Extends keyword with a value of Item as follows;
    BegClass ItemOrder Access(*Public) Extends(Item). This means ItemOrder is derived from the parent class Item.
  2. The Order property is defined with the Modifier keyword with a value of *Overrides as follows;
    BegProp Order Type(Order) Access(*Public) Modifier(*Overrides). This means that when an instance of an Item object is based on the ItemOrder class, the implementation of the Order property will be overridden by ItemOrder class.
  3. All members of the Item base class, declared with the Access keyword value of *Protected, are accessible to the ItemOrder class. Remember the field _order was declared as protected in the Item base class.

In AVR, getter methods are coded inside the BegGet and EndGet keywords. Setter methods are coded inside the BegSet and EndSet keywords. Even though they are framed by some funny looking keywords, getter and setter methods work like any other method in AVR. In the Order property of the ItemOrder class, the setter method has a custom implementation for setting the value of the protected _order field. There are two lines of code in the setter method as follows;

The first line creates a new instance of the OrderDbContext class, which controls all data access to the Order Header file. The second line of code assigns a value to the _order field by invoking the GetOrder method of OrderDbContext. The GetOrder method expects one argument to be passed to it, the order number, which is the key to the Order Header file. The GetOrder method returns a fully populated Order object which is assigned to _order.

With AVR’s class inheritance and class member override capabilities, I now have two ways of implementing the Item object in the business domain object model.

  1. Stand-alone Item – an instance of the ItemOrder class
    In this implementation an order object, with a valid order number, is assigned to the Order property of the ItemOrder class. This invokes the setter method of the Order property of ItemOrder, which will assign an Order object populated from the database.
  2. An Items that is part of a collection of items – an instance of the Item class
    In this implementation an instance of the Order object is assigned to the Order property of the Item class. This invokes the setter method of the Order property of Item, which will assign an Order Object not populated from the database.

Navigation Properties in ASNA Visual RPG (AVR)

ASNA Visual RPG (AVR) is a .NET program language developed by ASNA. In this post I will cover the topic of navigation properties in an AVR class. In order to demonstrate navigation properties, I created a business domain object model consisting of two plain old runtime class objects POCO Classes. The first class represents an order header and the second class represents an order line item.

Here are come code snippets from both classes;

The Order Class

The Item Class

Please notice the Items (plural) property of the Order class. The Items property is a type of generic list consisting of Item objects. This forms a one-to-many relationship between an order and line items in the order. In this structure the Items property is also a navigation property. A navigation property is an optional property on an entity type that allows for navigation from one end of an association to the other end.

Notice also that the Item class has a navigation property of Order (singular). An Item can exist in only one order. The remote end point of an item is a single order, a multiplicity of one. The remote end point of an order is one-to-many items, a multiplicity of many.

Remember, the definition of a navigation property states that it is optional. For example, when an Order object is populated with data, it is usually desirable to also populate the Items property of the order, with a list of all the line Items associated with that order. On the other hand, when an Item is populated with data, it is not always desirable to populate the Order property of the Item, especially when the Item is part of a collection of Items in that Order. The multiplicity between Orders and Items would be repeated over and over again in the collection of order items. This would be very inefficient. However, when creating a single instance of an Item object, that is not part of a collection of items, it is desirable to populate the order property of the Item object. ASNA Visual RPG for .NET provides the flexibility needed to resolve a scenario like this, with an optional navigation property.

Here is an AVR function I called “PopulateItemEntity” that populates all of the properties of the Item class except the Order property. By not assigning a value to the Item.Order property, the setter method of the Order property is not invoked, leaving the property with a null value.

In case you are wondering why the Order property of the Item class has a modifier of *Overridable, don’t worry, I will cover that in my next post.