The OpenILS Storage server has a very standardized API for retrieving individual objects, searching for objects, and updating, creating and deleting objects. Aproximately 99% percent of the API is automatically generated from the underlying table definitions, and contains about 8,900 methods. Becuase of this I will give a basic overview of the API and explain the storage layout, but will not be listing every single method published by the Storage server.
Methods published by the Storage server follow a simple functional hierarchy for their API Name. They are layed out first by thier access types and then by the object type on which they act. Let us take the example of open-ils.storage.cachable.direct.config.copy_status.batch.retrieve.atomic, which method can be broken down in this way:
The basic actions for each object type maintained by the Storage server are create, retrieve, update and delete. Thus, C.R.U.D. The Storage server also defines the batch action modifier for each of these actions. In addition, for Storage Drivers that can support it, there is a hook available for plugging in a mass_delete action for fast removal of many objects. All of these methods live inside the .direct access type branch of the open-ils.storage API Namespace. The .retrieve and .batch.retrieve methods also have a .cachable version available. Here are some examples of the CRUD interface:
There is also an all Method Variant for the retrieve method, but it is only available on certain object types. The reason for this is that a retrieve.all against large lists of objects would be very expensive. The object types for which retrieve.all is available are:
In addition to the CRUD interface's retrieve method, there is an API for searching when you don't know the id of the object you want. The base search interface is set up thusly:
As you can see, the search interface plays very well with the CRUD interface. In fact, everything up to the {search_type} is the same. The {search_type}s available to all drivers are:
For Storage Drivers that support them, such as the Postgres driver, there are three more search types available:
All search-type methods return a stream of fieldmapper objects that match the requested criteria. If you would perfer a single return value of an array containing the objects then simply use the .atomic version of the method, as in:
open-ils.storage.cachable.direct.actor.user.search_regex.family_name.atomic
The entire .direct retrieval and search interface trees, as well as some of the specialized methods, support the .cachable access modifier. This alternate API Name accepts an addition set of parameters that control the caching of the results from the query. Queries are identified using:
Paramters that relate directly to the cachable interface
Paramters that the cachable interface uses directly
When written as a direct parameter, as in
the cachable interface uses these for returning a (possibly cached) portion of the related cache page. The cache page is determined by finding the overlapping window of cache_page_size, limit and offset, and checking for a matching cache page.