Class Pzl

Автор: Виктор Юхтенко

Purpose

The destination of the class Pzl is to support the use of pzl-components and to get information regarding the status of the pzl-system. The class Pzl must be included into any project, which deals with pzl-components. Such a project may be both the pzl-container and the project generating the executable application.

The implementation of the class Pzl contained:

• if to pzl-container (DLL-container) - at the pzlContainer_YY.lib static library
• if to main executable application - at pzlPort_XX.lib static library

where YY and XX - appropriate license levels.

Any class, which included into the project and which uses the pzl-technology may use the predicates of the class Pzl.

The list of domains used by the class

pzlComponentsRegisterFileName_D	The status of the file-registry of the given application
pzlContainerContentInfo_D	Information regarding the components of the pzl-container
pzlComponentInfo_D	The desriptor of the pzl-component
entityUID_D	The identifier of the entity

The list of predicates of the class Pzl

The list of predicates of the class Pzl is divided on sublists (the standard VIP-predicate classInfo is not considered):

• Container Information

This group is not for use in the ordinary programming. It serves to get the information regardng the container, such as the level of the license, information regarding components etc..

• Component handling

This group of predicates gives the possibility to create instances of components using their identifiers and nicnames.<br\>This group also contains the predicate to assign the standard output flow. If you use the standard style of VIP programming, then you use this set of predicates rare.

• Object registration

This group of predicates is frequently used one. It serves to register active objects and to get information regarding currently active objects. The object registry is accessible from the any part of the application based on the pzl-technology.

• Special predicates

The special predicates used by special tools. Not for use by end users.

classInfo. Get information about the version and the date of the latest modification of the class Pzl

Container Information

getContainerName:()->string ThisContainerName procedure (). Get the name of the file-container, where the given component is placed

getContainerVersion:()->string ThisContainerVersion procedure (). Get the identifier of the version of the container, where the given component is placed

getLicenseLevel:()->string PZLUserLicenseLevel procedure (). Get the name of the license level of the container, where the given component is placed

getComponentRegisterFileName:()->pzlDomains::pzlComponentsRegisterFileName_D ComponentRegisterFileName procedure (). Get the name of the component registry file, assigned to the current application

getContainerContentList:(string PZLContainerFileName)->pzlDomains::pzlContainerContentInfo_D ContentInfo procedure (i). Get the list of components, contained in the container with the given name

Component handling

setStdOutputStream:(outputStream OutputStream). Assign the specified OutputStream as the standard output stream for all components used by the given application

newByName:(string Name,object InObject)->object OutObject procedure (i,i). Create new object using the name of the component

newByID:(pzlDomains::entityUID_D,object InObject)->object OutObject. Create new object using the component identifier

Object registration

register:(string ObjectName,object Object) procedure (i,i). Register the Object using the given ObjectName (single registration)

registerMulti:(string ObjectName,object Object) procedure (i,i). Register the Object using the given ObjectName ObjectName (possible multiple registration)

getObjectByName_nd:(string ObjectName)->object Object nondeterm (i). Get the Object, registered previously using the given name ObjectName

getNameByObject_nd:(object Object)->string ObjectNameLow nondeterm (i). Get the ObjectNames for given Object

getNameAndObject_nd:(string ObjectName,object Object) nondeterm (o,o). Gen Object and it's assosiated name ObjectName

unRegister:(string ObjectName,object Object) procedure (i,i). Deregister the given Object with the given ObjectName

unRegisterByName:(string ObjectName) procedure (i). Deregister all abjects with the given name ObjectName

unRegisterByObject:(object Object) procedure (i). Deregister given object Object

unRegisterAll:() procedure (). Deregister all objects (clear the object registry)

Special predicates. Not documented

releaseInactiveContainers:().

getContainerActivity_nd:(string FileName,unsigned RefCounter) nondeterm (o,o).

getContainerToBeUnloaded_nd:(string FileName) nondeterm (o).

subscribe:(notificationAgency::notificationListener NotificationListener).

unSubscribe:(notificationAgency::notificationListener NotificationListener).

newInstance:().

release:().

Other resources used

