Persistate

Standard Persistate operations

Hide Navigation Pane

Standard Persistate operations

Previous topic Next topic No directory for this topic  

Standard Persistate operations

Previous topic Next topic Topic directory requires JavaScript JavaScript is required for the print function Mail us feedback on this topic!  

Persistate provides a standard set of operations, which are defined for the Persistent class, and therefore applicable to every persistent object.  Persistate also provides a standard implementation of these operations, which will be described below.  Persistate applications can either use a standard implementation, or replace it, either partially or fully.  The Generator and Configurator applications do override some of the standard functionality, and these cases will also be described below.

All operations take an Execution object as a parameter, which represents the particular execution of the operation.  This gives access to the target object and target collection, as well as the current Session and UserInterface.  When an operation is executed using a menu item or  toolbar button, by default, the Execution object is the only parameter supplied.  However, some operations can take other parameters, and where this is the case it is noted below.  To pass extra parameters, operations must be executed in code.

The standard operations are divided into four operation groups.   The File operation group contains operations that typically appear on a File menu.  The Object operation group contains the most basic operations that work on single objects.  The Collection operation group contains  operations that work on objects within collections, and the View operation group contains operations that affect the appearance and layout of an application and typically appear on a View menu.

File operation group

This operation group contains operations that typically appear on a File menu.

Save

Save is not a real operation, but is used internally in Persistate to signal the end of a Modify operation which was begun earlier when the user modified an object in the user interface.  When the user selects Save, any modifications are synchronised with persistent storage.

Revert

Like Save, Revert is used by Persistate  to signal the end of a Modify operation.  In this case, all changes made in memory are rolled back.  See Synchronising with persistent storage for details of how Save and Revert are handled.

Exit

This operation exits the current application.  It operation will be executed if triggered from a menu or toolbar button, and if the user closes the last open window of an application.  It will also be executed internally in a Viewer-Server configuration if the server service stops.  During the execution of this operation, the Session.SessionEnding event is triggered.  See Other events for details.

Login

This operation, by default, performs authentication and authorisation for user currently logged in to the workstation operating system.  It is not  normally linked to a menu item or toolbar button, but is called programmatically when a session's user interface is initialised.  This operation takes an extra parameter which is a Credentials object.  By default, the parameter passed contains pre-authenticated credentials for the currently logged in user.

The standard implementation of this operation will create a new Principal object for the pre-authenticated user if one does not yet exist, and transfer the session to that Principal.  The Principal created will have its Identification property set to <domain>\<user> where <domain> is the value returned by System.Environment.UserDomainName and <user> is the value returned by System.Environment.UserName.

The authenticated Principal will then be authorised (or not) for the running package.  This only happens if the Package.SecurePackage property is true;  If authentication or authorisation fails, then the ExecutionResult returned from the operation will have a ResultAction of CommitWarning, and a SimpleMessage detailing the problem.  If they succeed, the operation will have a ResultAction of Commit.

Object operation group

This operation group contains the most basic operations that work on single objects.

Modify

This operation is never linked to a menu item, toolbar button or any other user interface element.  It is started automatically whenever you first modify an object in the user interface after the completion of the previous operation execution.  It is completed when you select Save or Revert, or select another operation for execution.  See Synchronising with persistent storage for details.

Refresh

This operation simply refreshes the value of the target object from persistent storage.

Show

This object shows an object or collection using a particular layout in a pane of the active window.  By default it is not linked to a menu item or toolbar button, but is often linked to an "operation column" in a grid.  Clicking the cell on a row of the grid will show the object in that row in a form.  It is also called when you click the text of a node in Tree layout types, such as the Domain Tree shown in the left navigation pane of both the Generator and Configurator applications.

Show takes zero, one or two extra parameters.  If there are no extra parameters passed, then the Layout used to show the object or collection, and the Pane in which it is shown are chosen automatically by the Persistate infrastructure.  If one extra parameter is passed, then it should be the Layout to be used, and the Pane is chosen automatically.  If a second parameter is passed it should be the name of the Pane in which the object or collection should be shown.

Collection operation group

This operation group contains operations which work on objects within collections.

Refresh All

This operation simply refreshes the contents of the target collection from persistent storage.

Delete

This operation deletes the target object from the target collection.  This operation is visible only for contained collections - the equivalent operation for associated collections is Remove.

