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. The contents of the hash are solely 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 (object.id and 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. The failure details should be available through its error and errmsg methods.
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' => [ '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 object.id and 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 object.id attribute should be returned, with the value SIAM.ROOT.
errmsg
Returns the last error message in case of a failure. The method must return an empty string if there are no errors.
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.