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:

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.

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.

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.

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.

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 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 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.

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.

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.

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 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 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 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.

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.

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 Check Agents or event handlers.

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.

Is called when an exception occurs in the GET and SET methods and raises the exception that is transferred 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.

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