By default, if the class of the object to be deleted has the log associations function (see Class Category Definition), this operation first checks if there are any associations to it. If there are, then the operation returns a warning and the object is not deleted.  Otherwise, Persistate asks the user for confirmation before the object is deleted from the collection.  Remember that this deletes the entire branch of the containment tree under the target object.

Caution

If the class of the object does not have the log associations function, then no check is made to see if there are any associations to it.  If there are, and you delete the object, those associations will be orphaned, and a PersistateDeReferenceException will be thrown when they are accessed.

Both Generator and Configurator add functionality to the Delete operation.  If the target object is a Database, then it returns a warning saying that the operation is not implemented - you can't delete databases.  If the target object is a Package, then a check is first made to see if the package is used by any other packages, and if so a warning is returned.  If it is not then, after confirmation, all of the package's data and metadata is removed from all databases on which it had been created.

Generator and Configurator also render the Delete operation invisible for a number of classes.  These are classes which are maintained by Persistate, most often those which are instantiated from processing the definition file.  So for example, you cannot Delete object classes, class categories, operation groups, operations, etc..

Remove

This operation removes the target object from the target collection.  This operation is visible only for associated collections - the equivalent operation for contained collections is Delete.  As this does not produce irreversible changes, it does not ask for confirmation, but simply removes the association immediately.

Both Generator and Configurator add functionality to the Remove operation. If you attempt to remove a Database from the Package.TargetDatabases collection, a warning is issued.  This functionality has not yet been implemented.

New

This operation creates a new object in the target collection. This operation is visible only for contained collections - the equivalent operation for associated collections is Add.

If the collection in which a new object is being created is a diverse collection, i.e. it can contain any derived class of the collection's defined class, then Persistate displays a small dialogue listing all these derived classes as well as the defined class.  You select the class of object you want to create and click Ok.

A new object is then instantiated.  If there is a form layout for the object, by default one that has the UseForNew property set, then the new object is displayed in a modal dialogue box using that layout.  Enter details of the object and click Ok, and the new object is added to the collection.  If there is no form layout, then the new object is added to the collection as is.  In both cases, the new object is given the focus in the grid from which it was created.

Generator and Configurator add functionality to the New operation.  If you try and create a new package in the system environment, it returns a warning - this is not allowed.  Also, when you use this operation to create a new Package, Database, Server or Environment, the appropriate CreateXXXX operation which performs the creation is executed, and the result passed back.  See Common operations for details of these creation operations.

Generator and Configurator also render the New operation invisible for a number of classes.  These are classes which are maintained by Persistate, most often those which are instantiated from processing the definition file.  So for example, you cannot create object classes, class categories, operation groups, operations, etc. with the New operation.

Add

This operation adds a new object to the target collection. This operation is visible only for associated collections - the equivalent operation for contained collections is New.

By default, this operation allows you to choose one or more objects to add to the target collection.  How you choose the object depends on how the collection was specified in the definition file, specifically whether it has a from or within clause, and whether the clause's specified source is a collection of several or many objects.  See Object Class Definition for details.  The following cases describe the different types of collection and how objects are chosen in each case

The collection has a from clause and its specified source is a collection of several objects.  Persistate displays a dialogue box listing all the objects in the from clause source collection.  Select one or more objects to add and click Ok.
The collection has a from clause and its specified source is a collection of many objects.  Persistate displays the appropriate Lookup form for the source collection.  Use the form to search for the object(s) you want.  Set the checkbox next to each object and click the Select button.
The collection has a within clause, or no clause at all.  Persistate displays the object selection dialogue.  The root object in the dialogue will be the within clause source, or it there is no within clause, the collection of singleton objects in the package.  Select one or more objects using the dialogue, and click Ok.

Both Generator and Configurator add functionality to the Add operation.  When you add a Database to the Package.TargetDatabases collection, Persistate will create all the tables, indexes, and other database objects required to store objects for that Package in the Database.  Also, when you add a Package to the Environment.AvailablePackages collection, Persistate creates a persistent tree for the Package in the Environment, including any configurative objects which were available in the Package the last time it was deployed in or imported into the local Domain.

Insert

This operation creates a new object in, or adds an object to, the target collection of several ordered objects, at a particular index.  This operation will be visible only for ordered collections, but can be executed for both contained and associated collections.

