CaliberRM SDK User Guide - Micro Focus · This document provides the necessary information for Visual Basic and Java programmers to get started with the Caliber APIs. Note: ... 2010,

Caliber™

11.1.0

SDK Programmer’s Guide

Micro Focus may have patents and/or pending patent applications covering subject matter inthis document. The furnishing of this document does not give you any license to these patents.

Copyright © 2013 Micro Focus. All rights reserved. Portions Copyuright (c) 1998-2009 BorlandSoftware Corporationi (a Micro Focus company). All other marks are the property of theirrespective owners. All Micro Focus brand and product names are trademarks or registeredtrademarks of Micro Focus in the United States and other countries. All other marks are theproperty of their respective owners.

CRM06-SDKPG

Chapter 1: Introduct ion 1

C h a p t e r

Chapter1IntroductionCaliber promotes extensibility through the Caliber Software Development Kit (SDK) and a traceability add-in API.

Caliber SDK

Using the Caliber SDK, you can create, modify and delete Caliber information, such as projects, baselines, requirements, users, and groups. The Caliber SDK gives you access to all requirements data in Caliber through programs written in Java and any other programming language that supports .NET or COM.

This document provides the necessary information for Visual Basic and Java programmers to get started with the Caliber APIs.

Note: Detailed programmer’s documentation in Javadoc format is available at Program Files\Borland\Caliber SDK <version>\api\index.html or contact Borland support for additional information.

Important: If your existing SDK application must connect to a server not yet upgraded to this release, do not recompile your application with the SDK included in this release. In general when writing SDK applications, use the same version of the SDK as the version of the oldest server you need the application to connect to. You must recompile your .NET/COM SDK applications to make use of the new SDK functionality (create and assign security profiles, get/set user LDAP DN) provided in this release, and the recompiled application will be compatible with this release of the server.

For more information about creating SDK applications, refer to Using Visual Basic to Write SDK Applications and Using Java to Write SDK Applications sections in this guide.

Traceability Add-In Technology

Caliber provides a unique way to extend your traceability information with any third party tools using its traceability add-in technology. You can create a traceability add-in to provide traceability to an external application. For example, creating a traceability add-in for Microsoft Project, allows you to easily define and manage real-time traces from requirements in Caliber to Tasks in Project. Once the trace has been created, you

2 Cal iberRM SDK Programmer’s Guide

can view it in the Traceability Matrix, Traceability Diagram, and report on it with Document Factory.

For more information about creating a traceability add-in refer to the Creating a Traceability Add-in for Caliber section in this guide.

More Information

If you require assistance with the Caliber SDK, please post your request in the Caliber SDK Newsgroup at news://newsgroups.borland.com/borland.public.caliber-rm.sdk.

If you need to report a problem with the Caliber SDK, please contact support at http://support.borland.com/.

Chapter 2: Using Visual Basic to Wri te SDK Appl icat ions 3

C h a p t e r

Chapter2Using Visual Basic to WriteSDK Applications

Introduction

This chapter introduces the Caliber Software Development Kit (SDK) for Visual Basic programmers. This chapter:

? describes the steps needed to set up your IDE to use the Caliber SDK,

? explains the way programmers can use the SDK to connect to a Caliber server,

? describes how Caliber information can be created, modified and deleted,

? provides an overview of working with requirement trees, attributes and history,

? presents an introduction to working with Caliber discussions,

? explains how programmers can utilize the SDK to view, create and delete trace relationships.

Setting up Your IDE

To use the Caliber SDK in your project, you need to set a reference to the SDK’s object library in your IDE.

Visual Studio 6.0

1 Click Project > Reference... on the main menu.If you have successfully installed the Caliber SDK, you should see a reference named Caliber library in the list of available references.

2 Select Caliber library and click OK to save the changes.

3 If you cannot see a reference named Caliber library in the list of references, click Browse and locate the CaliberSDK DLL file on your hard disk. (Typically, the library is located in Program Files\Borland\Caliber SDK <version>\api\lib folder and the name of the library file is CaliberSDK<version>.dll.)

4 Click OK in the References dialog box.


Visual Studio .NET 2003

1 Click Project > Add Reference... on the main menu.

2 Click the Browse button in the Add Reference dialog box.

3 Locate Caliber SDK library on your hard disk and click Open. (Typically, the library is located at Program Files\Borland\Caliber SDK <version>\api\lib folder and the name of the library file is CaliberSDK<version>.NET.dll.)

4 Click OK in the Add Reference dialog box.

Visual Studio 2005, 2008, 2010, 2012

1 Click Project > Add Reference... on the main menu.

2 Click the Browse tab in the Add Reference dialog box.

3 Locate Caliber SDK library on your hard disk and click OK. (Typically, the library is located at Program Files\Borland\Caliber SDK <version>\api\lib folder and the name of the library file is CaliberSDK<version>.NET.dll.)

4 Click OK in the Add Reference dialog box.

To check if the reference to Caliber SDK is correctly set, perform the following:

1 Click Project > Test VBNET Properties on the main menu.

2 Click the References tab. You should see CaliberSDK<version>.NET in the References pane.

Now you can use CaliberSDK library in your code. Make sure you import Caliber SDK classes in your code as follows:

Initializing the Caliber Library

Whenever the COM SDK is launched, the SDK launches a Java Virtual Machine (VM). The code in this section must be called prior to any other SDK calls because once the VM is loaded these options cannot be set.

COM applications can utilize the SDK’s Initilizer and IStJavaVMInfo objects, for example:

Imports Starbase.Caliber.Interop

' The Initializer object is responsible for loading the Java VM. Dim objInitializer As New Initializer 'IStJavaVMInfo describes a Java VM. Dim objStJavaVMInfo As IStJavaVMInfo ' Get the current VM from the initializer... Set objStJavaVMInfo = objInitializer.JavaConfiguration.CurrentJavaVM ' Set the max memory flag to 1000 MB...

objStJavaVMInfo.Options = "-Xmx1000M"


Note: By default, most VMs can only consume a maximum of 64 MB of memory. This limit can be overridden by setting the VM’s maximum memory flag (Xmx).

Specify the maximum size, in bytes, of the memory allocation pool. This value must be a multiple of 1024 greater than 2MB. Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes. The default value is 64MB. For example:

? -Xmx83886080

? -Xmx81920k

? -Xmx80m

If the application is not able to start Java VM and you get a Not enough space for object heap error, decrease the JVM heap size. Generally, you must specify the memory size for Java VM according to the available memory on you computer.

Connecting To a Caliber Server

The first step to using the Caliber SDK is creating a connection to a Caliber server. To establish a connection, you need to create a reference to a CaliberServer object. Simply put, a CaliberServer object is used to establish and maintain a connection with a Caliber server on behalf of a Caliber user.

In the following code, a simple Visual Basic application is created that connects to a Caliber server:

Notice in the above example that creating a Caliber server reference is a two-step process. First, you must create a Caliber server factory:

' Declare object variables for Caliber ' server factory, server and session objects. Dim objServerFact As CaliberServerFactory Dim objServer As CaliberServer Dim objSession As Session ' Assign object references to the server and ' server factory variables. Set objServerFact = New CaliberServerFactory Set objServer = objServerFact.Create(“localhost”)

' Assign an object reference to the session ' variable by logging in to the Caliber server. Set objSession = objServer.login(“admin”, “admin”)

Set objSrvrFctry = New CaliberServerFactory


Second, you should use the server factory to produce a new server reference:

Using Sessions

A Session object represents a user’s view of the Caliber and, as such, provides an entry point into the Caliber object model. In the previous example, we created a Session by logging in to a CaliberServer object. In the following code, we will use this Session to display the names of all projects available to the user.

Creating Caliber Objects

The Caliber SDK allows you to create, modify and delete the following objects:

? Projects

? Baselines

? Users

? Groups

? Departments

? Requirements

? Requirement Types

? Security Profiles

? Glossaries

? Glossary Terms

? Integrations

To create most Caliber information, complete the following steps:

1 Create a factory that will produce the new object.

2 Call the factory’s Create method.

3 Call the new object’s Save method.

Set objServer = objSrvrFctry.Create(“localhost”)

' Declare object variable for a Caliber Project. Dim objProject As Project

'Iterate through each Project in the session. For Each objProject In objSession.Projects Debug.Print objProject.Name Next objProject


The following sample follows these steps to create a new User object.

