API Reference

procedure Write_Reference, function Read_Reference

   procedure Write_Reference(  
      Stream : access Root_Stream_Type'Class; 
      Item   : in Reference ); 
   for Reference'Output use Write_Reference; 
 
   function Read_Reference( 
      Stream : access Root_Stream_Type'Class ) return Reference; 
   for Reference'Input use Read_Reference; 
 

this type is the root type of all persistent objects use this as references to persistent types

the following two procedures should be ignored, since they are required internaly to read and write references in the object store. They should never be called directly, only by means of the Input, Output attributes.

procedure Serialize

   procedure Serialize(  
      Item   : in out Object;  
      Header : in out Storage_Header.Object; 
      S      : in Stream_Access ) is abstract; 
 

This execption indicates that an object reference cannot be resolved.

   Unresolved_Reference : exception ; 
   Unknown_Attribute    : exception ; 

Maximum number of objects in the Persistent pool.

   Max_Nbr_Of_Objects   : constant Natural := 32_000; 

Description

This procedure writes out the object into the stream provided by the Persistency module. Each field of the object may be written out by means of the Output attribute. References to other objects are automatically expanded into a logical representation which can be read in later if the Method Reference'Output is used.

Preconditions

None

Postconditions

None

Exceptions

None

Notes

Please note, that the application delveloper has to provide this implemenation, but it should never be called somewhere in the application.

This procedure is only called by the persistency manager and should be placed in the private section.

procedure Deserialize

   procedure Deserialize(  
      Item   : in out Object;  
      Header : in out Storage_Header.Object; 
      S      : in Stream_Access ) is abstract; 
 

Description

Read in all field of the given object. This procedure is called by the persistency manager when loading the objects from an external file.

The procedure may read each field of the object by means of the Input attribute except for references to other instances in the object space. These entires have to be loaded by means of the Reference'Input method.

Preconditions

None

Postconditions

It is assumed, that all fields have been read.

Exceptions

Notes:

Please ensure, that the number of field written is identical to the number of fields read in. If not the file becomes unreadable. This procedure is only called by the persistency manager and should be placed in the private section.

function Factory

   function Factory return Reference is abstract;  
    

Description

The factory funtion creates a new object of the implenting class. Under normal circumstances this will be an new Object operation. This function will be registered together with the External_Tag of the implementation in order to allow the persistency manager to create instances when reading in the data from a file.

Preconditions

None

Postconditions

The function returns a reference to the newly created object

Exceptions

Notes:

Please be aware, that any initialization done in this procedure will be overwritten later when the actual object is restored.

function Object_Id

   function Object_Id(   
      Ref   : in Reference ) return Natural; 

Description

Returns the object identifier

Preconditions

None

Postconditions

Returns the object identifier which is a Natural number.

Exceptions

Notes:

procedure Name_Object

   procedure Name_Object(  
      Ref  : in Reference ; 
      Name : in String );       
 

Description

Assign a unique name to the object

Preconditions

C.1 - The Reference has to be valid C.2 - Name has to be unique.

Postconditions

Exceptions:

Invalid_Object - violation of C.1 Duplicate_Name - violation of C.2

function Object_Name

   function Object_Name(  
      Ref  : in Reference ) return String; 
 

Description

Ask for the object name

Preconditions

P.1 - Reference is valid

Postconditions

Returns a string with the name of the object

Exceptions

None

function Lookup_Object

   function Lookup_Object(  
      Name : in String ) return Reference; 

Description

Lookup the object from the object table.

Preconditions

Postconditions:

Returns the reference if the object does exist. Returns null if the object does not exist.

Exceptions

None

function Is_Persistent

   function Is_Persistent(  
      Ref   : in Reference ) return Boolean; 
 

Description

Check if the referenced object is persistent

Preconditions

C.1 - The Reference has to be valid

Postconditions

- The function returns true, if the object is persistent.

Exceptions

Invalid_Object - violation of C.1

function Get_Reference

   function Get_Reference(   
      Id    : in Natural; 
      Force : Boolean := False ) return Reference; 
 

Description

Return the reference to an object from the object identifier

Preconditions

None

Postconditions

Returns the reference to the object if it exists Returns null, if the object does not exist.

Exceptions

None

function Nbr_Of_Objects, procedure Index

   function Nbr_Of_Objects return Natural;  
 
   procedure Index(  
      Idx : in out Object_Index.Object'Class ); 
 
 

Description

Number of objects in the persistent pool

Preconditions

None

Postconditions

- Returns the number of already stored objects in the pool.

Exceptions

None