When selected, this operation performs exactly as the New or Add operations described above, depending on whether the target collection is contained or associated respectively.  The difference being that once you have created the new object or selected the object(s) to add, the object(s) are inserted into the collection at the index currently occupied by the target object.  The target object and all below it are moved down in the collection to accommodate the inserted object(s).

Generator and Configurator render the Insert operation invisible for a number of classes.  These are classes which are maintained by Persistate, most often those which are instantiated from processing the definition file.  Effectively, this means that there is nowhere in these applications where Insert can be used.

Move Up

This operation moves the target object up in the target collection.  This operation will be visible only for ordered collections.  In effect, this operation swaps the target object with the one above it (towards the start) in the collection.

In Generator and Configurator, this operation is limited to use on the OperationGroup.Operations and Layout.Placements collections.

Move Down

This operation moves the target object down in the target collection.  This operation will be visible only for ordered collections.  In effect, this operation swaps the target object with the one below it (towards the start) in the collection.

In Generator and Configurator, this operation is limited to use on the OperationGroup.Operations and Layout.Placements collections.

View operation group

This operation group contains operations that affect the appearance and layout of an application and typically appear on a View menu.

Back

This operation redisplays the content most recently obscured by a Show operation, or by selecting Clear Pane from a pane context menu.  The content is redisplayed in its original pane using the original Layout.  If the pane no longer exists, a warning is issued, and the content is not redisplayed.

This operation executes in the user interface module.  This means that in Viewer-Server configurations, it executes in the viewer.

Forward

This operation redisplays the content most recently obscured by a Back operation.  The content is redisplayed in its original pane using the original Layout.  If the pane no longer exists, a warning is issued, and the content is not redisplayed.

This operation executes in the user interface module.  This means that in Viewer-Server configurations, it executes in the viewer.

Parent

This operation displays the parent object of the target object.  The parent object is displayed using the default layout and in a pane chosen by Persistate.

Save Workspace

This operation saves the arrangement of panes in the window, along with the content showing in each, in a new workspace.  You are prompted to enter a new name for the workspace.  See Customising the workspace for details.

Restore Workspace

This operation restores the window to show the arrangement of panes and content saved using the Save Workspace operation.  It displays a small dialogue allowing you to choose the workspace to restore.   See Customising the workspace for details.

Apply Style

This operation applies a particular layout style to the window and all the panes and content showing in it.  It displays a small dialogue listing all the available layout styles.  Choose the one you want and click Ok.  the new style is applied immediately to the window.  See Customising the workspace for details.

This operation executes in the user interface module.  This means that in Viewer-Server configurations, it executes in the viewer.

Select Container

This operation selects the parent pane to the currently active pane.  This is most useful if you want to add a new pane below a set of tabbed panes.  You can't do this to a single tabbed pane, so you must select its parent pane, which holds all the tabbed panes, using this operation before doing so.

This operation executes in the user interface module.  This means that in Viewer-Server configurations, it executes in the viewer.

Add Tab

This operation adds a new empty tabbed pane to either an empty pane or an existing set of tabbed panes.  See Customising the workspace for details of using tabbed panes.

This operation executes in the user interface module.  This means that in Viewer-Server configurations, it executes in the viewer.

Add Pane / To Left

This operation splits the active pane into two, with a vertical divider.  It puts the original content of the active pane into the right pane and leaves the left one empty.    See Customising the workspace for details of splitting panes.

This operation executes in the user interface module.  This means that in Viewer-Server configurations, it executes in the viewer.

Add Pane / To Right

This operation splits the active pane into two, with a vertical divider.  It puts the original content of the active pane into the left pane and leaves the right one empty.    See Customising the workspace for details of splitting panes.

This operation executes in the user interface module.  This means that in Viewer-Server configurations, it executes in the viewer.

Add Pane / Above

This operation splits the active pane into two, with a horizontal divider.  It puts the original content of the active pane into the bottom pane and leaves the top one empty.    See Customising the workspace for details of splitting panes.

This operation executes in the user interface module.  This means that in Viewer-Server configurations, it executes in the viewer.

Add Pane / Below

This operation splits the active pane into two, with a horizontal divider.  It puts the original content of the active pane into the top pane and leaves the bottom one empty.    See Customising the workspace for details of splitting panes.

This operation executes in the user interface module.  This means that in Viewer-Server configurations, it executes in the viewer.