Modifying Caliber Objects

To modify a Caliber object, complete the following steps:

1 Obtain an instance of a Caliber object.

2 Call the object’s Lock method.

3 Set one or more of the object’s properties.

4 Call the object’s Save method.

See the example on the following page.

' Create a factory that will be used to produce new User objects. Set objUserFactory = New UserFactory

' Create a new User object. Set objNewUser = objUserFactory.Create(“jdoe”, objSession)

' Set the properties of the new User object. objNewUser.FirstName = “John” objNewUser.LastName = “Doe” ' Save the new User object. objNewUser.save

' Get a Group object. Set objGroup = objSession.Groups.Item(2) ' Lock the Group. objGroup.lock ' Modify the Group's properties. objGroup.Name = “New Name” objGroup.EmailAddress = “New Email Address” objGroup.Description = “New Description” ' Save the modified Group. objGroup.save


Deleting Caliber Objects

You can delete a CaliberObject from Caliber by calling its Remove method. For example:

Note that the Remove method only deletes a requirement from the current baseline. The requirement is not removed from any previous baselines.

Requirements

This section details creating, modifying and deleting requirements.

Creating Requirements

SDK provides two methods for creating new requirements. The first method allows you to create requirements at the top level of a project’s requirement tree hierarchy. The second is used to create children of an existing requirement.

In the following example, the first create method (Create1) is used to create a new requirement.

In the previous example, notice that a zero is passed as the 4th parameter to Create1. This indicates the index in the project’s requirement tree where this new requirement is inserted.

Dim objRequirement As RequirementSet objRequirement = objSession.getRequirement(1)objRequirement.remove

' Get the first Project in the session's collection Set objProject = objSession.Projects.Item(0) ' Get the first Requirement Type in the project. Set objType = objProject.CurrentBaseline.RequirementTypes.Item(0) ' Create a factory for new Requirement objects. Set reqFactory = New RequirementFactory ' Create a new Requirement. Set newRequirement = reqFactory.Create1( _

“New Requirement”, _ objProject, _ objType, _ 0, _ objSession) newRequirement.save ““


The following example illustrates how the second create method (Create2) is used to create a requirement that is a child of an existing requirement.

Attributes and Attribute Values

Caliber allows you to define requirements with any number of user-defined attributes (UDAs.) Additionally, all requirements contain a Status and Priority system attribute. Likewise, in the Caliber SDK, a Requirement object provides Status, Priority, and AttributeValues properties that return its Status, Priority and UDAs values respectively.

In the Caliber SDK, Attribute objects represent a type of Caliber attribute while AttributeValue objects represent an instance of a type.

The following table describes the relationship between Caliber Attributes and the SDK’s Attribute and AttributeValue objects.

Caliber Attributes SDK AttributeSDK

AttributeValue

Single Text Line

Multiple Line Text Field

UDAText UDATextValue

Long Integer UDAInteger UDAIntegerValue

Duration UDADuration UDADurationValue

Float UDAFloat UDAFloatValue

Date UDADate UDADateValue

Boolean UDABoolean UDABooleanValue

Multiple Selection List

Single Selection List

Multiple Selection Group List Single Selection Group List Multiple Selection User List Single Selection User List

UDAList UDAListValue

' Create a factory for new Requirement objects. Set reqFactory = New RequirementFactory

' Get a Requirement that will be a parent of the new Requirement. Set parentReq = objSession.getRequirement(1) ' Create a new Requirement that will be a child of parentReq Set newChildRequirement = reqFactory.Create2( _

“New Child Requirement”, _ parentReq, _ 4, _ objSession)


The following code shows how Attribute objects are obtained from a requirement type:

Likewise, you can obtain AttributeValue objects from a requirement. The following example displays the same list as the previous example but also adds the value:

Notice in this example the AttributeValue’s attribute property to obtain the name is used:

' Get the first Requirement Type in the session.Set objRequirementType = objSession.RequirementTypes.Item(0)

' Get the first Custom Tab in the Requirement TypeSet objCustomTab = objRequirementType.CustomTabs.Item(0)

' Print the name of the Attributes assigned to the Custom TabDim objAttribute As Caliber.AttributeFor Each objAttribute In objCustomTab.attributes Debug.Print vbTab & vbTab & objAttribute.NameNext objAttribute

Dim objAttribValue As AttributeValue

' Loop through all attribute values For Each objAttribValue In objRequirement.AttributeValues ' Print the name of the attribute and it's value Debug.Print _

objAttribValue.Attribute.Name _ & “ = “ _ & objAttribValue.Value

Next objAttribValue

objAttribValue.Attribute.Name


You can use this property any time you need to obtain an AttributeValue’s type. The example below illustrates dealing with a certain type of Attribute and AttributeValue.

List Attributes Values

As previously mentioned, a UDAListValue object embodies all list attribute values that are assignable to a requirement. This section contains practical examples that show how a UDAListValue object can be used to display single and multiple selection lists.

' Loop through all attribute values. For Each objAttribValue In objRequirement.AttributeValues

' Look for a UDATextValue. If TypeOf objAttribValue Is UDATextValue Then

' Cast the AttributeValue to a UDATextValue. Dim textValue As UDATextValue Set textValue = objAttribValue

' Cast the Attribute to a UDAText. Dim textAttribute As UDAText Set textAttribute = objAttribValue.Attribute

' Print information specific to the value. Debug.Print _ “The value of the UDATextValue is: “ _ & textValue.Value

' Print information specific to the value's type. Debug.Print _ “The maximum length this value can be: “_ & textAttribute.MaximumLength

Debug.Print _ “The minimum length this value can be: “_ & textAttribute.MinimumLength End If

Next objAttribValue


The example below displays the list entries and selected value of a requirement’s status list.

This code can be modified to display a Single Selection User List:

Notice in the above example a Single Selection User List is singled out from a collection of attributes by comparing the UITypeName property of its attribute against the UI_NAME_SSL constant:

Private Sub Form_Load() ... Dim objRequirement As Requirement Set objRequirement = objSession.getRequirement(1) PrintList objRequirement.StatusEnd Sub

Private Sub PrintList(objListValue As UDAListValue) ' Print the list entries Debug.Print “List Entries(s):” Dim listEntry As UDAListEntry For Each listEntry In objListValue.ListEntries Debug.Print listEntry.Object Next listEntry ' Print the selected value Debug.Print “Selected Value = “& objListValue.selectedValueEnd Sub

Private Sub PrintSSUserList(objReq As Requirement) Dim objAttribValue As Caliber.AttributeValue ' Iterate through all attributes associated with the ' supplied Requirement For Each objAttribValue In objReq.AttributeValues ' Only print “Single Selection User List” attributes. Set objAttribute = objAttribValue.Attribute If objAttribute.UITypeName = objAttribute.UI_NAME_SSUL Then ' Print the user list entries Debug.Print “User List Entries(s):”

Dim listEntry As UDAListEntry For Each listEntry In objAttribValue.ListEntries Debug.Print listEntry.Object.Name Next listEntry Debug.Print “Selected Value: “ & _ objAttribValue.SelectedValue.Name End If Next objAttribValue End Sub

If objAttribute.UITypeName = objAttribute.UI_NAME_SSUL Then


However, you could select an attribute from the collection by name. For example:

The UDAListValue object can also represent Multiple Selection List values. For example, the following code prints out the Name and Selected property of each element in a Multiple Selection Group List value:

Setting Attribute Values

To modify a requirement’s attribute values, complete the following steps:

1 Obtain a requirement.

2 Call the requirement’s Lock method.

3 Determine the types of Attribute Values (i.e. UDATextValue, UDAListValue) the requirement contains.

4 Modify the requirement’s AttributeValue objects based on their type.

5 Update the requirement by setting its AttributeValue property to the new value.

6 Call the requirement’s Save method.

See the example on the following page.

If objAttribute.Name = "My SSUL Attribute" Then

Dim listEntry As UDAListEntry For Each listEntry In objAttribValue.ListEntries ' Use the 'Selected' property of the list entry to ' to determine if the group is selected If listEntry.Selected Then Debug.Print listEntry.Object.Name & “ *** Selected ***"“ Else Debug.Print listEntry.Object.Name End If Next listEntry


Requirement Descriptions

In Caliber, a requirement description can be either a text string or a participant in a mapped/shared description relationship. A requirement’s description is shared when it is used by other requirements. Conversely, a requirement’s description is mapped when the requirement uses another requirement description as its own.

