Build Forge Perl API Guide By Riccardo Spoglia

Build Forge
Perl API Guide
By Riccardo Spoglia
[email protected]
Ver. 1.0
16 Apr 2008
5/7/2008
Table of Contents
Perl API Guide ................................................................................................................................. 2
Introduction .................................................................................................................................. 2
Architecture .................................................................................................................................. 2
Getting Started ............................................................................................................................. 4
Connection Class ......................................................................................................................... 5
General Patterns .......................................................................................................................... 6
General Patterns - Find................................................................................................................ 6
General Patterns - Create............................................................................................................ 6
General Patterns - Update ........................................................................................................... 7
General Patterns - Delete ............................................................................................................ 7
Sample Code ............................................................................................................................... 9
Connecting to BuildForge......................................................................................................... 9
Creating a Server ................................................................................................................... 10
Finding a Server ..................................................................................................................... 11
Deleting a Server.................................................................................................................... 12
Firing a Build........................................................................................................................... 12
Copyright IBM Corporation 2008
Perl API Guide
Introduction
The new Perl API version was made available in the Build Forge release 7.0.2 to enable
metadata configuration and runtime control by native Perl programmatic clients:
Metadata examples : Collector creation, Project modification, User deletion
Runtime control examples : Executing or canceling a build
It allows a programmatic interaction with the engine for the execution of projects and
management of Build Forge data.
The API’s documentation serves its purpose as a comprehensive reference but it does not
provide any guidance on usage patterns.
This document intends to complement the reference material, constituting a guide to the API
usage by describing its architecture, installation procedure, main transactions and providing
sample code to exemplify the main concepts.
Architecture
Build Forge release 7.0.1 introduces a Services Layer that runs in the context of the Apache
Tomcat Servlet Engine.
Both the Java API and the new Perl API (as opposed to the 7.0 PERL API, which still ships with
the Build Forge product) are built on top of this new Services Layer, as illustrated below.
Notice that this layer can only be accessed through the APIs as it does not have an interface that
can be invoked through the SOAP protocol.
Copyright IBM Corporation 2008
The main differences between the new Perl API (release 7.0.1) and the old Perl API (release 7.0)
can be summarized as follows:
Connected To:
Old API: Connects to UI for command processing
New API: Connects to the services layer database wrapper
Speed Enhancements:
Old API: As a result of the UI connection and PHP processing, extremely slow
New API: Can perform hundreds of operations per second
Consistency:
Old API: Operates through its own sub-UI moved forward from 3.8 which is
inconsistent with the rest of the product
New API: The services layer mandates consistent code paths which all portions
of the Build Forge product use or will be using in the not-terribly-distant future.
Copyright IBM Corporation 2008
Getting Started
A Perl 5.8 or higher interpreter is required to run the API code:
- Windows: ActivePerl – http://www.activestate.com/store/activeperl/download
- Linux – a Perl interpreter is included in most Unix / Linux distributions
The API uses certain prerequisite modules:
Exporter
LWP::UserAgent
HTTP::Request
You can get and install, from http://www.cpan.org/, the necessary Perl modules.
The Perl API client library is also required. The zip file containing the client library and the
documentation may be obtained from any installed Build Forge console at the following URLs:
JAR File : http://installedBuildForgeHost/clients/perl/rbf-services-client-perl.zip
PerlDoc : http://installedBuildForgeHost/clients/perl/docs/
Perl API client library installation example:
- Download rbf-services-client-perl.zip (http://localhost:8081/clients/ -> Perl Client) and unzip it;
- If you have Visual Studio (this step is intended to get a “make” environment; alternatively any
other “make” environment is ok): cd C:\Program Files\Microsoft Visual Studio 8\VC\bin
and execute vcvars32.bat;
- cd rbf-services-client-perl: (read README.txt)
and execute:
perl Makefile.PL
nmake
nmake install
- Alternatively:
copy the contents of rbf-services-client-perl into the local perl library directory such as
\perl\lib\ for Windows and /usr/lib/perl5/site_perl/5.8/ for Unix.
Copyright IBM Corporation 2008
Connection Class
The class com BuildForge::Services::Connection is the starting point of the programmatic
interface.
This is the initial object that needs to be created in the model objects’ constructors,
to establish and authenticate a connection between the API client and the Services Layer server.
Model Objects
The Model Object constructors class has the following form:
BuildForge::Services::DBO::*
Nearly every concept you’ve already seen in the UI is mirrored in model objects
Collector
Selector
Project
Build
Adaptor
Connection Example
The following code snippets connect an API client to a Services Layer server and authenticates
with the default root credentials:
Connect to localhost on port 3966
my $conn = new BuildForge::Services::Connection();
$conn->authUser("root", "root");
Connect to the specified host on port 3966
my $conn = new BuildForge::Services::Connection(“myhost”);
$conn->authUser("root", "root");
Connect to the specified host on the specified port
my $conn = new BuildForge::Services::Connection(“localhost”, 1234);
$conn->authUser("root", "root");
The “conn” object can then be passed as arguments to constructors or search class methods, as
discussed in the subsequent sections.
Copyright IBM Corporation 2008
General Patterns
The Perl API is based very strongly on the Java API:
almost every operation in one will be mirrored in the other.
All functions that return multiple objects will return a reference to an array of the object.
API objects follow common patterns for major operations such as:
- Find
Find single object by identifier
Find multiple objects by key
Find all objects
- Create
Local object creation followed by a series of setXXX() methods followed by a
create() call
- Update
Series of setXXX() methods followed by an update() call
- Delete
Simply a delete() call on a live object
General Patterns - Find
Each model object provides at least a find-single-object-by-identifier call, most provide additional,
object-specific finders
Finding a single object by identifier:
my $foundSelector = BuildForge::Services::DBO::Selector->findById($conn,
“mySelectorName”);
Finding multiple objects by identifier:
my $myProjectsBuilds = BuildForge::Services::DBO::Build->findByProjectId($conn,
$myIntegerProjectId);
Finding every object of a certain type:
my $allCollectors = BuildForge::Services::DBO::Collector->findAll($conn);
Note: In general, the findAll methods will return abbreviated data. For instance, Collector objects
contain CollectorProperty objects. In the interests of performance and scalability, these child
objects will never be returned with the parents from a findAll call. Instead, the returned parent
identifiers may be used to retrieve the entire object via a findById call, for example:
my $allCollectors = BuildForge::Services::DBO::Collector->findAll($conn);
my $fullyLoadedCollector = BuildForge::Services::DBO::Collector->findById($conn,
$allCollectors->[0].getCollectorName());
General Patterns - Create
Copyright IBM Corporation 2008
Local object creation
my $server = new BuildForge::Services::DBO::Server($conn);
Local object creation
$server->setActive(true);
$server->setHost(“localhost”);
$server->setLevel(1); // Guest access
$server->setName(“MyLocalhostServer”);
$server->setPath(“/builds”);
Call create()
$server->create();
In general, where applicable, generated primary keys will be available after creation
my $server2 = new BuildForge::Services::DBO::Server($conn);
// ‘server2’ has an unset identifier
print(“Server2 id is : “ . $server2->getServerId() . “\n”); // Prints ‘0’
$server2->create();
print(“Server2 id is : “ . $server2->getServerId() . “\n”); // Prints generated ID
General Patterns - Update
Obtain ‘live’ object (new does not suffice)
After create
$myNewServer->create();
// $myNewServer is now a ‘live’ object and may be updated
Via finder
my $myProject = BuildForge::Services::DBO::Project->findByName($conn, “myProjectName”);
// Any object returned by a finder will be ‘live’ and ready for update
Set new data
$myNewServer->setPath(“/newBuildPath”);
Call update()
$myNewServer->update();
General Patterns - Delete
Obtain ‘live’ object (same as Update)
Call delete()
$myNewServer->delete();
Copyright IBM Corporation 2008
Some objects provide specialized deletion methods for convenience
Register
deleteAllRegistersByBuild(BuildForge::Services::Connection, int)
deleteAllRegistersByProject(BuildForge::Services::Connection, int)
Copyright IBM Corporation 2008
Sample Code
This section illustrates the usage of the API through complete Perl programs to perform some
useful common tasks like connecting to a BuildForge instance, creating a new server, finding and
deleting an existing one and firing a build. The same methods can be applied to any other object
as “Projects”, “Libraries”, etc.
The programs below compile and work correctly but are not at the required quality level for
customer deployment since they do not catch exceptions and do not accept input for parameters
like user login.
In order to run the programs copy the code in a <file>.pl and execute the command:
perl <file>.pl
Connecting to BuildForge
use BuildForge::Services;
sub BFconnect {
my $conn = new BuildForge::Services::Connection();
}
BFconnect();
Copyright IBM Corporation 2008
Creating a Server
use BuildForge::Services;
sub createServer {
#CODE FOR CONNECTING TO BUILDFORGE
my $conn = new BuildForge::Services::Connection();
$conn->authUser("root", "root");
#CODE FOR CREATING SERVER
$server = new BuildForge::Services::DBO::Server($conn);
$server->setName("Api_Server");
$server->setHost("localhost");
$server->setLevel(1);
$server->setPath(“/builds”);
# OTHER SERVER OPTIONS ON THE API DOC’s
# $server->setActive(isActive)
# $server->setAuthId(authId)
# $server->setCollectorId(collectorId)
# $server->setEnvironmentId(envGroupId)
$server->create();
}
createServer();
Copyright IBM Corporation 2008
Finding a Server
use BuildForge::Services;
sub findServer {
#CODE FOR CONNECTING TO BUILDFORGE
my $conn = new BuildForge::Services::Connection();
$conn->authUser("root", "root");
#CODE FOR FINDING SERVER
$server = BuildForge::Services::DBO::Server->findByName($conn, "Api_Server");
if ($server) {
#check if the server exists
my $SVR_ID = $server->getServerId();
$server->getName();
# OTHER SERVER OPTIONS ON THE API DOC’s
# $server->getHost()
# $server->getActive()
# $server->getAuthId()
# $server->getCollectorId()
# $server->getEnvironmentId()
# $server->getLevel()
# $server->getPath()
# $server->getPublish()
# $server->getTestText()
# $server->getUpstate()
# $server->getError()
# $server->getManifest()
print "Server Info: " .$SVR_ID;
#print "Server Info: " .$server->getServerId();
}
}
findServer();
Copyright IBM Corporation 2008
Deleting a Server
use BuildForge::Services;
sub deleteServer {
#CODE FOR CONNECTING TO BUILDFORGE
my $conn = new BuildForge::Services::Connection();
$conn->authUser("root", "root");
#CODE FOR DELETING SERVER
$server->setName("Api_Server");
$server->delete();
}
deleteServer();
Firing a Build
use BuildForge::Services;
sub fireBuild {
#CODE FOR CONNECTING TO BUILDFORGE
my $conn = new BuildForge::Services::Connection();
$conn->authUser("root", "root");
#CODE FOR FINDING A PROJECT (ECS)
$project = BuildForge::Services::DBO::Project->findByName($conn, "ECS");
if ($project) {
#check if project exists
my $Prj_id = $project->getProjectId();
#CODE FOR FIRING BUILDS
$build = BuildForge::Services::DBO::Build->fire($conn, $Prj_id);
}
}
fireBuild();
Copyright IBM Corporation 2008