3tier_banner.gif Main Index  PREV  NEXT

Valid HTML 4.01!   Valid CSS!

Methodology Overview

Main Points

Here is a list of the main points in this particular methodology:

  1. The Business Application Model (BAM) defines the physical database and is used by components in the business layer. These have the standard I/O commands in the <read>, <write>, and <delete> triggers.
  2. The Presentation Application Model (PAM) is not connected to any physical database and is used by components in the presentation layer. These have the standard I/O commands removed from the <read>, <write>, and <delete> triggers.
  3. All Document Type Definitions (DTDs) are defined in the PAM using entity and field names defined within the PAM, therefore PAM components should not require any mapping options.
  4. All mapping between PAM entities and BAM entities will be performed by session service components in the business layer.
  5. Generally each PAM entity will have a single DTD which will have the same name as the entity. This makes it easier for the generic software to identify which DTD to use for that entity. An entity may not have a DTD if it is included in the DTD for another entity.
  6. It is possible for an XML stream to contain data for more than one entity, but this will be built from a single DTD which will be named after the most significant entity.
  7. Although it is possible to construct DTDs from component definitions in this methodology they are constructed from entity definitions. Each entity will have its own DTD and its own session service, which means that if several components refer to the same entity they can share the same DTD and the same session service.
  8. It is possible for a component to contain several entities which have separate DTDs. In this case the data for those entities will have to be processed in separate operations.
  9. Some fields in the XML stream, such as those obtained from foreign entities, are optional and will not be retrieved unless required. The generic software identifies the fields that are required by the presentation layer component by using the $SELECTLIST function. For this to work the fields in the PAM entity cannot have their characteristics set to Non-database.
  10. For each entity in the PAM the identity of the associated session service will be defined in the entity properties as the Object Service Name. The generic software can thus identify which session service to use for that entity by using the $ENTINFO function. For this to work the PAM entity cannot have its DBMS path set to Not in database.
  11. All data validation will be defined within the business layer, not the presentation layer.
  12. When a presentation layer component has data that it wants validated it must activate an operation on a session service in the business layer. The data to be validated will be passed in an XML stream as a parameter on that operation.
  13. Operations exist which will allow this data validation to be performed at the <validate field>, <validate key>, <validate occurrence> as well as the <store> stages.
  14. All presentation layer components should be built from component templates as these already contain the necessary proc code to exchange data with the business layer.
  15. All session services should be built from component templates as these already contain the operations which are necessary to service the requirements of the presentation layer.
  16. When a presentation layer component requires data is does not read directly from the database - instead it will activate the GETDATA operation on a session service. This is handled by the global proc GET_DATA. This proc is used on an entity which must have a DTD available with the same name.
  17. If the DTD contains additional entities then the data for these entities will be supplied in the XML stream along with the data for the primary entity. These additional entities will not require their own DTDs unless they are to be processed independently.
  18. There are no stepped hitlists with XML streams as all the data is obtained from a single activation of the session service. If the number of occurrences needs to be restricted then it is possible to use the maxhits option which is available on the read command in the session service. Each presentation layer component must have a $MAXHITS$ component variable which can be used to supply this value.
  19. When a presentation layer component wants to write data is does not go directly to the database - instead it will activate the PUTDATA operation on a session service. This is handled by the global proc PUT_DATA which is used in the <store> trigger instead of the STORE command.
  20. In order to test for a database occurrence in a presentation layer component the function $DBOCC cannot be used as the occurrence is not connected to the database. You must use $OCCSTATUS = "est" instead, which relies on the processing information being present in the XML stream.

The GET_DATA proc

Method: call GET_DATA(entname, orderby, options)

Where: entnameis in the format 'entity.model'
  orderbyis in the format used by the orderby clause on the read command.
  optionsis in the format used by the options clause on the read command.

The GETDATA operation

Method: activate service.GETDATA(profile, selectlist, orderby, options, xmlstream)

