Item Class Mappings

Item Class Mappings

Item classes can be scoped to a portal (currently in item class edit menu).

This means that their flows can only exist in the scope of that portal.

The Class Mappings Portal Data option provides an editor for you to assign mappings between higher classes and the private, scoped classes.

Class mapping specifies how external classes are mapped to internal classes in the module as items enter (and also the reverse when items leave the module).

The idea here is to provide a mechanism where a module (a portal) can be pasted into a model, carrying with it not just attributes and tables but also label lists and item classes (with their attributes) which it uses internally.

The goal is that the module can be pasted (singly or multiply) into another model without any of its internal code interfering with existing model code, or with multiple instances of itself.

Scoped item classes are an important part of this as even if common global class names were somehow agreed upon, different modules would need different attributes and use the same named attribute differently. By scoping, this usage is kept local and isolated.

To work within an existing model, a mechanism is required to "map" the existing, outside or "external" classes in a model to the private, local or "internal" classes in the module being pasted in. This is provided by the "Class Mapper". The class mapper specifies how external classes are mapped to internal classes in the module as items enter (and also the reverse when items leave the module).

This keeps the portal self contained. Copying the portal will create a separate item class for the copy and the 2 will be isolated from each other.

Scoped item classes will have access to scoped label lists (which global item classes do not) further encouraging modularity.

Getting Items into Portals

Items can enter a portal in the following ways:

1. via flows
   
2. via a spatial link/track
   
3. messaging to the portal
   
4. via a broadcast
   
5. via a wormhole
   
6. via a Throw Exit (Place Item into Object, mode available in Application Panels).
   

Methods 1 and 2 and 3 are currently mapped by the class mapper. As the item enters portal it gets "translated" to an internal item for the portal.

As it leaves, it gets translated back to the external item.

To enable mapping for a message item you need to manually set up the mapping as the platform doesn't prompt to do it automatically as when you are flow editing.

Method 4 should already occur due to the existing broadcast mechanism for class translation (see below though).

5 and 6 wont be supported for modules as they are not modular by nature.

Translation of Items and Attributes

The translation process involes copying matching item attributes (see below) as occurs in "tupling" with tables and between different item classes.

This applies to both item attributes and item table references. Matching names get mapped unless the INTERNAL item class has the "private" option set for the attribute/table reference.

An external item survives while an internal item is inside a portal where a mapping has occurred. It gets put "aside" until the item leaves the portal whereupon its attributes are updated.

This whole process works both in lookahead (looking into the module/portal to determine if it has capacity, the module looking "out" to see if there is capacity for an item that wants to leave) and "lookthrough" (looking right through a module with no capacity to see if what is on the other side has capacity for an item to move. It should also work recursively (modules inside modules).

Private item attribute option

If a subsystem contains a class with private item attributes, these attributes are not set or returned to the "external' item class which is being mapping into or out of the subsystem.

All other item attributes with matching names are copied when translating external to internal and coming out again.

Reporting Mappings

A "Report" button in the class mapping overview will display a summary of the attributes/table references that the internal class is allowing to be tupled and indicating which ones are actually matched by the external class.

Current Limitations

Carried items to be transferred between the external and internal items on the way in/out.

The ability for a module to produce an item without one entering and the class mapping to properly occur as the item leaves the module.

Table references to be treated similar to item attributes as described above

If a class is mapped, the module is not able to assign routes/link targets for the external item. A mechanism to enable this needs to be developed (though this raises the issue - how does the module know about the external network)

A mechanism to "insulate" modules from scoped broadcasts is intended. This will prevent a module having its internals activated by modeller broadcasts in the model it is pasted into unless those broadcasts are specifically targetted at it.

Class Mappings and Modules

When a module (portal with "module" option on) which has internal classes is included in a flow, PL will check if there is a mapping for the current class being edited. If there isn't it will offer to allow an internal class to be selected. If the module only has one class, then PL will create a mapping automatically without prompting the user. This simplifies the use of modules with a single scoped class within them.