EDMA: Entorno de Desarrollo Modular y Abierto
Object Oriented and Componentware Framework

Copyright (C) 1998, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010, 2013
           by David Martínez Oliveira

See the end of the file for license conditions.
==========================================================================

Anchor Point Tests
------------------
This example demostrates basic use of anchor points in GNU/EDMA. 

The classes following classes from the GNU/EDMA test repository are used for these examples.

AP_TEST: Base class for the test
AP_TEST_SUBCLASS: An AP_TEST subclass
AP_TEST_SUBCLASS1: Another AP_TEST subclass

Additionally the classes DOG and GAP also from the GNU/EDMA test repository will also be used.

To compile and run examples in this directory:

     make -f ap_overwrite
     make -f ap_remove
     make -f ap_test
     make -f full_test

* Briefing

GNU/EDMA supports "uncoupled" inheritance in the sense that an object is created for each class involved in the inheritance relationships. Then, those objects are linked together to compose the full object associated to the derived class. 

Each link among those objects can be independently named and managed. These links are named "anchor_points". GNU/EDMA provides a rich set of operations to be performed on anchor points which are illustrated in the examples in this directory.

Paths along objects inheritance tree can be represented as a sequence of anchor points plus a minimal set of operators to indicate direction in the mentionated inheritance tree. These sequences are represented as strings and are generically named "classpaths". The examples in this directory makes extensive use of these "classpaths".

Examples in this directory shows how to work with GNU/EDMA anchor points.

- ap_test

This is the basic introductory test on anchor points. 
A complex object hierarchy is built using the "On-Demand Inheritance" feature of GNU/EDMA. This feature allows to change object hierarchy just accessing an object in the hierarchy as if it will be there. The system will link the missing object on demand and the primitive will continue. For example the primitive :

  edma_wprop3 (id, "AP_TEST@SUPER>Id", "Super 1");

will try to access a property named Id which is located "up" (direction of superclasses) in the inheritance hierarchy and assign it the value "Super 1". Since such an object does not exists the system will add a new superobject to the current one (id) of class AP_TEST and will link the original object id to the new object throughout the anchor point "SUPER". 

Summing up, primitive above will add superclass AP_TEST to object id and will allow access to this new superclass through classpaths of the form "SUPER>method" or "SUPER>property".

Note that the anchor point is only required on name clashing. Accessing to properties and methods on superclass not defined on current object is automatic.

Coming back to the example, a complex object hierarchy is built up combining several AP_TEST subobjects. 

Then a reference to the "top most" object is got using casting primitives and several examples of accessing specific items in the hierarchy using defined anchor points is shown. 

Several debugging commands are used to show graphically the built inheritance hierarchy:

edma_show_subobjects_down : Shows the hierarchy of subobjects of a given object
edma_show_superobjects_up : Shows the hierarchy of superobjects of a given object

Also note the detection of a inheritance cycle in the test and how to solve it renaming anchor points.

- ap_overwrite

overwriting 

This example show the capability of overwrite a given anchor point dynamically, using classpaths operations:

NEW_CLASS@!TARGET_ANCHOR_POINT[<>]Property|Method]

The character ! indicated to GNU/EDMA that the TARGET_ANCHOR_POINT in direction < or > in the class hierarchy should be overriden with an object of NEW_CLASS.

In the example an object of class AP_TEST is created and a new subclass of class GAP is attached to this object at anchor point INNER. Then this object (of class GAP) is overriden by a new object of class DOG.

Debug commands edma_obj_report, edma_subobjects_down and edma_subobjects_up are issued to show the result of the operation.

- ap_remove

This example how to remove anchor points of a running object. Classes with specific destructors are used to check that the objects are effectively destroyed.

Four tests are carried out by this program

Test1: An object with two superclasses is created. Both superclasses must be removed when object is destroyed

Test2: An object with two subclasses is created. Both subclasses must be removed when object is destroyed.

Test3: An object with superclasses and subclasses is created (Combination of Test1 and Test2)

Test4: Shared parent example. 

- full_test

Autoexplanatory
.

EDMA is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

EDMA is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with EDMA.  If not, see <http://www.gnu.org/licenses/>.