• The class Pzl uses the pzlPort_XX.lib library, if the target is executable application (.EXE). Class Pzl uses pzlContainer_XX library, if the target is Dll-contaner (DLL). Actually these libraries contain the class Pzl implementation.
• It is necessary to have the package pzlConfig.

Domain details

pzlDomains::pzlComponentsRegisterFileName_D

The status of the component registry file

pzlComponentsRegisterFileName_D=
  pzlRegistryFileName(string FileName);
  pzlRegistryFileNameWronglyDefined;
  pzlRegistryFileNameNotInUse.

The domain pzlComponentsRegisterFileName_D defines one of the statuses of the component registry file for the given applicaion.

pzlRegistryFileName(string FileName)
The file FileName assigned as the component registry file.

pzlRegistryFileNameWronglyDefined
The component registry file wrongly defined. Possibly the file not existed, when assignment was done.

pzlRegistryFileNameNotInUse
There was no component registry file assignment.

pzlDomains::entityUID_D

The domain entityUID_D helps to identify different entities. It may have two variants:

• simple form str(string)
• complex form uid(...), which corresponds to the nativeGuid of the Visual Prolog, which in turn corresponds to the GUID of the Microsoft company.

The simple form doesn’t provide the uniqueness of the identifiers. It is recommended to use in examples and in the exercises.

The complex form provides the uniqueness of the identifiers. It is not convenient to remember and to manipulate.

domains
  entityUID_D =
    str(string StringIdentifier);
    uid(
       core::unsigned32 Unsigned,
       core::unsigned16 Short1,
       core::unsigned16 Short2,
       core::unsigned8 Byte1,
       core::unsigned8 Byte2,
       core::unsigned8 Byte3,
       core::unsigned8 Byte4,
       core::unsigned8 Byte5,
       core::unsigned8 Byte6,
       core::unsigned8 Byte7,
       core::unsigned8 Byte8
       ).

pzlDomains::pzlContainerContentInfo_D, pzlDomains::pzlComponentInfo_D

The Domain pzlContainerContentInfo_D used to describe the content of the pzl-containers. It is represented as the list of descriptions of components.

pzlContainerContentInfo_D = pzlComponentInfo_D*.

Each element of the list is the term of the domain pzlComponentInfo_D

pzlComponentInfo_D=pzlComponentInfo
  (
  string Alias,
  entityUID_D ComponentID,
  booleanInt Runable,
  core::namedValue_List UserDefinedInfo
  )

Here

• Alias – the string name of the component,
• ComponentID – component identifier
• Runable – Boolean flag, which shows whether the component can be called and can run independently.
• UserDefinedInfo – the list of parameters interpreted by the developer of the component.

Predicate details

pzl::getContainerName/0

getContainerName:()->string ThisContainerName procedure ().

Get the name of the file-container, where the given component is placed

Description

Returnes the name (full path) of the file where the given pzl-component is placed.

Exceptions

No

Example

...
ContainerName=pzl::getContainerName(),
stdIO::writef("Component /"MyComponent/" placed at container %",ContainerName),
...

pzl::getContainerVersion/0

getContainerVersion:()->string ThisContainerVersion procedure ()

Get the identifier of the container version, where the given component is placed

Description

Returnes the version of the pzl-container, where the given component placed. The version of the container declared as the value of the string type (string). It is defined by the constant "pzlContainerVersion_C" in the file PzlConfig.i of the container project.

Exceptions

No

Example

If the file PzlConfig.i of the given container contains the constant declaration

constants
  pzlContainerVersion_C="1.0;001".

then the following code gets the version No of the given container

...
ContainerVersion=pzl::getContainerVersion(),
stdIO::writef("Container Version - %",ContainerVersion),
...

It will be sent to the output stream: "Container version - 1.0;001"

pzl::getLicenseLevel/0

getLicenseLevel:()->string PZLUserLicenseLevel procedure ()

Get license level of the container, where the given component is placed

Description

Returnes the license level of the container, where the given pzl-component is placed. The license level of the container is the one assigned to the container by the publisher of the container. It is defined by the appropriate library. Thus the library defines the license level of the pzl-container. The license level may have on of the following string values:

• ”Public”
• ”Commercial”
• ”Exclusive”
• ”SuperExclusive”
• ”Unknown”