The Caliber SDK provides three classes that represent the possible states for a requirement’s description: RequirementDescription, RequirementDescriptionMapped and RequirementDescriptionShared. All of these

Set objRequirement = objSession.getRequirement(1) objRequirement.lock ' Loop through all attribute values in the Requirement.Dim objAttribValue As AttributeValueFor Each objAttribValue In objRequirement.AttributeValues

If TypeOf objAttribValue Is UDABooleanValue Then' If value is a Boolean UDA Value then set the new' value to the opposite of the current value.objAttribValue.Value = Not objAttribValue.Value

ElseIf TypeOf objAttribValue Is UDATextValue Then

' If the value is a Text UDA Value then set the' new value equal to the current time.objAttribValue.Value = Time

ElseIf TypeOf objAttribValue Is UDAIntegerValue Then' If the value is a Integer UDA Value then increment' the value by one.objAttribValue.Value = objAttribValue.Value + 1

ElseIf TypeOf objAttribValue Is UDAListValue ThenIf objAttribValue.MaximumSelections = 1 Then' If the value is a Single Selection List Value then' increment the selected index by 1.objAttribValue.SelectedIndex = _

objAttribValue.SelectedIndex + 1End If

End If' Update the Requirement object with the new valueobjRequirement.AttributeValue = objAttribValue

Next objAttribValue ' Save the modified RequirementobjRequirement.save “Modifying UDA Values”


description objects contain a Text property that allows you to obtain the text of a description. Therefore, the following code snippet works for all requirements:

To modify a requirement’s description you simply set the requirement’s Description property to a new RequirementDescription or RequirementDescriptionMapped object. For example, the following code creates a simple text description (Lock and Save method calls have been omitted for clarity):

The following example creates a simple HTML description for the requirement.

In the next example, the description of Requirement #1 to Requirement #2 is mapped.

Document References

The Caliber SDK provides three types of Document Reference objects: FileReference, TextReference and WebReference. You can create each of these reference objects and add them to a requirement’s DocumentReferences property. The example on the following page creates an instance of each of these objects and uses these objects to modify a requirement.

Debug.Print req.Description.Text

' Create a factory that will produce descriptions. Dim descriptionFactory As New RequirementDescriptionFactory ' Create a new description object and use it to set the Requirement's' Description property.req.Description = descriptionFactory.Create(“A new description.”)

' Create a factory that will produce descriptions.Dim descriptionFactory As New RequirementDescriptionFactory ' Create a new description object and use it to set the Requirement's ' Description property.req.Description = descriptionFactory.Create(“<html><body>A new <i><b>formatted description.</b></i></body></html>”)

Set req1 = objSession.getRequirement(1)Set req2 = objSession.getRequirement(2)' Create a factory that will produce mapped descriptions. Dim mapDescriptionFactory As New RequirementDescriptionMappedFactory' Create a new mapped description and use it to set Requirement 1's' Description property. req1.Description = mapDescriptionFactory.Create(req2, objSession)


In the above example, notice that the first thing that was done was the creation of a new collection using CollectionFactory’s CreateByIStCollection method. This is necessary because a requirement’s DocumentReferences property is a read-only collection and cannot be modified.

Responsibilities

Typically, several individuals are assigned as responsible users for each requirement in Caliber. You can obtain these users, and their corresponding groups, through a requirement’s Responsibilities property which is a collection of GroupMemberAssignment objects.

' First, we must copy the Requirement's existing collection of' references into a collection that can be modified.Dim colFactory As New CollectionFactorySet docRefs = colFactory.CreateByIStCollection(req.DocumentReferences) ' Create and add a text reference to the docRefs collection.Dim textRefFactory As New TextReferenceFactorydocRefs.Add textRefFactory.Create("Text Reference") ' Create and add a web reference to the docRefs collection.Dim webRefFactory As New WebReferenceFactorydocRefs.Add webRefFactory.Create(“www.microsoft.com”) ' Create and add a file reference to the docRefs collection.Dim fileRefFactory As New FileReferenceFactorydocRefs.Add fileRefFactory.Create(“C:\foo.txt”) ' Set the references and save.req.lockreq.DocumentReferences = docRefsreq.save ““


The following code unassigns all users who are responsible for a requirement.

History

The Caliber SDK allows for complete access to requirement history records. To obtain a requirement’s history, you can use the History property of any Requirement object. The following code demonstrates how to use these objects to display history revisions:

Now we can expand this example to include information about the individual changes that comprise these revisions. The code on the following page iterates through all HistoryChange objects for a HistoryRevision, prints the name of the requirement field that changed, the type of change that occurred and the field’s old and new values.

' Get the collection of GroupMemberAssignment objects ' that comprise the Requirement's responsibilities. Dim gmaCollection As Caliber.Collection Set gmaCollection = req.responsibilities ' Iterate through all GroupMemberAssignment objects ' in the collection. Dim gma As GroupMemberAssignment For Each gma In gmaCollection 'Iterate through all assigned members... Dim assignedMember As User For Each assignedMember In gma.AssignedMembers ' ... and unassign each. gma.removeAssignedMember assignedMember Next assignedMember Next gma ' Lock the Requirement, set its responsibilities and save. req.lock req.responsibilities = gmaCollection req.save ““

Dim revision As HistoryRevision For Each revision In objReq.History.Revisions Debug.Print “Major Ver: “ & revision.Version.MajorVersion Debug.Print “Minor Ver: “ & revision.Version.MinorVersion Debug.Print “Date: “ & Format(revision.OLEDate, “d-mmm”) Debug.Print “User Name: “ & revision.UserName Debug.Print “Comment: “ & revision.Comment Next revision


The OldValue and NewValue properties of a Change object represent the value of a requirement field before and after a change occurs. To work with these objects, you need to separate them by type. As a rule, a change value object is one of the following three types:

? String: represents changes to non-UDA text fields such as a requirement’s name or description.

? Attribute: represents changes to all user-defined and system attributes.

? User: represents changes to a requirement’s owner field.

The following subroutine (called twice in the previous example) separates these OldValue and NewValue objects by String, Attribute and User.

Dim objChange As HistoryChange For Each objChange In revision.Changes Debug.Print “Field Name: “ & objChange.FieldName Debug.Print “Type: “ & ChangeTypeToString(objChange.changeType) Debug.Print “Old Value: “ & VariantToString(objChange.OldValue) Debug.Print “New Value: “ & VariantToString(objChange.NewValue) Next objChange

' Converts the specified variant to a string.Private Function VariantToString(ByVal vntValue As Object) As String

' Filter out any null changes. If IsNull(vntValue) Then VariantToString = “[NULL]”

' If its a string already then just return it. ElseIf VarType(vntValue) = vbString Then VariantToString = vntValue

Else ' “Narrow” the variant down to an object. Dim objValue As Object objValue = vntValue

' If the object is a CaliberObject then return it ' name attribute... If TypeOf objValue Is CaliberObject Then VariantToString = objValue.Name

' Print User Defined and System attribute changes. ElseIf TypeOf objValue Is AttributeValue Then VariantToString = UDAValueToString(objValue)

Else VariantToString = ““ End If

End IfEnd Function


Note that the first thing this code does is ensure the Variant passed into this subroutine is not null. Typically, a null change object emerges when a UDA has been added or removed from a requirement’s type.

Also note that the handler for AttributeValue objects calls the UDAValueToString function:

This conversion function (listed below) illustrates how different types of AttributeValue objects can be handled in a generic manner.

Discussions

Caliber allows project teams to provide feedback on requirements and projects through its Group Discussion feature. Likewise, the Caliber SDK allows programmers to view discussions about requirements and projects.

The following subroutine takes a CaliberObject and displays information about each of its discussion messages. This is accomplished by using the Discussion property for the specified CaliberObject. Note that this subroutine exits if this CaliberObject is not a

ElseIf TypeOf objValue Is AttributeValue Then VariantToString = UDAValueToString(objValue)

' Converts an AttributeValue (also know as UDA Value) to a String.Function UDAValueToString(ByVal objValue As AttributeValue) As String

' First, handle all AttributeValue objects whose ' “Value” attribute converts easily to a string... If TypeOf objValue Is UDABooleanValue _ Or TypeOf objValue Is UDAFloatValue _ Or TypeOf objValue Is UDAIntegerValue _ Or TypeOf objValue Is UDATextValue Then UDAValueToString = objValue.Value

