Components of the Persistence Service 

The Persistence Service is a software layer that manages persistent objects. This software layer consists of a general part and a class-specific part. It is made up of global classes and interfaces from the Class Library. The class-specific part is specially generated for each persistent class.

The following graphic shows the components of the Persistence Service that are relevant to ABAP programmers:

CL_persistent

You create the class CL_persistent as a persistent class using the Class Builder. For more details on creating persistent classes with the Class Builder, see Creating Persistent Classes. The objects of this class are managed by the Persistence Service. These objects are known as managed objects. (Note that a managed object does not necessarily have to be a persistent object).

Instances of each persistent class CL_persistent can be either protected (CREATE PROTECTED) or abstract.

The Class Builder generates the SET and GET methods for the attributes of this class. The name of these classes always begins with CL_; there are no conventions governing the rest of the class name. You can adapt the generated class to your own needs.

The classes CA_persistent and CB_persistent

For each persistent class, CL_persistent, the Class Builder generates two further classes, CA_persistent and CB_persistent. These classes form the class-specific part of the Persistence Service. CB_persistent is a subclass of a general abstract superclass of all class actors, CL_OS_CA_COMMON.

CA_persistent is known the class actor (or class agent), which is used to manage the managed object of the class CL_persistent, and where database accesses actually take place. The class actor inherits its methods from the abstract superclass CB_persistent. The programmer can extend the class actor and redefine its methods (in particular, those for accessing the database). You cannot change the superclass CB_persistent. Each class actor is a friend of the managed class. The class actor is a singleton: It has the attribute CREATE PRIVATE. Exactly one instance of a class actor is created when it is first accessed.

Interfaces for the Class Actor

The class actor implements the interfaces IF_OS_FACTORY, IF_OS_CA_PERSISTENCY and IF_OS_CA_INSTANCE. You can use both the interface methods and the class methods. Interfaces also offer you generic access by means of interface reference variables. In the ABAP program, you can use interface reference variables of the same type to access different class actors for different persistent classes. The interfaces represent the general part of the Persistence Service.

Management Interface for the Persistent Class

The persistent class implements the management interface IF_OS_STATE, which lets you access the managed objects of different persistent classes in the same way.

Other interfaces and classes

The persistent class and the class actor are connected with other interfaces and classes in the Persistence Service, which are however mainly used internally. To find the names of these object types, refer to the definition of the persistent class and class actor in the Class Builder.

The AGENT attribute of the class actor

The AGENT static attribute is a reference variable with the type of the class CA_persistent. When you first access this attribute in an ABAP program, the static constructor of the class CA_persistent generates exactly one instance of this class, to which the AGENT attribute then points. This object is part of the Persistence Service; its methods are then used to manage the object of the persistent class. There is only one object of the class CA_persistent for each program, since you cannot create objects externally using CREATE OBJECT.

The class actor manages one or more objects of the appropriate class. Each object must have a unique key.

The main methods of the class actor

The Class Builder generates the following methods when you create the persistent class. You can then redefine them in the class CA_persistent. There are other methods available for internal use within the Persistence Service.

Methods inherited from CB_persistent

CREATE_PERSISTENT

Instantiates a new persistent object. The interface is generated according to the Mapping created from the persistent class to the ABAP Dictionary. If the persistent object is managed using business keys, the interface will contain the appropriate importing parameters. If the persistent object is managed using so-called GUIDs, a new instance GUID is generated when the object is created. Independently of which keys manage the object, there are optional importing parameters for all persistent attributes. The return value RESULT has the type of the persistent class and contains a reference to the generated persistent object. Each program can contain only one object for each key. The object is saved to the database using the COMMIT WORK statement. When the Persistence Service instantiates the object, it does not check whether or not the object is already available in the database. No errors will occur until you try to save an already available object. For this reason, you should always make sure that there is no existing persistent object with the same name, using the GET_PERSISTENT method.

GET_PERSISTENT

Loads a persistent object from the database and generates an appropriate runtime object in the ABAP program. The interface is generated according to the Mapping created from the persistent class to the ABAP Dictionary. The method is only available if the persistent object is managed using business keys, and the interface will contain the appropriate importing parameters. The return value RESULT has the type of the persistent class and contains a reference to the loaded persistent object. If an object with the same key already exists in the program, it is not loaded again, but instead the system returns the reference to the object already loaded. Changes to the object’s attributes are saved to the database using the COMMIT WORK statement.

DELETE_PERSISTENT

Deletes a persistent object. To delete the persistent object on the database as well, use the COMMIT WORK statement. The interface is generated according to the Mapping created from the persistent class to the ABAP Dictionary. The method is only available if the persistent object is managed using business keys, and the interface will contain the appropriate importing parameters.

CREATE_TRANSIENT