If the pzl-component placed in the container of the main application, then the license level of the main application will be returned.

Exceptions

No

Example

The code below gets the license level of the current container (and the license level of the current component)

...
LicenseLevel=pzl::getLicenseLevel(),
stdIO::writef("The license level of the current container is - %",LicenseLevel),
...

pzl::getComponentRegisterFileName/0

getComponentRegisterFileName:()->pzlDomains::pzlComponentsRegisterFileName_D ComponentRegisterFileName procedure ().

Get the status of the component registry file of the given application

Description

Returns one of the following terms, indicating the status of the component registry file of the current application:

• pzlRegistryFileName(FileName) - FileName defines the full name of the assigned file.
• pzlRegistryFileNameWronglyDefined – the registry file is wrongly defined
• pzlRegistryFileNameNotInUse – the registry file is not in use

Exceptions

No

Example

...
RegisterStatus=pzl::getComponentRegisterFileName(),
(
   RegisterStatus=pzlDomains::pzlRegistryFileName(FileName),
   stdio::writef("The registry file - %\n",FileName)
or
   RegisterStatus=pzlDomains::pzlRegistryFileNameNotInUse,
   stdio::write("The registry file is not in use \n")
or
   RegisterStatus=pzlDomains::pzlRegistryFileNameWronglyDefined,
   stdio::write("The registry file not found while assignment\n")
),
…

pzl::getContainerContentList/1

getContainerContentList:(string PZLContainerFileName)
  ->pzlDomains::pzlContainerContentInfo_D ContentInfo procedure (i).

Get the list of components, contained in the container with the given name

Description

The predicate returns the list of descriptions of components, which are placed in the container with the given name. It is not necessary that the components of the container to be registered in the pzl-system.

To get the list of components of the main application it must be used:

• "pzlPort" or
• The name (full or relative) of the executable file of the main application

Each element of the returned list is the term of the domain pzlComponentInfo_D

pzlComponentInfo_D=pzlComponentInfo
  (
  string Alias,
  entityUID_D ComponentID,
  booleanInt Runable,
  core::namedValue_List UserDefinedInfo
  )

Where

• Alias – string name of the component
• ComponentID – the identifier of the component
• Runable – Boolean flag, which indicates the possibility to be invoked independently
• UserDefinedInfo – the list of parameters, defined by the developer of the component.

Exceptions

The following exceptions are generated if

• the file-container not found
• the dll container can not be loaded
• the version of the dll-container doesn’t correspond to the version of the main application
• the license level of the main application is lower then the license level of the container
• the Dll-container doesn’t correspond to the pzl-agreements

Example

In the example below by the event ‘’’onShowComponentsDescription’’’ (pushbutton on the pane) the information regarding the container "..\\VPPuzzle\\Examples\\PZL\\HelloWorld.pzl" components is requested. This info is sent to the standard output stream

predicates
  onShowComponentsDescription : button::clickResponder.
clauses
  onShowComponentsDescription(_Source) = button::defaultAction:-
    DataList=pzl::getContainerContentList("..\\VPPuzzle\\Examples\\PZL\\HelloWorld.pzl"),
    foreach Element=list::getMember_nd(DataList) do
      stdio::writef("Element=%\n",Element)
    end foreach.

For this concrete container we will get

Element=pzlcomponentinfo("HelloWorld",str("HelloWorld"),1,[])

And for the container FactDemo_UI the same code

clauses
  onShowComponentsDescription(_Source) = button::defaultAction:-
    DataList=pzl::getContainerContentList("..\\VPPuzzle\\Examples\\PZL\\FactDemo_UI.pzl"),
    foreach Element=list::getMember_nd(DataList) do
      stdio::writef("Element=%\n",Element)
    end foreach.

returns (the formatting done manually):

Data:=pzlcomponentinfo(
  "FactDemo",
   str("Fact_UI"),
   1,
   [
   namedvalue("CodeExporter",string("FactDemoExporter")),
   namedvalue("ProxyExporter",string("FactDemoExporter"))
   ]
   )

pzl::newByID/2

newByID:(pzlDomains::entityUID_D ComponentID,object InObject)->object OutObject.

Create new object, using the unique component identifier