ElseIf TypeOf objValue Is UDADateValue Then UDAValueToString = Format(objValue.OLEDate, “d-mmm”)

ElseIf TypeOf objValue Is UDADurationValue Then UDAValueToString = objValue.Value _ & objValue.Attribute.GranularityTextElseIf TypeOf objValue Is UDAListValue Then UDAValueToString = “Selected List Entries: “ For Each objListEntry In objValue.ListEntries If objListEntry.Selected = True Then UDAValueToString = UDAValueToString & _ VariantToString(objListEntry.Object) & _ “,” End If Next objListEntry End If

End Function


Requirement or Project object since only requirements and projects can have discussions.

The Caliber SDK also allows you to post discussion messages through the Discussion object’s postMessage method. Likewise, you can reply to discussion messages by using DiscussionMessage’s postReply method. The following example illustrates the use of these two methods.

Requirement Trees

Typically, hierarchical relationships exist between sets of requirements in a Caliber baseline. Taken together, these requirements comprise a Requirement Tree. The RequirementTree and RequirementTreeNode objects provide valuable options for working with these trees.

You can traverse the nodes of a Requirement Tree by:

1 Obtaining a RequirementTree object from a baseline.

2 Accessing the RequirementTree’s Root property to obtain the root RequirementTreeNode.

3 Recursively calling the RequirementTreeNode’s Children property.

Private Sub PrintDiscussion(objCaliberObj As CaliberObject) ' Only Projects and Requirements can have discussions. If Not TypeOf objCaliberObj Is Project _ And Not TypeOf objCaliberObj Is Requirement Then Exit Sub End If Dim objDiscussion As Discussion Set objDiscussion = objCaliberObj.Discussion Dim objMessage As DiscussionMessage For Each objMessage In objDiscussion.Messages intTab = objMessage.Depth * 5 Debug.Print Tab(intTab); “Subject: “ & objMessage.Subject Debug.Print Tab(intTab); “Have read: “ & objMessage.Read Debug.Print Tab(intTabDepth); “Date: “ & _ Format(objMessage.OLEDate, “d-mmm”) Next objMessage End Sub

' Get a Requirement's discussion. Set objDiscussion = req.Discussion ' Post a message to the discussion. Set objMessage = objDiscussion.postMessage(“My Subject”, “My Message”) ' Post a reply to the new message. objMessage.postReply “Re: My Subject”, “My Reply”


The following code follows these steps to print out information about each and every node in a Requirement Tree.

A RequirementTreeNode can represent either a project, requirement type or requirement node in a Requirement Tree. A RequirementTreeNode object contains the minimum data necessary to represent the Caliber object that it is associated with. For example, if a node is associated with a Project object then you can obtain the project’s name and ID number through RequirementTreeNode; however, you cannot directly obtain the project’s description and baselines.

... ' Get baseline's requirement tree... Dim objRequirementTree As RequirementTree Set objRequirementTree = objBaseline.RequirementTree

' Traverse the tree starting at the root node... TraverseTree objRequirementTree.Root End Sub

' Traverses the subtree rooted at the specified node depth-first ' and prints information about each node. Private Sub TraverseTree(ByVal parent As RequirementTreeNode)

' Print information about the parent node... Debug.Print _ String(parent.Level, vbTab) _ & parent.HierarchyNumber _ & “ “ _ & parent.Name _ & “ “ _ & parent.SerialNumberTag

' Recursively call this function for ' each of the parent's children... Dim child As RequirementTreeNode For Each child In parent.Children TraverseTree(child) Next child

End Sub


To obtain the full object that is associate with a RequirementTreeNode, you should use RequirementTreeNode’s AssociatedObjectID property. For example:

You can modify a requirement tree using RequirementTreeNode’s addChild and insertChild methods. The following example uses the addChild method to add the second requirement node in a requirement tree to the first requirement node.

You can also traverse requirement trees using a baseline’s Requirements collection in conjunction with the requirement’s ChildRequirements collection. It should be noted, however, that this method of tree traversal is significantly more resource intensive than using RequirementTree and RequirementTreeNode because you are requesting the entire Requirement objects from the remote Caliber server.

The example on the following page uses these collections to display the first two levels of a requirement tree.

' Get the ID of the CaliberObject that the node represents Dim id As CaliberObjectID Set id = objRequirementTreeNode.AssociatedObjectID

' Get the CaliberObject that the node represents Dim co As CaliberObject Set co = objSession.get(id) ' Print an attribute specific to the CaliberObject subtype... If TypeOf co Is Project Then ' Print the Project's Description Debug.Print co.Description

ElseIf TypeOf co Is RequirementType Then ' Print the Type's Tag Debug.Print co.Tag

ElseIf TypeOf co Is Requirement Then ' Print the Requirement's Description Debug.Print co.Description.Text End If

... ' Get the project node. This will always be the root node. Set objProjectNode = objRequirementTree.Root

' Get the first Requirement Type node under the project node. Set objTypeNode = objProjectNode.Children.Item(0) ' Get the first and second Requirements under the Requirement Type. Set firstRequirementNode = objTypeNode.Children.Item(0) Set secondRequirementNode = objTypeNode.Children.Item(1)

' Add the second Requirement to the first. firstRequirementNode.addChild secondRequirementNode

' Save the changes to the tree. objRequirementTree.save


You can also traverse from child to parent by using a requirement object’s ParentRequirement property. For example, the following procedure prints the path from a given requirement to the root requirement in its tree.

Traditionally, Caliber applications have displayed all top-level tree requirements as grouped and sorted by requirement type; therefore, the Requirements property of a Baseline object always returns requirements sorted and grouped this way.

Note: You can determine a requirement’s project, baseline and type by accessing its Project, Baseline and Requirement Type properties respectively.

Traceability

In Caliber, a trace relationship can exist between two requirements and between a requirement and an object external to Caliber. Similarly, the Caliber SDK supports the creation, deletion and modification of traces between both Caliber requirements and non-requirements software artifacts.

' Declare variables for Project and Baseline objects. Dim firstProject As Project Dim curBaseline As Baseline ' Set the Project variable to reference the first ' Project in the Session's collection of Projects. Set firstProject = objSession.Projects.Item(0) ' Set the Baseline variable to reference the ' "Current" Baseline in the first Project. Set curBaseline = firstProject.CurrentBaseline

' Declare a variable that will temporarily hold ' the first level of Requirements in the tree Dim parentReq As Requirement' Iterate through the first level of Requirements For Each parentReq In curBaseline.Requirements Debug.Print parentReq.Name Dim childReq As Requirement ' Iterate through all children of ' the current parent Requiremennt For Each childReq In parentReq.ChildRequirements log vbTab & childReq.Name Next childReq

Next parentReq

Private Sub PrintPathToRoot(ByVal objRequirement As Requirement) Do While Not objRequirement Is Nothing Debug.Print objRequirement.Name Set objRequirement = objRequirement.ParentRequirement Loop End Sub


Some of the more important trace-related objects are:

? Trace: represents a trace relationship between two Caliber objects. These Caliber objects can be requirements or objects that reside outside Caliber.

? TraceManager: provides the functionality for creating, modifying and deleting traces.

? XGenericObjectManager: provides the functionality for creating traces between requirements and non-requirements software artifacts.

? VendorAddIn: represents a reference to an object that resides within the realm of another application. Software vendors whose applications implement Caliber’s Traceability add-in module supply these objects.

Obtaining Traces

The Caliber SDK allows you to retrieve traces at many levels of the Caliber object model. For instance, the Session object provides a Traces property that returns all traces between all Caliber objects available to you. Furthermore, the Traces property of a Project object returns all traces that trace to or from the requirements that it contains. Finally, the Requirement object provides two properties for getting traces: TracesFrom and TracesTo.

The following example uses these TracesTo and TracesFrom properties to print out the names of objects tracing to or from a requirement.

Creating Traces Between Requirements

The TraceManager object allows for the creation and modification of trace relationships. The first step in creating a trace is to obtain a reference to this object:

