NAME
SIAM::Documentation::DriverSpec - SIAM driver specification
INTRODUCTION
A SIAM driver is what connects to the enterprise database and retrieves objects and their attributes.
There is no base class for a driver, and the enterprises are free to implement the drivers in in their preferred ways.
A driver is a Perl object which must provide a number of methods, as described below. The validity of the driver object is verified by validate_driver() method of SIAM::Object
The driver class should take care of error reporting. It should be able to send its error messages to STDERR or a log file.
METHODS
new
my $driver = EnterpriseDriverClass->new($drvopts);The new() method creates an instance of the driver object. It takes a hash reference as an argument. This hash defines all configuration needed to initialize the driver.
One entry in the configuration hash is mandatory: Logger. It supplies a reference to an object which is used for all logging. The object must implement the following methods: debug, info, warn, and error.
Requirements for the rest of configuration hash are defined by the driver class.
The new() method should validate the configuration and return undef in case of problems.
connect
Connects the driver to its underlying databases. Returns true in case of success.
disconect
Disconnects the driver from its underlying databases and frees its internal memory. The driver should be able to connect() again.
fetch_attributes
$status = $driver->fetch_attributes($attrs);The argument is a hash reference that contains the SIAM::Object mandatory attributes (siam.object.id and siam.object.class).
The driver should populate the provided hashref with the rest of the object's attributes, based on its ID and class.
The method should return undef in case of failures, and true otherwise.
fetch_computable
$value = $driver->fetch_computable($id, $key);Returns a computable value for the object. The driver must return empty string if the computable is not supported. Returns undef if the object ID is invalid.
fetch_contained_object_ids
$ids = $driver->fetch_contained_object_ids($id, $classname, $options);The method returns an arrayref containing IDs of contained objects of a given class. The method must return an empty arrayref if there are no contained objects.
Options define a filter as follows. If no filter is defined, all relevant object IDs should be returned.
$ids = $driver->fetch_contained_object_ids($id, 'SIAM::Contract', {
'match_attribute' => [ 'siam.object.access_scope_id',
['SCOPEID01', 'SCOPEID02'] ]
}
);In this example, only the contracts which match the specified access scopes are returned.
fetch_contained_classes
$classes = $driver->fetch_contained_classes($id);The method returns an arrayref with all object classes that are contained within the specified object.
fetch_container
$attr = $driver->fetch_container($id);The method returns a hashref containing siam.object.id and siam.object.class attribute values of the object that is a container for the specified object.
The method returns undef if the specified object ID does not exist.
If the container is the SIAM root, only the siam.object.id attribute should be returned, with the value SIAM.ROOT.
fetch_object_ids_by_attribute
$list = $driver->fetch_object_ids_by_attribute($classname, $attr, $value);The method returns an arrayref with object identifiers of given class and a matched attribute value. Empty arrayref should be returned if no objects match the criteria.
set_condition
$driver->set_condition($id, 'torrus.import_successful', 1);The method interprets a (key, value) pair that the client application sets as a new condition for an object. The driver is free to do anything with this data.
manifest_attributes
my $manifest = $driver->manifest_attributes();The method returns an arrayref with all attribute names introduced by the driver.
LICENSE AND COPYRIGHT
Copyright 2011 Stanislav Sinyagin.
This program is distributed under the MIT (X11) License: http://www.opensource.org/licenses/mit-license.php
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.