Customizing Scope Builder

The Scope Builder method is a server method that is responsible for constructing a Scope Object. The purpose of the builder method is to construct a Scope Object using custom business data and business logic.

The Scope Builder uses a predefined method template. The template enables you to implement a Scope builder method properly.

The Scope Builder method uses the CSharp:Aras.Server.Core.Configurator template to define a class that inherits from the base abstract class. Here is the template for the Scope builder method:

namespace $(pkgname)

{
    public class $(clsname): ScopeBuilderBase
    {
        $(MethodCode)                                            
    }
}

Base abstract class:

public abstract class ScopeBuilderBase

public abstract class ScopeBuilderBase 

{ 

public Item ScopeItem { get; set; } 

public IServerConnection IomConnection { get; private set; } 

public void Init(Item scopeItem, IServerConnection iomConnection) {} 

public abstract Scope BuildScope(); 

public abstract string[] GetGuidsItemDependsOn(); 

public abstract List<string> GetItemTypeNamesItemDependsOn(); 

public abstract ArrayList GetCustomKey(); 

} 

The Scope Builder method is designed to provide a way for constructing a Scope object. The Scope Builder method also provides the built-in possibility to cache the Scope object.

The BuildScope method is responsible for constructing the Scope object instance.

The GetGuidsItemDependsOn, GetItemTypeNamesItemDependsOn, and GetCustomKey methods are used for Scope object caching and cache invalidation (see Caching section for more details).

The Effectivity Scope ItemType (effs_scope) is associated with the property builder_method. This property is a link to the Method Item. Effectivity Services automatically runs the linked builder method to get the Scope Object for the specified Effectivity Scope Item.

The Scope builder approach provides a built-in ability to cache a constructed Scope object. You can override the CustomKey function to store and retrieve the Scope object from the cache. This function returns the same ArrayList for each request for the same Scope object. To store different caches for different Scope objects, you can override the GetCustomKey function to return the different contents of the ArrayList:

public override ArrayList GetCustomKey()

public override ArrayList GetCustomKey() 

{ 

return new ArrayList { 

ScopeItem.getID(), 

}; 

} 

The Scope object can be invalidated automatically. Invalidation is triggered if at least one of the Items that the Scope object depends on changes. To do this, the system maintains a list of Item IDs and list of ItemTypes associated with these Items. Any time an item associated with a maintained ItemType and ID is changed, the system invalidates the found item.

The following collections must be created to make caching and invalidation possible:

• List of ItemType Names. This list contains the name of each Item Type that is used to build the Scope.

  Expand Collapse

  public override List<string> GetItemTypeNamesItemDependsOn() 
  
  { 
  
  return new List<string> { 
  
  "ItemType1", 
  
  "ItemType2", 
  
  "ItemType3", 
  
  "ItemType4" 
  
  }; 
  
  }

  Each Item Type in this list must be a poly source item for the ScopeCacheDependency Poly Item ItemType.

• List of Item IDs. This list contains the ID of each Item that is used to build the Scope.

  Expand Collapse

  public override string[] GetGuidsItemDependsOn() 
  
  { 
  
  return new string[] { 
  
  "item_id_Z4", 
  
  "item_id_Z5", 
  
  "item_id_Z6", 
  
  "item_id_Z7" 
  
  }; 
  
  } 

The effs_scope ItemType has a property named builder_method. This Item property is the link to a custom server method. The Builder method is a server method that is responsible for constructing a Scope object from custom business data.

This sample shows how to implement a Builder method that creates a static Scope object.

//MethodTemplateName=CSharp:Aras.Server.Core.Configurator;

public override Scope BuildScope()

{

    Scope builtScope = new Scope { Id = "item_id_scope", Name = "Model/SN Scope" };
                                            

    Variable int_variable = new Variable(DataType.Int) { Id = "item_id_serialNumber", Name = "Serial Number" };
                                            

    builtScope.VariableList.Add(int_variable);

    Aras.Server.Core.Configurator.Enum vEnum = new Aras.Server.Core.Configurator.Enum(DataType.String) { Id = "item_id_modelList", Name = "List of Models" };
                                            

vEnum.AddNamedConstant("item_id_modelX", "Model X", "Model X");
                                            

    vEnum.AddNamedConstant("item_id_modelY", "Model Y", "Model Y");
                                            

    vEnum.AddNamedConstant("item_id_modelZ", "Model Z", "Model Z");
                                            

    builtScope.VariableList.Add(new Variable(DataType.String) { Id = "item_id_model", Name = "Model", Enum = vEnum });
                                            

    return builtScope;
                                            

}

public override ArrayList GetCustomKey()

{

    return new ArrayList { "static_scope" };

}

public override string[] GetGuidsItemDependsOn()

{

    return new string[0];

}

public override List<string> GetItemTypeNamesItemDependsOn()

{

    return new List<string> { };

}

In this sample we have a static Scope object, so we can store it in the cache using a hardcoded ID as a key. The method result is cached with key “static_scope”.

The Scope has two Variables:

• [Serial Number] – data type of integer

• [Model] - data type of string, with list of values:

  • [Model X]
  • [Model Y]
  • [Model Z]

GetCustomKey, GetGuidsItemDependsOn, and GetItemTypeNamesItemDependsOn return either static or empty values for this sample static Scope Object. A Scope Object using real business data would return a feasible result.