Private Sub PrintTraces(objRequirement As Requirement) Dim objTrace As Caliber.Trace Debug.Print “Objects tracing from “ & objRequirement.Name For Each objTrace In objRequirement.TracesFrom ' The following Trace is to our Requirement ' FROM some other object. Debug.Print objTrace.FromObject.Name _ & vbTab _ & objTrace.Suspect Next objTrace Debug.Print “Objects tracing to “ & objRequirement.Name For Each objTrace In objRequirement.TracesTo ' The following Trace is from our Requirement ' TO some other object. Debug.Print objTrace.ToObject.Name _ & vbTab _ & objTrace.Suspect Next objTrace End Sub

Dim objTraceManager As TraceManager Set objTraceManager = objSession.TraceManager


Once you have obtained a TraceManager, you can use it to create traces. The following example creates a trace relationship between two requirements.

Creating Traces to Non-Requirements Software Artifacts

The previous example showed how a trace relationship could be created between two objects (both requirements) that reside within Caliber. The following example uses the XGenericObjectManager object to create a trace between a requirement and an object that resides outside of Caliber.

The XGenericObjectManager also provides a function for creating traces between two external VendorAddIn objects.

Dim req1 As Requirement Set req1 = objSession.getRequirement(1) Dim req2 As Requirement Set req2 = objSession.getRequirement(2)

objTraceManager.createTrace3 req1, req2, False

... Dim req1 As Requirement Set req1 = objSession.getRequirement(1) Dim objIntegrationMgr As IntegrationManager Set objIntegrationMgr = objSession.IntegrationManager ' Create a trace from req1 to the ABCObject provided ' by the ABCCorp objIntegrationMgr. createTrace2 _ req1, _ True, _ "ABCCorp", _ “ABCObjectID” ...

objIntegrationMgr. createTrace1 _ “ABCCorp”, _ “ABCObjectID”, _ “XYZCorp”, _ “XYZObjectID”


Deleting Traces

To delete a trace, use the TraceManager object’s deleteTrace method. For example, the following subroutine deletes all traces from a given requirement:

See “Appendix A: Caliber Object Models” for diagrams that can be used to locate the object you want to work with, and to understand how that object fits into the overall Caliber object model.

Private Sub DeleteTraces(objRequirement As Requirement) Dim objTraceManager As TraceManager Set objTraceManager = objSession.TraceManager Dim objTrace As Trace For Each objTrace In objRequirement.TracesFrom objTraceManager.deleteTrace objTrace Next objTrace End Sub

Chapter 3: Using Java to Wri te SDK Appl icat ions 27

C h a p t e r

Chapter3Using Java to Write SDKApplications

Introduction

This chapter provides an introduction to the Caliber SDK for Java programmers. This chapter:

? explains the way programmers can use the SDK to connect to a Caliber server,

? describes the conventions used by the SDK,

? provides an overview of working with requirement trees, attributes and history,

? explains how the SDK can be used to view and create trace relationships.

Creating a CaliberServer

All applications that use the Caliber SDK must first create a connection to a Caliber server. To establish a connection, you need to create a new instance of the CaliberServer class. A CaliberServer class is used to establish and maintain a connection with a Caliber server on behalf of a Caliber user.


In the following code, a simple Java application is created that connects to a Caliber server:

This code demonstrates the basic steps that every Caliber application must take:

? import the pertinent Caliber packages,

? create a Caliber server,

? login to the Caliber server.

The first line imports the main Caliber package:

This package contains the Session class. For more information on the Session class, see “Using Sessions” on page 29.

The second line imports the Caliber server package:

This package contains all classes relating to server connections, transactions and exceptions. The CaliberServer class is contained in this package.

The following code creates an instance of CaliberServer, which is used to communicate with the Caliber server that resides on host “foo:”

import com.starbase.caliber.*; import com.starbase.caliber.server.*;

public class ConnectionCreator { public static void main(String[] args) { CaliberServer server = new CaliberServer(“foo”);try { Session session = server.login(“admin”, “admin”);

} catch(RemoteServerException rse) { rse.printStackTrace();

} } }

import com.starbase.caliber.*;

import com.starbase.caliber.server.*;

CaliberServer server = new CaliberServer(“foo”);


Finally, logging in to the CaliberServer creates a new Session object:

In the above example, the login method throws a RemoteServerException if a client is unable to login to a remote Caliber server. Typically, a login fails if an incorrect user ID or password is supplied to the login method. For more information on RemoteServerException, see “Caliber Java SDK Conventions”, below.

Note: Whenever the Java SDK is launched, the SDK launches a Java Virtual Machine (VM). By default, most VMs can only consume a maximum of 64 MB of memory. This limit can be overridden by setting the VM’s maximum memory flag (Xmx).

For Java SDK applications, this flag can be set on the command line, for example:

This code must be called prior to any other SDK calls because once the VM is loaded these options cannot be set.

Using Sessions

A Session represents a user’s view of a Caliber server and, as such, provides an entry point into the Caliber object model. In the following code, we use the Session created in the previous example to display the names of all Caliber projects available to the user.

Caliber Java SDK Conventions

The two previous examples illustrate various Caliber SDK conventions. First, whenever an SDK method depends on a Caliber server to perform an operation, that method is declared as throwing RemoteServerException. Typically, a RemoteServerException “wraps” an exception that is thrown by the remote server. You can get a detailed message describing this wrapped exception by calling the exception’s getMessage method.

Second, all methods that return multiple objects return those objects in arrays.

try { Session session = server.login("jdoe", "1234ABC");

} catch(RemoteServerException rse) { rse.printStackTrace();}

java -Xmx1000M

try{ Project[] arrayOfProjects = session.getProjects();

for(int i = 0; i < arrayOfProjects.length; i++) { System.out.println(arrayOfProjects[i].getName());

}} catch(RemoteServerException) {

rse.printStackTrace();}


Finally, the Caliber SDK adheres to the naming standards established by the core Java APIs. The following table illustrates these rules.

Creating Caliber Objects

The Caliber SDK allows you to create, modify and delete the following objects:

? Projects

? Baselines

? Users

? Groups

? Departments

? Requirements

? Requirement Types

? Security Profiles

? Glossaries

? Glossary Terms

? Integrations

The following sample code shows the typical pattern for creating Caliber objects:

Modifying Caliber Objects

To modify a Caliber object, complete the following steps:

1 Obtain an instance of a Caliber object.

2 Call the object’s Lock method.

3 Set one or more of the object’s properties.

4 Call the object’s Save method.

Group Rules Examples

Getter/Setter Methods getXxxxsetXxxx getName() setName()

Boolean Methods isXxxx isEstablished()

isKeyReference()

Event Listener Interfaces XxxxListener ServerConnectionListener

ServerTransactionListener

Event Listener Registration

addXxxxListener addServerConnectionListener

addServerTransactionListener

Event Handler Methods onXxxx onConnectionEstablished

onServerTransaction

Event Classes XxxxEvent ServerTransactionEvent

ServerConnectionEvent

User newUser = new User(“A New User”, session);newUser.save();


The following example follows these steps to modify a Group object:

Deleting Caliber Objects

You can delete a CaliberObject from Caliber by calling its Remove method. For example:

Note that the remove method only deletes a requirement from the current baseline. The requirement is not removed from any previous baselines.

Requirements

This section of the document describes the basics for working with Requirement objects.

Requirement Trees

Typically, hierarchical relationships exist between sets of requirements in a Caliber baseline. Taken together, these requirements comprise a requirement tree. The RequirementTree and RequirementTreeNode classes provide valuable options for working with these trees.

You can traverse the nodes of a requirement tree by:

? obtaining a RequirementTree object from a Baseline.

? calling the RequirementTree's getRoot method to obtain the root RequirementTreeNode.

? recursively calling the RequirementTreeNode’s getChildren method.

Group group = session.getGroups()[2];group.lock();group.setDescription("A New Description");group.setEmailAddress("[email protected]");group.save();

Requirement requirement = session.getRequirement(77);requirement.remove();


The following code follows these steps to print out information about each and every node in a requirement tree.

This code produces output similar to the following:

You can also traverse a requirement tree by utilizing RequirementTreeNode’s getDepthFirstEnumeration and getBreadthFirstEnumeration methods. To illustrate

... // Get current baseline's tree. RequirementTree tree = currentBaseline.getRequirementTree(); // Get the tree's root node. RequirementTreeNode root = tree.getRoot(); TraverseTree(root);}

