Assembly line signals

From Apibot
Jump to: navigation, search

The assembly line objects pass between them the information to be processed, encapsulated in objects called signals. If you are a network admin, imagine the assembly line as a TCP connection and the signals as TCP packets.

The signal classes are implemented in the file line/signal.php.

Types of signals

Currently there are three types of signals defined: Start, End and Data. Every data stream (feed) starts with a Start packet, contains zero or more Data packets and ends with an End packet.

Signal parameters

All signals can carry signal parameters - metadata that serves as a means of communication between the assembly line objects. A signal can carry zero or more named parameters groups, each of them having zero or more named parameters. Their purpose if passing between line objects information other than the data - eg. work parameters or instructions.

Each type of assembly line object, when accepting a signal, will seek for a parameters group named after the line object type ( "feeder", "fetcher", "filter" etc). If found, the object will try to set its parameters from the parameters in this group, and will delete the group from the signal. The same will be done with a parameters group named after the line object name (eg. "Page.Edit.Replace.Strings"), and the parameters from it will take priority over those of the type-named group.

Signals data

In addition, the Data signals can carry zero or more data blocks. Each data block consists of a data element (which is eventually the data being processed), a data type indicator (similar by syntax to a MIME type), data key (if the data element was fetched together with some ID, that's it) and possibly more info.

The data blocks are referenced by data element keys. Every assembly line object has a default data key which indicates the signal data block (and element) that will be processed. Typically Data signals carry only one data block, referenced by the standard for the line objects default data key ('*'). You can change the default data key of a line object.

There are workers that can set, unset, copy, rename etc. data blocks or the data in them.

Properties and methods

All signal objects have the following public properties:

Name Contains
$id A random numeric ID of the signal. Used to avoid signal duplication.
$log An array where every line object this signal passes leaves some info on what it did
$params An array with the parameter groups, their names as keys. (Every parameter group is also an array, with the parameter names as keys.)

All signal objects have the following public methods:

Name and profile Result
exists_paramgroup ( $group_name ) true if it exists, false if not
unset_paramgroup ( $group_name ) Deletes the group with this name, if it exists.
copy_paramgroup ( $group_name, $to_name ) If the group with $group_name exists, copies it to $to_name and returns true. Otherwise, returns false.
rename_paramgroup ( $group_name, $to_name ) If the group with $group_name exists, moves it to $to_name and returns true. Otherwise, returns false.
swap_paramgroups ( $group_name1, $group_name2 ) If any of the groups exists, renames it to the other name and returns true. If none of them exists, returns false.
exists_param ( $group_name, $param_name ) true if it exists, false if not
unset_param ( $group_name, $param_name ) Deletes the param with this name, if it exists.
copy_param ( $group_name, $param_name, $to_name, $to_group = NULL ) If this param exists, copies it to $to_name (and $to_group, if not NULL) and returns true. Otherwise, returns false.
rename_param ( $group_name, $param_name, $to_name, $to_group = NULL ) If this param exists, moves it to $to_name (and $to_group, if not NULL) and returns true. Otherwise, returns false.
swap_params ( $group_name1, $param_name1, $group_name2 = NULL, $param_name2 = NULL ) If any of the params exists, renames it to the other group/name and returns true. If none of them exists, returns false.
paramgroup ( $group_name ) The requested params group, or NULL if it doesn't exist.
set_paramgroup ( $group_name, $group = array() ) Sets the given group to this name.
param ( $group_name, $param_name ) The requested param, or NULL if it doesn't exist.
set_param ( $group_name, $param_name, $param ) Sets the given param to this group / name.

The Data signal objects also have the following public methods:

Name and profile Result
all_data() The complete array of data blocks.
all_data_keys() An array with the keys of all data blocks.
exists_data_block ( $data_key ) true if it exists, false if not
unset_data_block ( $data_key ) Deletes the data block with this key, if it exists.
copy_data_block ( $from_key, $to_key ) If the data block with $from_key exists, copies it to $to_key and returns true. Otherwise, returns false.
rename_data_block ( $from_key, $to_key ) If the data block with $from_key exists, moves it to $to_key and returns true. Otherwise, returns false.
swap_data_blocks ( $key1, $key2 ) If any of the data blocks exists, renames it to the other and returns true. If none of them exists, returns false.
data_block ( $data_key ) Returns this data block, or NULL if it does not exist.
data_element ( $data_key ) Returns the data element from the data block with this key, or NULL if it does not exist.
data_type ( $data_key ) Returns the data type from the data block with this key, or NULL if it does not exist.
data_element_key ( $data_key ) Returns the data element key from the data block with this key, or NULL if it does not exist.
set_data_block ( $data_key, $data_block ) Sets this data block to the signal.
set_data_element ( $data_key, $data_element ) Sets this data element to the signal.
set_data_type ( $data_key, $data_type ) Sets this data type to the signal.
set_data_element_key ( $data_key, $data_element_key ) Sets this the data element key to the signal.
data_element_property_exists ( $data_key, $property ) true if it exists, false if not
data_element_property ( $data_key, $property ) Returns the data element property (object property or array member with a key $property) from the data block with this key, or NULL if it does not exist.
set_data_element_property ( $data_key, $property, $value ) Sets this value to this data element property from the data block with this key.

The Data signal objects have also some methods that try to extract intelligently and return specific properties from wiki (and some other) data. For example, the data_title() method will try to return a page title even from objects that do not directly contain one. If the data element is a wiki user, this method will return its user page. If the data element is an image description, this method will try to return the image page, etc.

Name and profile Attempts to return
data_title() Wiki page title
data_pageid() Wiki page ID
data_revid() Wiki revision ID
data_user() Wiki user account name
data_by_user() Wiki user the data element has been done by (eg. the admin that did this blocking)
data_userid() Wiki user account ID
data_by_userid() Wiki user ID the data element has been done by (eg. the admin that did this blocking)
data_timestamp() Wiki timestamp
data_expiry() Wiki object (eg. block) expiry
data_nsid() Wiki namespace ID
data_rcid() Wiki recentchange ID
data_logid() Wiki log record ID
data_blockid() Wiki user / IP block ID
data_size() Wiki object size (eg. revision text size)
data_extlink() Wiki object extlink
data_unique_id() Something that identifies uniquely this data element among the others of its type