Sorcery is a unifying data access layer which utilizes the configuration framework, realtime, and astdb to allow object creation, retrieval, updating, and deletion.

Initialization

Usage of sorcery is accomplished by first opening a sorcery structure. This structure holds all information about the object types, object fields, and object mappings. All API functions require the sorcery structure to operate. When sorcery is no longer needed the structure can be unreferenced using ast_sorcery_unref

Once opened the sorcery structure must have object mappings applied to it. This maps the object types to their respective wizards (object storage modules). If the developer would like to allow the user to configure this using the sorcery.conf configuration file the ast_sorcery_apply_config API call can be used to read in the configuration file and apply the mappings. ast_sorcery_open will automatically call ast_sorcery_apply_config to allow for configuration of objects using the same category name as the module that is opening the sorcery instance. Direct calls to ast_sorcery_apply_config should only be performed if a module wishes to allow for additional configuration sections in sorcery.conf to be used. If the storage of the object types are such that a default wizard can be used this can be applied using the ast_sorcery_apply_default API call. Note that the default mappings will not override configured mappings. They are only used in the case where no configured mapping exists.

Configuring object mappings implicitly creates a basic version of an object type. The object type must be fully registered, however, using the ast_sorcery_object_register API call before any objects of the type can be allocated, created, or retrieved.

Once the object type itself has been fully registered the individual fields within the object must be registered using the ast_sorcery_object_field_register API call. Note that not all fields need be registered. Only fields that should be accessible using the sorcery API have to be registered.

Creating Objects

Before an object can be created within the sorcery API it must first be allocated using the ast_sorcery_alloc API call. This allocates a new instance of the object, sets sorcery specific details, and applies default values to the object. A unique identifier can optionally be specified when allocating an object. If it is not provided one will be automatically generated. Allocating an object does not create it within any object storage mechanisms that are configured for the object type. Creation must explicitly be done using the ast_sorcery_create API call. This API call passes the object to each configured object storage mechanism for the object type until one successfully persists the object.

Retrieving Objects

To retrieve a single object using its unique identifier the ast_sorcery_retrieve_by_id API call can be used.

To retrieve potentially multiple objects using specific fields the ast_sorcery_retrieve_by_fields API call can be used. The behavior of this API call is controlled using different flags. If the AST_RETRIEVE_FLAG_MULTIPLE flag is used a container will be returned which contains all matching objects. To retrieve all objects the AST_RETRIEVE_FLAG_ALL flag can be specified. Note that when specifying this flag you do not need to pass any fields.

Both API calls return shared objects. Modification of the object can not occur until it has been copied.

Updating Objects

As retrieved objects may be shared the first step to updating the object with new details is creating a copy using the ast_sorcery_copy API call. This will return a new object which is specific to the caller. Any field within the object may be modified as needed. Once changes are done the changes can be committed using the ast_sorcery_update API call. Note that as the copied object is specific to the caller it must be unreferenced after use.

Deleting Objects

To delete an object simply call the ast_sorcery_delete API call with an object retrieved using the ast_sorcery_retrieve_by_* API calls or a copy returned from ast_sorcery_copy.