public void TraverseTree(RequirementTreeNode parentNode) {

// Print relevant information about the current node. PrintTreeNode(parentNode);

// Iterate through the parent's collection of children... RequirementTreeNode[] children = parentNode.getChildren(); for (int i = 0; i < children.length; i++) { TraverseTree(children[i]);}}private void PrintTreeNode(RequirementTreeNode node) { StringBuffer sb = new StringBuffer(); for(int i = 0; i < node.getLevel(); i++) { sb.append(“ “); } sb.append(node.getHierarchyNumber()); sb.append(“ “); sb.append(node.getName()); sb.append(“ “); sb.append(node.getSerialNumberTag()); System.out.println(sb);}

X100 Droid 2016412 Business Requirements BR2016416 1 Operating Environment BR1 1.1 Temperature BR2 1.2 Humidity BR3 1.3 Radiation BR4 2 Continuous operation BR5 2.1 Recharge Time BR73 3 Startup time BR6


this point, the following code represents a portion of the code above using the getDepthFirstEnumeration method:

A RequirementTreeNode in a requirement tree can represent either a project, requirement type or requirement. To obtain the ID of the CaliberObject that is associated with a RequirementTreeNode, you should use RequirementTreeNode’s getAssociatedObjectID method. For example:

// Get current baseline's tree.RequirementTree tree = currentBaseline.getRequirementTree();

// Get the tree's root node.RequirementTreeNode root = tree.getRoot();

// Get an enumeration of all of the nodes that descend from the// root.Enumeration nodes = root.getDepthFirstEnumeration();

// Iterate through all nodes...while(nodes.hasMoreElements()) { RequirementTreeNode node = (RequirementTreeNode)nodes.nextElement(); PrintTreeNode(node); }

// Get the ID of the CaliberObject associated with the node.CaliberObjectID coid = node.getAssociatedObjectID();

// Get the CaliberObject using the CaliberObjectID.CaliberObject co = session.get(coid);if(co instanceof Project) { // Print project specific information. Project p = (Project)co; System.out.println(p.getDescription());

} else if(co instanceof RequirementType) { // Print type specific information. RequirementType rt = (RequirementType)co; System.out.println(rt.getTag());

} else { // Print requirement specific information. Requirement r = (Requirement)co; System.out.println(r.getStatus().getSelectedValue());}


You can modify a requirement tree using RequirementTreeNode’s addChild and insertChild methods. The following example uses the addChild method to add the second requirement node in a requirement tree to the first requirement node.

Requirement trees can also be traversed by using baseline’s getRequirements method in conjunction with the requirement’s getChildRequirements method. It should be noted however, that this method of tree traversal is significantly more resource intensive than using RequirementTree and RequirementTreeNode because you are requesting the entire Requirement objects from the remote Caliber server.

The following example uses these methods to display the first two levels of a requirement tree.

RequirementTree tree = currentBaseline.getRequirementTree();

// Get the project node. This will always be the root node.RequirementTreeNode projectNode = tree.getRoot();

// Get the first Requirement Type node under the project node.RequirementTreeNode typeNode = projectNode.getChildAt(0);

// Get the 1st and 2nd requirements under the Requirement Type.RequirementTreeNode requirementNode1 = typeNode.getChildAt(0);RequirementTreeNode requirementNode2 = typeNode.getChildAt(1);

// Modify the tree by adding the second node to the first.requirementNode1.addChild(requirementNode2);

// Commit the changes.tree.save();

try { // Get the default/current Baseline Baseline defaultBaseline = project.getDefaultBaseline();

// Get the first-level of Requirements in the Baseline's // Requirement tree. Requirement[] topLvlReqs = defaultBaseline.getRequirements(); // Iterate through the first-level of Requirements

for(int i; i < topLvlReqs.length; i++) { Requirement req = topLvlReqs [i];

System.out.println(req.getName());

// Get the “children” of the current Requirement Requirement[] childReqs = req.getChildRequirements();// Iterate through the children. for(int j; j < childReqs.length; j++) { Requirement childReq = childReqs[j];

System.out.println(“\t” + childReq.getName()); } }}


You can also traverse from child to parent requirement by calling a requirement’s getParentRequirement method. For example, the following code prints the path from a requirement to the root requirement in its tree.

Traditionally, Caliber applications display all top-level tree requirements grouped and sorted by requirement type. Therefore, the getRequirements method of a Baseline object always returns requirements sorted and grouped this way.

Note: You can determine a requirement’s project, baseline and type by calling its getProject, getBaseline and getRequirementType methods respectively.

Creating Requirements

The Caliber SDK provides two constructors for Requirement objects. The first constructor allows you to create requirements at the top level of a project’s requirement tree hierarchy, and the second is used to create children of an existing requirement. The example below shows the first constructor to create a new requirement.

try{ // Get the latest version of the Requirement with the ID // number of 10. Requirement req = session.getRequirement( 10 );

while(req != null) { System.out.println(req.getName());

req = req.getParent(); }

} catch(RemoteServerException) { rse.printStackTrace();

}

// Get the Session's first Project. Project project = session.getProjects()[0];

// Get the Project's Current Baseline. Baseline currentBaseline = project.getCurrentBaseline();

// Get the first Requirement Type in the Baseline. RequirementType type = currentBaseline.getRequirementTypes()[0];

// Construct the new Requirement. Requirement newRequirement = new Requirement( “New Requirement”, project, type, 0, session); // Save the new Requirement. newRequirement.save();


The next example illustrates how the second constructor is used to create a requirement that is a child of an existing requirement. This new requirement will be called Child Requirement and will be the fourth child in the parent’s child hierarchy.

Requirement Attributes

Caliber allows you to define requirements using any number of user-defined attributes (UDAs.) Additionally, requirements always contain the Status and Priority system attributes.

In the Caliber SDK, a Requirement object provides a getAttributeValues method for getting its UDA Values and a getStatus and getPriority method for getting its system attribute values. For example, the following code prints the selected value of a requirement’s status, which is an instance of the AttributeValue subclass UDAListValue:

You can also obtain the default value for an attribute by using the getAttributeType( ) method. For example:

It is important to remember that each AttributeValue subclass is associated with a single Attribute subclass. Therefore, UDABooleanValue’s getAttributeType method returns an instance of UDABoolean and UDATextValue’s getAttributeValue method returns an instance of UDAText.

// Get a Requirement that will become the parent of a new // Requirement.

Requirement parentReq = session.getRequirement(125);

// Construct the new Requirement using the parent Requirement. Requirement newRequirement = new Requirement( “Child Requirement”, parentReq, 3, session);

// Save the new Requirement. newRequirement.save();

UDAListValue status = requirement.getStatus();Object selectedValue = status.getSelectedValue();System.out.print("Selected Value: " + selectedValue);

// Get the corresponding attribute type. UDAList attributeType = status.getAttributeType();

// Get the default value object for the attribute type.UDAListValue defaultValue = attributeType.getDefaultValue();

// Get the selected value from the default UDAListValueObject selectedDefaultValue = defaultValue.getSelectedValue();

System.out.print(“Default Value: “ + selectedDefaultValue);


The table below illustrates the relationship between the SDK’s AttributeValue and Attribute classes and Caliber attribute types.

Refreshing Requirements

The Caliber SDK allows for fetching information about the requirements that have been updated in the given project and baseline. It compares last time the requirement was updated and the time on the current view, then updates the view with any changes between those times. Use the getCheckpointRecordsVis() method to obtain Visualize changes. The getCheckpointRecords() is overloaded with an option to retrieve only requirements.

AttributeValue Subclasses Attribute Subclasses Application Attribute Type(s)

UDATextValue UDAText Single Text Line

Multiple Line Text Field

UDAIntegerValue UDAInteger Long Integer

UDADurationValue UDADuration Duration

UDAFloatValue UDAFloat Float

UDADateValue UDADate Date

UDABooleanValue UDABoolean Boolean

UDAListValue UDAList Multiple Selection List

Single Selection List

Multiple Selection Group List

Single Selection Group List

Multiple Selection User List

Single Selection User List


The following example demonstrates how to retrieve changed Visualize objects:

The following example demonstrates how to retrieve changed requirements only:

try { RequirementManager reqMgr = (RequirementManager)session.getManager(Requirement.class); // The following line will get all changed scenarios and simulations // for the given project. HashMap checkpointRecords = reqMgr.getCheckpointRecordsViz(project.getProjectID(), project.getCurrentBaseline().getBaselineID(), 0); Iterator keyIterator = checkpointRecords.keySet().iterator(); while (keyIterator.hasNext()) { // ID of the changed Visualize object Integer key = (Integer)keyIterator.next(); System.out.println(key.toString()); // Change type System.out.println(checkpointRecords.get(key)); } } catch (RemoteServerException e) { e.printStackTrace(); }


Requirement History

The Caliber SDK allows for complete access to requirement history records. To obtain a requirement history you can call the getHistory method on any instance of requirement.

The following class diagram illustrates the relationship between the Requirement, History, HistoryRevision, and HistoryChange classes.

try { RequirementManager reqMgr = (RequirementManager)session.getManager(Requirement.class); // The following line will get all changed requirements (excluding Visualize // objects)for the given project. HashMap checkpointRecords = reqMgr.getCheckpointRecords(project.getProjectID(), project.getCurrentBaseline().getBaselineID(), 0, false); Iterator keyIterator = checkpointRecords.keySet().iterator(); while (keyIterator.hasNext()) { // ID of the changed requirement Integer key = (Integer)keyIterator.next(); System.out.println(key.toString()); // Change type System.out.println(checkpointRecords.get(key)); } } catch (RemoteServerException e) { e.printStackTrace(); }


The example below demonstrates how these classes can be used to display history information:

Traceability

In Caliber, a trace relationship can exist between two requirements or between a requirement and an object external to Caliber. Likewise, the Caliber SDK supports the creation, deletion and modification traces to both Caliber requirements and non-requirements software artifacts.

Some of the more important trace-related classes are:

? Trace: represents a trace relationship between a requirement and some other Caliber object. This Caliber object can be a requirement or an object external to Caliber.

? TraceManager: provides the functionality for creating, modifying and deleting traces.

? ExternalObject: an abstract base class that represents all objects external to Caliber.

? File: represents a file system object.

? SCMFile: represents an object that is managed by a source configuration management tool. Both File and SCMFile reside in the com.starbase.caliber.external.file.

? XGenericObjectManager: provides the functionality for creating traces between requirements and non-requirements software artifacts.

? VendorAddIn: represents a reference to an object that resides within the realm of some other application.

// Get the history for a Requirement objectHistory history = req.getHistory();

// Get the revisions that comprise the historyHistoryRevision[] revisions = history.getRevisions();

for(int i = 0; i < revisions.length; i++) { Revision revision = revisions[i]; System.out.println(“Revision: “ + revision.getVersion()); System.out.println(“Date: “ + revision.getDate()); System.out.println(“User: “ + revision.getUserName()); System.out.println(“Comment: “ + revision.getComment()); // Get the changes that comprise the revision HistoryChange[] changes = revision.getChanges(); For(int j = 0; j < changes.length; j++) { Change change = changes[j];

System.out.println(“\tField: “ + change.getFieldName()); System.out.println(“\tOld Value: “ + change.getOldValue());System.out.println(“\tNew Value: “ + change.getNewValue()); }}


Obtaining Traces

Traces can be retrieved at many levels of the Caliber object hierarchy. The Session class provides a getTraces method that returns all traces available to the Session. Similarly, the getTraces method of the project class returns all traces that trace to or from the requirements contained within a project.

The requirement class provides two methods for getting traces: getTracesFrom and getTracesTo. Additionally, to obtain traces from Caliber Visualize, use one of the two methods: getTracedVizTo() and hasTracedVizTo(). The example on the following page uses these methods to print the names of objects tracing to or from a requirement.

The following example gets traces in Caliber Author:

The following exmample gets traces from Caliber Visualize:

try{

// The following line will get the latest version of // a Requirement with an ID number of 1. Requirement requirement = session.getRequirement(1);

Trace[] tracesTo = requirement.getTracesTo(); for(int i = 0; i < tracesTo.length; i++) {

// The following Trace is FROM our Requirement

// to some other object. Trace trace = tracesTo[i]; CaliberObject obj = trace.getToObject();

System.out.println(obj.getName()); }

Trace[] tracesFrom = requirement.getTracesFrom(); for(int i = 0; i < tracesFrom.length; i++) {

// The following Trace is TO our Requirement // from some other object.

Trace trace = tracesFrom[i]; CaliberObject obj = trace.getFromObject();

System.out.println(obj.getName()); }

} catch(RemoteServerException) { rse.printStackTrace();

}


Creating Traces Between Requirements

The TraceManager class allows the creation and modification of trace relationships. To obtain an instance of TraceManager, you must call the Session’s getManager method. The following example shows how to obtain an instance of TraceManager:

Once you have obtained a TraceManager, you can use it to create traces. The following example creates a trace between two requirements.

try{ // The following line will get the latest version of // a Requirement with an ID number of 292. Requirement requirement = session.getRequirement(292); if (!requirement.hasTracedVizTo()) { System.out.println("Requirement " + requirement.getName() + " has no tracedToViz"); return; } TracedViz[] tracedVizTo = requirement.getTracedVizTo(); for (TracedViz tracedViz : tracedVizTo) { // Each tracedViz is FROM our Requirement // to some other Visualize object. System.out.println("name=" + tracedViz.getName()); System.out.println("ID=" + tracedViz.getID().getIDNumber()); System.out.println("projectID=" + tracedViz.getProjectID().getIDNumber()); System.out.println("simObjectType==" + tracedViz.getSimObjectType()); System.out.println("snapshotUrl=" + tracedViz.getSnapshotUrl()); System.out.println("testCasesUrl=" + tracedViz.getTestcasesUrl());

TraceManager traceMgr;traceMgr = (TraceManager)session.getManager(Trace.class);

Requirement req1 = session.getRequirement(1);Requirement req2 = session.getRequirement(2);// The following line creates a trace from req1 to req2.TraceMgr.createTrace(req1, req2, false);


Creating Traces to Non-Requirements Software Artifacts

In the previous example, a trace relationship between two objects (both requirements) that reside within the bounds of Caliber was created. The following example shows how to create a trace to an object that resides outside of Caliber.

To create a reference to an external object, you must first obtain a reference to the appropriate object manager. As previously stated, you can call the getManager method of a Session object to obtain an instance of CaliberObjectManager. In the above example, an instance of om.starbase.caliber.xgeneric.XGenericObjectManager (which manages most objects external to Caliber) is obtained:

Notice that the createFileTrace method requires a reference to a requirement as its first parameter:

This is because a reference to an external object can only exist within Caliber while that object is participating in a trace relationship with a requirement. Once this relationship is removed, the reference is deleted. The only exceptions to this rule are Mercury TestDirector and Select Enterprise objects, which can be added and removed from Caliber without being linked to a requirement.

Class clazz = File.class;XGenericObjectManager extGenObjMgr =

(XGenericObjectManager)session.getManager(clazz);

Requirement req1 = session.getRequirement(1);

// The following line creates a File object in the Caliber// system and creates a trace from req1 to the new File.File f = extGenObjMgr.createFileTrace(

Req1, true, “foo.txt”, “C:\\temp\\”);

Class clazz = File.class;FileManager fileMgr = (FileManager)session.getManager(clazz);

File f = fileMgr.createFileTrace( Req1, ...


Chapter 4: Creat ing a Traceabi l i ty Add- in for Cal iber 41

C h a p t e r

Chapter4Creating a Traceability Add-infor Caliber

Introduction

Developing and distributing a traceability add-in is the simplest way to provide your users with a custom solution for Caliber. An add-in provides a set of objects to Caliber. These objects are displayed through the Caliber user interface so users can create trace relationships with requirements. For example, an add-in might display Microsoft Project tasks, or objects from a design tool, or a testing tool.

This document describes how you can use a Microsoft Visual Basic.NET project sample to create a traceability add-in for Caliber. The sample files are provided at Program Files\Borland\Caliber\Samples\Addins\.

Using the Visual Basic.NET Sample

The Caliber installation includes a set of sample files you can use for creating a traceability add-in for Caliber in Visual Basic.NET.

Note: You should change all of the GUIDs in the traceability add-in files and Assembly.Info.vb.

By default, the sample project is located at Program Files\Borland\Caliber\Samples\Addins\HelloWorld2 VB.NET. You will see the following files:

? AssemblyInfo.vb

? HelloWorld2_VBNet.sln

? HelloWorld2_VBNet.vbproj

? HelloWorld2_VBNet.vbproj.user

? Icon1.ico

? Icon2.ico

? Icon3.ico

? Icon4.ico


? Icon5.ico

? VendorObject.vb

? VendorSession.vb

? VendorView.vb

To create a new traceability add-in, perform the following steps:

1 Create a new Visual Basic project using the "Class Library" template.

2 Copy VendorSession.vb, VendorView.vb, and VendorObject.vb files into the directory of you new VB project. Then add the files to the project using "Add Existing Item…".

3 Change all of the COM GUIDs values in the newly added files using the CreateGUID (menu: Tools->CreateGUID) tool found in VS.NET.

4 Next build your new project. VS.NET will register the newly built DLL at the end of the build. You can register the DLL on other machines by using regasm (.NET Assembly Registration tool) at any command line.

5 Your traceability add-in is now ready to use. You can now implement the properties and methods that are required in the interface.

Traceability Add-in Interface

To create an add-in, you need to populate the properties and functions of three classes: VendorSession, VendorView and VendorObject. The following is a detailed description of each of these classes and their procedures.

VendorSession

The VendorSession class provides a context in which Caliber clients can interact with your add-in. Subsequently, VendorSession is the only class that must be publicly creatable.

Public ReadOnly Property SupportsViewBuilding() As Boolean

If your add-in allows users to dynamically build custom views, this property should be "true". For example, if you are building an integration with a database, you might want to expose multiple views of data based on a query. Conversely, if you are creating an add-in that only supports default views then this property should be "false".

See “GetVendorViews” on page 43 for more information.

Public WriteOnly Property ConfigFilePath() As String

The ConfigFilePath property is set by Caliber to indicate the path of a configuration file that your add-in uses. This configuration file is specified when you register an add-in in Caliber Administrator. See “Registering and Enabling Your Traceability Add-In” on page 45 for information about enabling a new traceability add-in.

Once this configuration file is set, it is managed by Caliber and passed to your integration (using the ConfigFilePath property) immediately after the VendorSession class is initialized.


Public Property SilentMode() As Boolean

This property is set by Caliber to indicate that an add-in should run silently. In this state, your add-in MUST NOT display any dialog boxes that require user input.

When Caliber gets this property, it indicates that the add-in is running in silent mode.

Note: Silent mode allows Datamart reports to be scheduled to generate reports off hours. If your Caliber server contains projects in which you established traces to your traceability add-in, when Datamart performs its tasks, it will be looking for credential information but no login dialog should be displayed when the add-in runs in silent mode. It is recommended to store the authentication information in a file or the registry for your add-in to gather that information without displaying a login dialog box.

Public ReadOnly Property InterfaceVersion() As Integer

This property provides the version of the traceability add-in interface that an add-in implements. Currently CalibeRM supports version 2.0 of this interface, therefore this property should always be 2.

Public Function GetVendorViews(ByVal BuildView As Boolean) As Collection

This function provides a collection of VendorView objects to Caliber. Each of these views is displayed as a tab in Caliber’s Traceability Modification window.

When initializing the Traceability Modification window, Caliber calls the add-in’s GetVendorViews method with the BuildView parameter set to "false", indicating that Caliber is requesting the initial (or default) view(s). If the add-in supports dynamic view building (see “Public ReadOnly Property SupportsViewBuilding() As Boolean” on page 42), the Build View button is enabled. When a user clicks the Build View button, Caliber calls GetVendorViews with the BuildView parameter set to “true”. The add-in can show a dialog box asking the user to specify view parameters. Returned views will be appended to existing view tabs.

Public Function GetVendorObject(ID As String) As VendorObject

The GetVendorObject function is called by Caliber to obtain a single VendorObject.

VendorView

As previously stated, a traceability add-in provides a set of VendorView objects through VendorSession's GetVendorViews method. In turn, each VendorView provides a set of VendorObjects that are displayed in the view's tab in Caliber's Traceability Modification window.

Public ReadOnly Property ViewName() As String

This property provides the name for the view.

Public ReadOnly Property IsList() As Boolean

Caliber can display a collection of add-in objects as a tree or as a list. If this property is "true," Caliber displays the view's objects as a list. Otherwise, Caliber displays the view's objects as a tree.


Public ReadOnly Property VendorObjects() As Collection

This property provides the objects that comprise the view. If the view represents a tree of objects (i.e. IsList = "false"), this collection of objects should represent the first level of nodes in the tree.

VendorObject

The VendorObject class represents a single object that is exposed by your add-in. Caliber obtains these objects as members of a VendorView or through VendorSession's GetVendorObject method.

Public ReadOnly Property ID() As String

The ID property provides a unique identifier for an object in Caliber. Subsequently, Caliber uses this ID when calling VendorSession's GetVendorObject method.

Public ReadOnly Property ObjectName() As String

The ObjectName property provides a name for the VendorObject.

Public ReadOnly Property ShortObjectName() As String

This provides Caliber an abbreviated name for the object. Caliber truncates this name if it exceeds 16 characters in length.

Public ReadOnly Property Icon() As Long

This property provides a windows icon handle for the object.

Public ReadOnly Property Traceable() As Boolean

The Traceable property determines whether or not Caliber allows users to create a trace to a VendorObject.

Public ReadOnly Property HasChildren() As Boolean

This property determines whether or not the VendorObject has children. Caliber checks this property only if the VendorObject is provided as a tree of objects (see VendorView's IsList property). If this property is "true," Caliber displays a symbol next to the object in the object's tree.

Public ReadOnly Property Children() As Collection

This property makes the children of a VendorObject available to Caliber. Caliber calls this method if the HasChildren property is "true" and the user has expanded the VendorObject in a tree.

Public ReadOnly Property Operations() As Variant

Each VendorObject may expose one or more operations to Caliber users through its Operations property. This property should return an array of strings, each of these strings represents an operation that can be performed on the object. For example, if your VendorObject represents a file then you may wish to expose Open and Properties as operations.


Public Sub DoOperation(Operation As String)

When a user right-clicks on a VendorObject in Caliber, Caliber queries the Operations property and displays a pop-up menu that contains the returned strings. Subsequently, when a user selects an operation menu item, Caliber calls the VendorObject's DoOperation method and passes in the name of the selected operation.

Public Sub OnTraceCreated(RequirementID As Integer)

This method is called by Caliber when a trace is created between a Caliber requirement and the VendorObject.

Public Sub OnTraceDeleted(RequirementID As Integer)

This method is called by Caliber when a trace between a Caliber requirement and the VendorObject is deleted.

Public Sub OnStatusChange(RequirementID As Integer, MadeSuspect As Boolean)

This method is called by Caliber when the "suspect" status of a trace between a Caliber requirement and the VendorObject changes.

Registering and Enabling Your Traceability Add-In

Once you have coded and compiled your add-in, you should register and enable it for a specific project on a Caliber Server as well as deploy it on each Caliber client computer.

To register and enable your add-in, perform the following steps:

1 On a Caliber Server computer, open Caliber Administrator and select a project in the left pane.

2 Select the External Traceability tab in the right pane.

3 Click the New button. The New Integration dialog box is displayed.

4 Type in an Add-in Name (this name appears on the Traceability Modification tab), Library Name (in Visual Basic, this name appears in the Project Name field of your project's Properties dialog box), and choose an icon. You may also specify the location of a configuration file that your add-in uses. Caliber automatically distributes this file to all clients that use your integration (see "VendorSession's ConfigFilePath" on page 43 for more information.)

5 Click OK to create the new integration. The new integration is added to the Disabled Integration(s) list box for all Caliber projects.

6 To enable the integration, select that integration in the Disabled Integration(s) list box and click the Move Left button.

7 Click File > Save Changes. Your add-in is registered and enabled on the Caliber Server.

8 Deploy your add-in on each Caliber client machines when users need to trace requirements to your add-in objects. You can use either a setup program or distribute and register the necessary files manually or using the logon script.


Appendix A: Cal iber Object Model 47

A p p e n d i x

Appendix ACaliber Object ModelThese diagrams can be used as a way to locate the object you want to work with and to understand how that object fits into the overall Caliber object model.

The following table shows how objects and collections are represented in the diagrams:

Indicates an object.

Indicates a collection of objects.

Indicates that a complete view of the object hierarchy is located elsewhere in the diagram.


Caliber Object Model

Appendix A: Cal iber Object Model 49


Documents

CaliberRM SDK User Guide - Micro Focus · This document provides the necessary information for Visual Basic and Java programmers to get started with the Caliber APIs. Note: ... 2010,