Where: profileis used as the profile when retrieving occurrences from the BAM entity.
  selectlistis an indexed list of field names to be included in the output XML stream.
  orderbyis an indexed list of field names to be used as the sort sequence on the read command.
  optionsis an associative list of options for the read command. Currently only the maxhits=n option is used.
  xmlstreamreturns all the data retrieved by the session service.

The PUT_DATA proc

Method: call PUT_DATA(entname)

Where: entnameis in the format 'entity.model'

The PUTDATA operation

Method: activate service.PUTDATA(xmlstream)

Where: xmlstreamcontains the data which is obtained from and returned to the presentation layer component,

Changing the <read> trigger

The <read> trigger in each PAM entity should not contain the read command as the entity does not exist in any database. By default this trigger should contain the statement #include STD:READ_TRIGGER which takes care of this when compiled in a presentation layer component.

However, in my presentation layer components I still use the retrieve/e command to obtain data, so the contents of the <read> trigger for that entity needs to be changed to one of the following statements:

#include STD:READ_SINGLE - retrieve a single occurrence
This is equivalent to a retrieve/x statement in that it expects to retrieve a single occurrence, usually by its primary key. It will call the GET_DATA proc setting maxhits=1 and orderby="", and will error if no retrieve profile is provided. It will also error if more than 1 occurrence is retrieved. If a single occurrence is successfully retrieved it will automatically fire the <read> trigger of any inner entities defined within the component.
#include STD:READ_SEVERAL - retrieve any number of occurrences
This is equivalent to a retrieve/e or retrieve/a statement in that it will retrieve all those occurrences which match whatever retrieve profile has been supplied, including a null profile. It will call the GET_DATA proc setting maxhits=$MAXHITS$ and orderby=$ORDER_BY$. If occurrences from previous retrieve operations exist in the component then the results of the current retrieve will be appended to the existing contents and duplicate entries removed. This is similar to the standard processing for the retrieve/a command.

This results in a process flow diagram as shown in figure 1:

Figure 1 - how a presentation layer component receives data

section04_001.gif


Changing the <store> trigger

The <store> trigger for the component is inherited from the component template, so no further action need be taken. Instead of a STORE command this contains a call to the PUT_DATA proc, followed by a COMMIT or ROLLBACK as necessary.

If a STORE command were to be issued it would have no effect as the <write> and <delete> triggers of all the entities do not contain any code.

This results in a process flow diagram as shown in figure 2:

Figure 2 - how a presentation layer component stores data

section04_002.gif


Validation triggers

Validation at various levels is available provided that the following proc statements are inserted into the relevant triggers:

#include STD:LMK_TRIGGER - <leave modified key> trigger
This uses the RETRIEVE/O command to perform standard processing when leaving a key field which has been modified.
#include STD:VLDK_TRIGGER - <validate key> trigger
This will create an XML stream for the current occurrence using XMLSAVE/one, then activate the VALIDATEKEY operation on the session service in order to perform any validation for the current key.
#include STD:VLDO_TRIGGER - <validate occurrence> trigger
This will create an XML stream for the current occurrence using XMLSAVE/one, then activate the VALIDATE operation on the session service in order to perform any validation on the whole of this occurrence. If any fields are modified during this validation they are passed back in an associative list so that they can replace the current values.
#include STD:VLDF_TRIGGER - <validate field> trigger
This will create an XML stream for the current occurrence using XMLSAVE/one, then activate the VALIDATE operation on the session service in order to perform any validation for the current field only. If any fields are modified during this validation they are passed back in an associative list so that they can replace the current values.
call VERIFY_DELETE("entity") - <detail> or <exec> trigger
This will create an XML stream for the current occurrence using XMLSAVE/one, then activate the VERIFY_DELETE operation on the session service in order to check that it is safe to be deleted. If any occurrences exist on subordinate entities which are named in the local proc LP_DONT_DELETE then a negative status is returned.

copyright.gif http://www.tonymarston.net