|Version 3 (modified by dustin, 13 months ago) (diff)|
The data api enforces a strong and well-defined model on Buildbot's data. This model is influenced by REST, in the sense that it defines resources, representations for resources, and identifiers for resources.
For each resource type, the api specifies
- the attributes of the resource and their types (e.g., changes have a string specifying their project)
- the format of links to other resources (e.g., buildsets to sourcestamp sets)
- the events that can occur on that resource (e.g., a buildrequest can be claimed)
The getter component can get either a single resource, or a list of resources. Getting a single resource requires a resource identifier (a tuple of strings) and a set of options to support automatic expansion of links to other resources (thus saving round-trips). Lists are requested with a partial resource identifier (a tuple of strings) and an optional set of filter options. In some cases, certain filters are implicit in the path, e.g., the list of buildsteps for a particular build.
Message subscriptions can be made to anything that can be listed or gotten from the getter component, using the same resource identifiers. Options and explicit filters are not supported - a message contains only the most basic information about a resource, and a list subscription results in a message for every new resource of the desired type. Implicit filters are supported.
The control component defines a set of actions that cause Buildbot to behave in a certain way, e.g., rebuilding a build or shutting down a slave. Actions correspond to a particular resource, although sometimes that resource is the root resource (an empty tuple).
The update component defines a free-form set of methods that Buildbot's process implementation calls to update data. Most update methods both modify state via the db api and send a message via the mq api. Some are simple wrappers for these APIs, while others contain more complex logic, e.g., building a source stamp set for a collection of changes. This component is the proper place to put common functionality required by disparate Buildbot components e.g., rebuilding builds.
The root of the data api is available at self.master.data. The first three components are implemented with the following methods:
- get -- get a resource
- subscribe -- subscribe to a resource or list, optionally getting its current state
- control -- perform an action on a resource
The update component is available at self.master.data.update, and contains a number of ad-hoc methods needed by the process modules.