Generates a transient object of the persistent class. The method interface is the same as the interface for the CREATE_PERSISTENT method. Objects instantiated using CREATE_TRANSIENT are managed by the Persistence Service but have no connection to the database. With CREATE_TRANSIENT, you cannot generate more than one object with the same key in the program.

GET_TRANSIENT

Gets the reference to a transient object of the persistent class. The method interface is the same as the interface for the GET_PERSISTENT method. The object must have been created using the CREATE_TRANSIENT method. The system does not look for a corresponding persistent object in the database.

Methods of the Interface IF_OS_FACTORY

IF_OS_FACTORY~CREATE_PERSISTENT

If the persistent class is not managed using business keys, you can use this interface method (instead of the class method CREATE_PERSISTENT) to instantiate a persistent object of the class CL_persistent. The return value RESULT has the type of the persistent class and contains a reference to the generated persistent object. When the object is created, a new instance GUID is generated.

IF_OS_FACTORY~CREATE_PERSISTENT_BY_KEY

If the persistent class is managed using business keys, you can use this interface method (instead of the class method CREATE_PERSISTENT) to instantiate a persistent object of the class CL_persistent. The key is passed as a structure, whose components are the key fields, to the generic parameter I_KEY of the type ANY. The return value RESULT has the general type REF TO OBJECT and contains a reference to the generated persistent object. If the persistent object is managed using so-called GUIDs, a new instance GUID is generated when the object is created.

IF_OS_FACTORY~REFRESH_PERSISTENT

This method forces the system to load the current attributes of a persistent object from the database into the ABAP program. It does this by passing the object reference to the input parameter I_OBJECT of the type IF_OS_STATE. The current attributes are then fetched from the database when it is next accessed (on-request loading). The management state of the object may be either OSCON_OSTATUS_LOADED or OSCON_OSTATUS_NOT_LOADED. Immediately after the method has been executed, but before the attribute has been accessed, the management state is OSCON_OSTATUS_NOT_LOADED.

IF_OS_FACTORY~DELETE_PERSISTENT

Deletes a persistent object. It does this by passing the object reference to the input parameter I_OBJECT of the type IF_OS_STATE. To delete the persistent object on the database as well, use the COMMIT WORK statement.

IF_OS_FACTORY~CREATE_TRANSIENT

If the persistent class is not managed using business keys, you can use this interface method (instead of the class method CREATE_TRANSIENT) to instantiate a persistent object of the class CL_persistent. The return value RESULT has the type of the persistent class and contains a reference to the generated transient object.

IF_OS_FACTORY~CREATE_TRANSIENT_BY_KEY

If the persistent class is managed using business keys, you can use this interface method (instead of the class method CREATE_TRANSIENT) to instantiate a persistent object of the class CL_persistent. The key is passed to the generic parameter I_KEY of the type ANY as a structure whose components are the key fields. The return value RESULT has the general type REF TO OBJECT and contains a reference to the generated transient object.

IF_OS_FACTORY~RELEASE

Completely removes an object managed by the class actor from the management of the Persistence Service. It does this by passing the object reference to the input parameter I_OBJECT of the type IF_OS_STATE. The management state of the object may be either OSCON_OSTATUS_LOADED or OSCON_OSTATUS_NOT_LOADED.

Methods of the Interface IF_OS_CA_PERSISTENCY

IF_OS_CA_PERSISTENCY~GET_PERSISTENT_BY_OID

If the persistent class is not managed using business keys, you can use this interface method (instead of the class method GET_PERSISTENT) to get a persistent object from the database and generate an appropriate runtime object in the ABAP program. The object ID is passed to the parameter I_OID of the type OS_GUID. The return value RESULT has the general type REF TO OBJECT and contains a reference to the generated persistent object.

IF_OS_CA_PERSISTENCY~GET_PERSISTENT_BY_KEY

If the persistent class is managed using business keys, you can use this interface method (instead of the class method GET_PERSISTENT) to get a persistent object from the database and generate an appropriate runtime object in the ABAP program. The key is passed as a structure, whose components are the key fields, to the generic parameter I_KEY of the type ANY. The return value RESULT has the general type REF TO OBJECT and contains a reference to the generated persistent object.

IF_OS_CA_PERSISTENCY~GET_PERSISTENT_BY_OID_TAB

If the persistent class is not managed using business keys, you can use this interface method to get more than one persistent object simultaneously from the database and to generate appropriate runtime objects in the ABAP program. The objects’ IDs are passed to the I_OID_TAB parameter of type INDEX TABLE in an internal table. The return value RESULT is of general type OSREFTAB and contains a table of references to the persistent objects that are loaded. For each entry in the table, at the same position in the result table there is a corresponding entry that either contains an object reference to the loaded object, or it is initial if no object was found for the relevant ID. There is no corresponding method in the class actor.

