User Tools

Site Tools


documentation:developer:zzz_archive:backend-devel:open-ils_storage_api

OpenILS Storage Server API Overview

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.

Base Method Naming Structure

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:

  • open-ils.storageAPI Namespace
    The API Namespace in which the method lives.
    • .cachableAccess Type
      Denotes this method as a cadidate for server-side caching, and informs the user that the method accepts optional cache-oriented parameters.
    • .directAccess Type
      This method acts directly on the underlying storage mechanism, and deals only with Fieldmapper objects of the Fieldmapper::config::copy_status type.
      • .config.copy_statusObject Type
        This tells the user what object type this method deals with, in this case Fieldmapper::config::copy_status.
        • .batchAction Modifier
          In this case, specifying that the method accepts multiple IDs and will return multiple Fieldmapper::config::copy_status objects.
        • .retrieveAction
          This is the action to be performed.
          • .atomicMethod Variant
            Because the base version of this method is streaming, an atomic variant is supplied by the system for use by stateless clients.

The Creeping C.R.U.D.

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:

  • open-ils.storage.direct.permission.usr_grp_map.create
  • open-ils.storage.direct.permission.usr_perm_map.batch.create
  • open-ils.storage.direct.permission.usr_perm_map.batch.retrieve
  • open-ils.storage.cachable.direct.permission.usr_perm_map.batch.retrieve
  • open-ils.storage.cachable.direct.permission.usr_perm_map.batch.retrieve.atomic
  • open-ils.storage.direct.permission.usr_grp_map.update
  • open-ils.storage.direct.permission.usr_grp_map.batch.update
  • open-ils.storage.direct.permission.usr_perm_map.delete
  • open-ils.storage.direct.permission.usr_perm_map.batch.delete

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:

  • config.metabib_field
  • config.standing
  • config.identification_type
  • config.copy_status
  • actor.org_unit
  • actor.org_unit_type
  • actor.profile
  • asset.copy_location

Return types

  • .create – Returns the id of the new object
  • .batch.create – Returns the number of objects created
  • .retrieve – Returns the fieldmapper object identified by the id passed in
  • .batch.retrieve – Returns a stream of fieldmapper objects identified by the list of ids passed in
  • .retrieve.all – Returns a stream of ALL fieldmapper objects of that type
  • .update – Returns 1 on success, 0 on failure
  • .batch.update – Returns the number of objects updated
  • .delete – Returns 1 on success, 0 on failure
  • .batch.delete – Returns the number of objects deleted
  • .mass_delete – Returns 1 on success, 0 on failure

Searching

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:

  • open-ils.storage[.{access_type}].direct.{object_type}.{search_type}[.{property}]

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:

  • .search
    The argument to this function is a hash (JSON Object) where the keys are the property names and the values are the property values. This will perform an ANDed equality search based on all properties passed in.
  • .search.property
    The argument to this function is the value to search for on the named property. Use this when you want to search a single property, as it is faster and the method name makes it easier to remeber what your code is doing.
  • .search_like
    This works exactly like search, but performs a text search using % as the "any string" wildcard and _ as the "one character" wildcard.
  • .search_like.property
    This works exactly like search.property, but performs a text search using % as the "any string" wildcard and _ as the "one character" wildcard.

For Storage Drivers that support them, such as the Postgres driver, there are three more search types available:

  • .search_ilike (and .search_ilike.property)
    Provides a case insensitive version of .search_like.
  • .search_regex (and .search_regex.property)
    Provides POSIX regular expression searching.
  • .search_fts (and .search_fts.property)
    Provides Driver specific Full Text searching.1)
  • .search_where
    Provides a more complex but flexible search interface with the same syntax as Class::DBI::AbstractSearch.

Return types

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

Optional Result Caching

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:

  1. The API Name of the method that is called
  2. All parameters other than a limit or offset listed directly on the request

Paramters that relate directly to the cachable interface

  • cache_page_size
    Default: 1000
    This controls how much of the total result is held in the cache at any given time
  • timeout
    Default: 7200 seconds (2 hours)
    Specifies how long the contents of each cache page will exist in cache.

Paramters that the cachable interface uses directly

  • limit
    Default: 100
  • offset
    Default: 0

When written as a direct parameter, as in

  • open-ils.strorage.cachable.direct… '17', 'limit', '10', 'offset', '40'

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.

1)
This will eventually use the generic OpenILS::Application::Storage::FTS infrastructure to allow Driver agnostic searches.
documentation/developer/zzz_archive/backend-devel/open-ils_storage_api.txt · Last modified: 2018/04/24 10:26 by dbwells

© 2008-2017 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.