Description

Creates the new object of the pzl-component, which is registered with the identifier ComponentID.

Pzl-component with the identifier ComponentID must be registered in one of registration places – or in the Windows registry, or in the component registration file, created by the User (*.pzr).

The reference to the object InObject may be the reference to any object. if it supposed to make a call to that object InObject, then the component, which is used to create the object, must know the domain-interface of the object InObject.

The returned object Object is the reference to the created object. To use the predicate of the created object the object OutObject must be converted to the appropriate domain-interface.

Exceptions

If pzl-system can not create the instance of the component, then the exception will be generated by possible reasons:

1. pzl-system has no access to the component registry.
2. pzl-component with the given name not found in the component registry.
3. pzl-container, which contains the given component can not be loaded
4. pzl-container and the main application are incompatible
5. main application has the license level lower, then the license level of the pzl-container
6. the pzl-container doesn’t contain the component with the given ID
7. the constructor of the given component can not create the instance of the component

If the exception occurred by the reasons 3,4 и 5, then the pzl-system tries to unload the container. If this is impossible, then the new exception generated.

In the exception stack the last description contains the text:

”newByID failured for the Component with the ID <ID>"

Example

The component registed with the ID str(“MyComponent”) supports the interface iMyComponent, where the predicate myPredicate(...) is defined.

...
Object=newByID(str("MyComponent"),This),
MyComponentInstance=tryConvert(iMyComponent,Object),
MyComponentInstance:myPredicate(...),
...

In case if the unique UID is used, then the call will look like

...
Object=newByID(uid(0xDF29A0EA,0x7BA6,0x4425,0x8D,0x88,0x2B,0x3C,0x6F,0xDA,0x0C,0x73),This),
MyComponentInstance=tryConvert(iMyComponent,Object),
MyComponentInstance:myPredicate(...),
...

pzl::newByName/2

newByName:(string Name,object InObject)->object OutObject procedure (i,i)

Create new object, using the string name of the component </vip>

Description

Creates the new object of the pzl-component, registered with the name Name.

The pzl-component named Name must be registered in one of available places of the registration – in the Windows registry or in the user’s component registry file (*.pzr).

The object InObject may be any object, which has the sense in the called object. If it is supposed that the component will have any call to the InObject , then the component must know the domain-interface of the object InObject.

The returned object OutObject is the result of the operation. To make a call of any predicate of the object OutObject it must be done the conversion of the object to the domain defined by the appropriate interface of that class.

Exceptions

There may be exceptions generated:

1. pzl-system has no access to the component registry.
2. pzl-component with the given name not found in the component registry.
3. pzl-container, which contains the given component, can not be loaded
4. pzl-container and the main application are incompatible
5. main application has the license level lower, then the license level of the pzl-container
6. the pzl-container doesn’t contain the component with the given Name
7. the constructor of the given component can not create the instance of the component

If the exception occurred by the reasons 3,4 и 5, then the pzl-system tries to unload the container. If this is impossible, then the new exception generated.

In the exception stack the last description contains the text:

”newByName failured for the Component with the name <Name>"

Example

The component MyComponent supports the interface iMyComponent. Predicate myPredicate(...) is the part of the interface iMyComponent.

...
Object=newByName("MyComponent",This),
MyComponentInstance=tryConvert(iMyComponent,Object),
MyComponentInstance:myPredicate(...),
...

pzl::setStdOutputStream/1

setStdOutputStream:(outputStream OutputStream).

Assign the given output Stream as the standard output stream for all components used by this application

Description

Any component may assign the existing output stream as the standard output stream. If this happens, then all components, participating in the given application begin to use this output stream as the standard one.

In that case if one component assigned the output stream ‘’’A’’’ as the standard one, and some other component after that assigned the output stream ‘’’B’’’ as the standard one, then when the first component becomes active again it will use the output stream ‘’’B’’’ as the standard one.

If the first component anyway needs the output stream ‘’’A’’’ then it must reassign the output string according to it’s needs.

Exceptions

No

Example

The next peace of code creates the new output stream and assigns it as the standard output stream

...
MessageStream=outputStream_message ::new(),
pzl::setStdOutputStream(MessageStream),
...