So that you can use this method, the Multiple Access checkbox on the Generator Settings screen has to be selected.

IF_OS_CA_PERSISTENCY~GET_PERSISTENT_BY_KEY_TAB

If the persistent class is managed using business keys, you can use this interface method to get more than one persistent object simultaneously from the database and to generate appropriate runtime objects in the ABAP program. The objects’ keys are passed in an internal table, whose line type has the key fields as components, to generic parameter I_KEY_TAB of type INDEX TABLE. The return value RESULT is of general type OSREFTAB and contains a table of references to the persistent objects that are loaded. For each entry in the key table, at the same position in the result table there is a corresponding entry that either contains an object reference to the loaded object, or it is initial if no object was found for the relevant key. There is no corresponding method in the class actor.

So that you can use this method, the Multiple Access checkbox on the Generator Settings screen has to be selected.

IF_OS_CA_PERSISTENCY~GET_PERSISTENT_BY_QUERY

You can use this interface method to get more than one persistent object simultaneously from the database and to generate appropriate runtime objects in the ABAP program. A logical expression, which compares the attributes of the persistent class with parameters or values of your choice, determines which persistent objects are loaded. The logical expression is implemented by an instance of a class that implements interface IF_OS_QUERY. An instance of this type is a query object, often abbreviated to query, and can be generated using method CREATE_QUERY of interface IF_OS_QUERY_MANAGER (see section Query). A reference to the query is passed to parameter I_QUERY. The comparison values for the query are passed in an internal table to the I_PARAMETER_TAB parameter. If the query requires a maximum of three comparison values with an elementary type, these can also be passed individually to parameters I_PAR1, I_PAR2 and I_PAR3. You can use parameter I_SUBCLASSES and I_UPTO to determine whether instances of subclasses of the persistent class are also loaded or the maximum number of instances that can be loaded. The return value RESULT is of general type OSREFTAB and contains a table of references to the persistent objects that are loaded. You can also determine the sorting of the object references using the query. There is no corresponding method in the class actor.

So that you can use this method, the Multiple Access checkbox on the Generator Settings screen has to be selected.

Methods of the Interface IF_OS_CA_INSTANCE

IF_OS_CA_INSTANCE~GET_STATUS

Gets the management state of a persistent object. The input parameter, with the general type REF TO OBJECT, passes a reference to the managed object. The return value RESULT has the type OS_STATUS and can have the value 0, 1, 2, 3, 4, or 10, matching the constants OSTATUS_ of the type group OSCON.

IF_OS_CA_INSTANCE~GET_NOT_LOADED

Gets all the objects managed by the class actor in the management state OSCON_OSTATUS_NOT_LOADED (0). The return value is an internal table with the general line type REF TO OBJECT.

IF_OS_CA_INSTANCE~GET_CREATED

Gets all the objects managed by the class actor in the management state OSCON_OSTATUS_NEW (1). The return value is an internal table with the general line type REF TO OBJECT.

IF_OS_CA_INSTANCE~GET_LOADED

Gets all the objects managed by the class actor in the management state OSCON_OSTATUS_LOADED (2). The return value is an internal table with the general line type REF TO OBJECT.

IF_OS_CA_INSTANCE~GET_CHANGED

Gets all the objects managed by the class actor in the management state OSCON_OSTATUS_CHANGED (3). The return value is an internal table with the general line type REF TO OBJECT.

IF_OS_CA_INSTANCE~GET_DELETED

Gets all the objects managed by the class actor in the management state OSCON_OSTATUS_DELETED (4). The return value is an internal table with the general line type REF TO OBJECT.

IF_OS_CA_INSTANCE~TRANSIENT

Gets all the objects managed by the class actor in the management state OSCON_OSTATUS_TRANSIENT (10). The return value is an internal table with the general line type REF TO OBJECT.

The Main Methods of the Management Interface

The interface IF_OS_STATE defines the interface of a class that can be managed with Object Services. It allows you to monitor and manage objects of this class.

IF_OS_STATE~INIT

Is called when creating a persistent or transient object and when loading a persistent object after persistent attributes have been set. Here you can, for example, initialize transient attributes and register checking agents or event handlers.

IF_OS_STATE~INVALIDATE

Is called for persistent objects when deleting a persistent object, forcing the reload of a persistent object, and starting a subsequent transaction after resetting the persistent attributes. Here you can, for example, reset transient attributes and deregister event handlers. It is also called in the case of resetting by the UNDO service.

IF_OS_STATE~HANDLE_EXCEPTION

Is called when an exception occurs in the GET and SET methods and raises the exception that is passed as a parameter. Here, you can handle the exceptions raised. In general however, the exceptions should be handled by the user of the GET and SET methods.

IF_OS_STATE~GET and IF_OS_STATE~SET

These methods are for internal use and must not be changed.