Vision Class: Entity

Entity Overview

The Entity class is an abstract class that is used to organize the classes in the hierarchy whose instances represent real-world entities such as companies, products, and industries. Each instance of these classes corresponds to a particular entity. For example, the instances of the class Company could represent individual corporate entities such as GM. Instances of the class Industry represent specific industries such as Autos.

The Entity class is a direct subclass of Object:

  Object
     |
     Entity
        |
        |-- Classification
        |
        |-- Currency
        |
        |-- Universe

Basic Access

Since it is useful to be able to address individual entities, entity instances are explicitly named. To avoid conflicting names (e.g., a company, security, and account all named GM), separate naming dictionaries are created for each entity subclass. For example, to access the object representing the company GM, you would execute the expression:

  Named Company GM

and to access the object representing the account GM, you would execute the expression:

  Named Account GM

The general form to get to a specific instance of an entity class is:

  Named entityClass entityId

where entityClass is the name of an entity class and entityId is the name of the actual instance. Note that the entityId must start with a letter or the _ character. If it does not, you should use the \ (escape) character to precede the name. For example, if the id for US currency is 1, the expression:

  Named Currency \1

can be used to access this object. An alternative to using the escape character for individual special characters is to identify the entire code as a string using the form:

  Named Currency at: "code" .

For example:

  Named Currency at: "1" .

Additional information on valid identifiers is available.

Popular Messages

All entities responds the the messages code and name. Initially, these values are the same. The value of name is usually changed from its initial value to a more descriptive name for the entity. An entity's name can be changed using the message setNameTo:. For example, the expression:

  Named Currency US setNameTo: "U.S. Dollar" ;

sets the value of the property name to the string supplied.

The properties shortName and sortCode are also initialized with the value of code. The shortName property is usually used to keep an abbreviated name for the entity that can be displayed in fewer characters than the full name. The sortCode property is usually used to store an alternative string used for sorting the entities in a class. These values can be set using the messages: setShortNameTo: and setSortCodeTo:. The property numericCode is defined for all entities. It is not initialized and can be used as needed to set a numeric value for instances that require one. The message setNumericCodeTo: can be used to set this value.

The message displayInfo is defined to display the entity's code and name followed by a carriage return. Some classes redefine the displayInfo message to display additional information. The message profile is defined to display a descriptive report for an entity. Some classes redefine this message to display additional information.

The message masterList returns the list of all non-default entities in a class. For example, to display the code and name for each Currency you could use:

     Currency masterList
     do: [ code print: 10 ; 
           name printNL ;
         ] ;

Aliases

Each entity instance can have more than one name. For example, your installation may have named the currency instance for US as "USD" and "US". The expressions:

  Named Currency USD

and

     Named Currency US

can both be used to return the currency instance that represents the US currency.

The identifiers USD and US are both aliases for the object that represents the US currency instance. An entity can have any number of aliases associated with it. All entities have at least one alias. By default, the value of the code property for an entity is used as the first alias created. Additional aliases can be added using the message addAlias:. For example, the alias USA can be added to this entity using:

  Named Currency US addAlias: "USA" ;

The expression:

  Named Currency US = Named Currency USA

would then return the value TRUE.

To display all the aliases associated with a specific entity you can display the list of strings stored in the aliases property. For example, to see the aliases defined for the US currency use:

  Named Currency US aliases do: [ printNL ] ;

To delete an alias use the message deleteAlias:. For example:

  Named Currency US deleteAlias: "USA" ;

deletes the USA alias for the US currency. To display the aliases available for each currency, use:

  Currency masterList sortUp: [ name ] .
  do: [ name print: 30 ; 
        aliases do: [ " / " print ; print ; ] ;
        newLine print ;
      ] ;

Creating Entity Subclasses

The expression:

  Entity createSubclass: "Company"

is used to create a new subclass of the Entity class that represents company objects. Once created, this class can be accessed using:

  Company

  Named Company Default

The variations of the createSubclass messages have been redefined at the Entity class to perform the following additional functions:

Create a new naming dictionary to name the instances of the new class.
Define the name Default in this naming dictionary to return the default instance of this new class.
Define the constant named at the new class to return the new class' naming dictionary. The expressions:
```
  Named Company
```
and
```
  Named Company Default named
```
and
```
  Company named
```
all return the naming dictionary for the Company class.

When a subclass of Entity is created, an initial instance representing the default instance for the class is also created. This instance is used by the Entity initialization messages to store values that are copied to new instances. This instance in all ways behaves like other instances in the class. To determine if an object is the default instance in its class, the isDefault and isntDefault messages are defined. Both return boolean (i.e., TRUE/FALSE) values. For example:

  Named Currency US isDefault

returns FALSE

  Named Currency US isntDefault

returns TRUE

  Named Currency Default isDefault

returns TRUE and

  Named Currency Default isntDefault

returns FALSE.

Note that the message instanceList returns the list of all instances in a class including the default instance and the message masterList returns the list of all instances in a class excluding the default instance.

Creating Entity Instances

The expression:

  Company createInstance: "XYZ"

is used to create a new instance of the Company class named XYZ. Once created, this instance can be accessed using:

  Named Company XYZ

The variations of the createInstance messages have been redefined at the Entity class to perform the following additional functions:

Add the instance's id to the class naming dictionary.
Initialize the values of name, shortName, and sortCode.
Initialize other default values defined for the class.

Several additional messages have been define at Entity which are used to initialize properties in the new instance. Initial values can automatically be copied from the default instance. For example, define the following:

  Company
      defineFixedProperty: 'property1' .
      defineFixedProperty: 'property2' ;

  Named Company Default :property1 <- 10 ;
  Named Company Default :property2 <- "xyz" ;

The following technique can be used to automatically initialize these values in new instances:

  Company createInitializationListFrom: NA ;
  Company updateInitializationListWith: [ :property1 ] ;
  Company updateInitializationListWith: [ :property2 ] ;

The first statement defines an empty initialization list. You could supply an existing list here instead. The next statements add the two properties to the automatic initialization process. When new instances are created, the values for these properties will be copied from the default instance. For example:

  Company createInstance: "GM"

will create a new company instance named GM and automatically copy the values for property1 and property2. The expression:

  Named Company GM property1

will return the value 10 and the expression:

  Named Company GM property2

will return the string "xyz".

Review

Suppose you needed to created several classes which represent simple tables of information that provide short and long names for various codes. For example, the class Rating could be defined to stores names for the ratings A through F and the class Status could be defined to store names for various status codes such as "Approved" and "Restricted".

To begin, create a subclass of Entity that will be the super class of all Table subclasses:

  Entity createSubclass: "Table";

Next, define the Rating class and its instances:

  Table createSubclass: "Rating" ;
  Rating createInstance: "A" . setNameTo: "Excellent" ;
  Rating createInstance: "B" . setNameTo: "Good" ;
  Rating createInstance: "C" . setNameTo: "Fair" ;
  Rating createInstance: "D" . setNameTo: "Poor" ;
  Rating createInstance: "F" . setNameTo: "Failure" ;

Finally, define the Status class and its instances:

  Table createSubclass: "Status" ;
  Status createInstance: "A" . setNameTo: "Approved" ;
  Status createInstance: "R" . setNameTo: "Restricted" ;
  Status createInstance: "D" . setNameTo: "Discard" ;

The A rating instance is accessed using:

  Named Rating A

The A status instance is accessed using:

  Named Status A

Notice that although both the classes have instances named A these objects have distinct access paths.

To display all the instances in the Rating class including the default use:

  Rating instanceList
     do: [ code print: 3 ; name printNL ] ;

To display all the instances in the Status class excluding the default use:

  Status masterList
     do: [ code print: 3 ; name printNL ] ;

To display all the subclasses of the Table class use:

  Table showInheritance

To create a status property at the Company class and assign the approved status for GM use:

  Company defineFixedProperty: 'status' ;
  Named Company GM :status <- Named Status A ;

Entity Overview

Basic Access

Popular Messages

Aliases

Creating Entity Subclasses

Creating Entity Instances

Review

Related Topics