pzl::register/2

register:(string ObjectName,object Object) procedure (i,i).

Register the object using the given name ObjectName (single registration)

Description

Gives the possibility to register object in the global for the current application run object registry. Any object of the Visual Prolog may be registered in the global registry, using the string name.

Predicate register(), gets the object Object and the string name ObjectName, choosen by programmer and put this object to the registry with this name.

The only one object with that name can be placed to the registry.

If there is the object with the same (case insensitive) name in the registry, then the exception is generated. The same object may be placed to the object registry using different names.

Exceptions

If object registry already contains the object with the same name.

Example

The following example shows the initialization of the pzl-system and the creation and the registration of the TaskWindow. The TaskWindow can be created and registered only once. As the string name it is used the value, which all components (and other classes of the application) must know.

...
run():-
  pzlPort::init(),
  TaskWindow = taskWindow::new(),
  pzl::register(studioConstants::studioTaskWindow_C,TaskWindow),
  TaskWindow:addShowListener(onShow),
  TaskWindow:addMenuItemListener(resourceIdentifiers::id_file_run_profile,onRunProfile),
  TaskWindow:show().

It is known from the context of the program, that here in that place of the code the TaskWindow is created first time, so we do not use the exception handling here.

In the example below the exception handling is used, because of there is the possibility to try to create the form more that once.

It is supposed, that the variable TaskWindow previously have gotten the value and can be used as the parent window

...
TicketForm = ticketForm::new(),
trap(pzl::register("Ticket Form",TicketForm ),Error,ExceptionHandler(Error,"Ticket form ")),
TicketForm :show(TaskWindow).
...

pzl::registerMulti/2

registerMulti:(string ObjectName,object Object) procedure (i,i).

Register the object using the given name ObjectName (possibly multiple registrations)

Description

Gives the possibility to register object in the global for the current application run object registry. Any object of the Visual Prolog may be registered in the global registry, using the string name.

Predicate registerMulti(…), gets the object Object and the string name ObjectName, chosen by programmer and put this object to the registry with this name.

Predicate registerMulti(...) places the only one object Object with the given name. If the same object with the same name exists in the registry already, then no execution performed.

Many object with the same name may be placed to the registry using the registryMulti(…) predicate.

Exceptions

No

Example

In the following example we register the Form Editor, which may be created many times. Each time the form is registered with the same name. The programmer is responsible for the resolving collisions between objects, when he gets the object from the registry, using the name.

...
FormEditorObject=formEditor::new(This),
pzl::registerMulti("FromEditor ",FormEditorObject),
FormEditorObject:show(TaskWindow),
...

pzl::getObjectByName_nd/1

getObjectByName_nd:(string ObjectName)->object Object nondeterm (i).

Get object registered with the name ObjectName

Description

The predicate getObjectByName_nd(...) returns in the nondeterm mode all objects, registered before in the object registry with the name ObjectName. If the object hot found in the registry, then the predicate fails.

Exceptions

No

Example

See example below:

The first clause checks whether the object with the name componentAlias_C stored in the object registry before. If object registered before, then it is converted to the domain messageForm and the focus on the object is set. Predicate’s execution complete.

The second clause remembers the current output stream, than the new instance of the class messageForm created. It gets the stored in the object registry ApplicationWindow object as the input parameter. The newly created object stored in the object registry with the name componentAlias_C.

The predicate getApplicationWindow() restores the reference to the object ApplicationWindow from the object registry. If the object with the name ApplicationWindow not created (object not found in the object registry), then exception generated.

createMessageForm(_InText):-
  Object=pzl::getObjectByName_nd(componentAlias_C),
  LiveObject=convert(messageForm,Object),
  LiveObject:setFocus(),
  !.
createMessageForm(_UserText):-
  defaultOutputStream_V:=stdio::getOutputStream(),
  ApplicationWindow=getApplicationWindow(),
  messageForm_V:=messageForm::display(ApplicationWindow),
  OutputStream=messageForm_V:getOutputStream(),
  pzl::setStdOutputStream(OutputStream),
  pzl::register(componentAlias_C,This),
  messageForm_V:setCloseResponder(onMessageFormCloseRequest),
  messageForm_V:addDestroyListener(onDestroy).
 
predicates
  getApplicationWindow:()->applicationWindow.
clauses
  getApplicationWindow()=convert(applicationWindow,TaskWindowObj):-
    TaskWindowObj=pzl::getObjectByName_nd(studioConstants::studioTaskWindow_C),
    !.
  getApplicationWindow()=_Win:-
    common_Exception::raise_User(classInfo,predicate_FullName(),"InternalError: Unexpected Alternative").

pzl::getNameByObject_nd/1

getNameByObject_nd:(object Object)->string ObjectNameLow nondeterm (i).

Get registration name of the registered object

Description

The predicate returns in the nondeterm mode all names, which was assigned to the given object while the registrations. If no object found in the object registry, then the predicate fails.

Exceptions

No

Example

The following piece of code outputs the list of names, which the current object has in the object registry

...
if not(_RegistryName=pzl::getNameByObject_nd(This)) then
  stdio::writef("The current object % is not registered",toString(This))
else
  stdio::write("The list of the names for the current object %\n",This),
  foreach RegistryName=pzl::getNameByObject_nd(This) do
    stdio::writef("Name -> %\n",RegistryName)
  end foreach
endif,
...

pzl::getNameAndObject_nd/2

getNameAndObject_nd:(string ObjectName,object Object) nondeterm (o,o).

Get the name of the object and the object

Description

Predicate returns in the nondeterm mode all objects and their names, which was registered before. If no object found in the registry, then the predicate fails.

Exceptions

No

Example

The following example outputs all objects registered in the object registry and their names,

...
if not(pzl::getNameAndObject_nd(ObjectName,Object)) then
  stdio::write("There is no objects in the registry\n")
else
  stdio::write("The list of the registered objects:\n"),
  foreach pzl::getNameAndObject_nd(ObjectName,Object) do
    stdio::writef("Name: % ;Object: %\n",ObjectName,toString(Object))
  end foreach
endif,
...

pzl::unRegister/2

unRegister:(string ObjectName,object Object) procedure (i,i).

Remove the registration of the object Object with the registration name ObjectName

Description

The predicate removes from the registry object Object with the registration name ObjectName. If no object Object with the given name ObjectName is found in the registry, then predicate succeeds anyway.

Exceptions

No

Example

In the example below fist makes the try to find the object corresponding to the main application window (TaskWindow), and then the found object removed from the object registry

...
if (TaskWindowObject=pzl::getObjectByName_nd("TaskWindow"),!) then
  pzl::unRegister("TaskWindow",TaskWindowObject)
end if,
...

pzl::unRegisterByName/1

unRegisterByName:(string ObjectName) procedure (i).

Remove the registration of all objects registered in the object registry with the given name ObjectName

Description

The predicate removes from the object registry all objects registered with the given name ObjectName. If there are no objects in the object registry with the given name, then predicate succeeds anyway.

Exceptions

No

Example

In the example below the objects registered with the name “TaskWindow” removed from the object registry.

...
pzl::unRegisterByName("TaskWindow"),
...

pzl::unRegisterByObject/1

unRegisterByObject:(object Object) procedure (i).

Deregister the object Object

Description

Predicate deregisters all registrations of the object Object in the object registry. If no object Object registered in the object registry, then the predicate succeeds anyway.

Exceptions

No

Example

In the example below the object MessageForm ends the run and:

• stores if’s current status
• removes itself from the object registry
• restores the status of the output stream, which existed before the creation of the object MessageForm

...
predicates
  onDestroy:window::destroyListener.
clauses
  onDestroy(_Source):-
    setRestoreData(componentAlias_C,[],[]),
    pzl::unRegisterByObject(This), % <--- removes the self registration
    pzl::setStdOutputStream(defaultOutputStream_V),
    messageForm_V:removeDestroyListener(onDestroy),
    defaultOutputStream_V:=erroneous,
    messageForm_V:=erroneous.
...

pzl::unRegisterAll/0

unRegisterAll:() procedure ().

Clear the object registry.

Description

Predicate removes all registered before objects from the object registry. Predicate succeeds even if there is no objects in the object registry.

Exceptions

No

Example

...
pzl::unRegisterAll(),
...