NAME

CQCC::TriggerCQCC - Class that defines user interactions with the ClearCase/ClearQuest integration.


CLASS DESCRIPTION

This class defines the overall behavior of the trigger application drawing upon the capabilities of the lower level classes to handle user interaction and communications with ClearCase and ClearQuest. It relies upon its superclass, TriggerBase, for methods to handle command line argument processing, initialization, menu interaction, and cache management.

The trigger is activated by ClearCase operations, each of which has its own entry method; for example, when the user does a checkin, then the Op_checkin method is invoked.

Depending on the operation, the main menu is presented to the user for runtime interaction. The menu in turn calls either Dialog methods, which interact with the user, or Action methods, which carry out an action and possibly exit from the trigger.

NOTE: Anyone interested in understanding how the overall trigger works or who is contemplating customizing the behavior of the trigger should start with a review of this class and how its methods work. Most changes in visible behavior of the trigger will involve changes in this class. For additional source code documentation, contact Rational Customer Support.

If local changes are needed, do NOT make them directly to the TriggerCQCC source code: make a copy of the MyTrigger.pm template class, rename it, and make your changes there by overriding or extending the TriggerCQCC methods (see MyTrigger.pm for more details). Doing this will facilitate upgrading to later releases of the CQCC trigger from Rational and provide a fallback to the released trigger for working with Rational Customer Support.

SUPPORT POLICY:

Rational Support supports the new integration as provided and local configuration changes made using the parameters in the configuration file (config.pl).

Rational does NOT support source code changes to the integration even though it is provided in source code form as Perl scripts. Internal source code documentation will be provided on request to enable local sites to make judicious changes if needed but Rational Customer Support can not and will not support local changes of this sort.


METHODS

TriggerMain()
This is the main entry subroutine for the application. It will call methods to evaluate the command line and environment settings, call the method with the same name as the ``operation'', then cleanup.

ClassInit()
This class function is automatically invoked to define class parameters using CQCC::Parm objects. Current parameters include:
CQCC_MULTIPLE_ASSOCS
This switch selects whether the user can make only one association ('FALSE') or multiple associations ('TRUE', default) per operation.

CQCC_CQWEB_ONLY
This switch is used to force using the CQWeb interface even when ClearQuest and CQPerl is found on the client machine. It is set to 'FALSE' by default; set it to 'TRUE' to always use CQWeb.

CQCC_GUI_ENABLE
This switch is used to enable or disable the Perl/TK GUI interface. If 'ON' (default) then it will be presented when possible (Perl/TK support is available and ClearCase Explorer or XClearCase is in use). If 'ALWAYS', then the GUI will be presented for command line access as well, when possible. If 'OFF', then the GUI is never presented and Perl/TK is not loaded.

CQCC_POSTCHECKIN_VERIFY
This switch enables a post-checkin validation that the object IDs for the version file that are being stored in ClearQuest are correct. This may be needed because the object IDs can change after the version is checked in. If they do have changed, they will be updated if this switch is set to 'TRUE'. If it is set to 'FALSE' (default), check is not made.

CQCC_QUERY_ENABLE
This switch controls whether the user can select different queries while searching for associations. If 'LOCAL' (default), then only queries defined locally in the configuration file are presented. If 'CQ' then only ClearQuest named queries will be shown. If 'BOTH' then both LOCAL and CQ queries are displayed. If 'OFF' then no choice is permitted; the GUI's Browse button is disabled and the QueryName menu option is hidden. Query names displayed are subject to the CQCC_QUERY_FILTER for finer control.

CQCC_QUERY_FILTER
This switch provides an optional filter to control which query names will be presented to the user to choose from. The string is applied in a Perl pattern match if it is not empty. For example, to only allow queries that include ``Public Queries'', set the filter string to ``Public Queries''. By default the string is empty.

CACHE_*
There are a number of internal parameters maintained by this class that hold the values of runtime values from the previous trigger invocation. They are not externally visible or settable.

ConfigureClasses()
This method decides which component classes to use when initializing the trigger based on the current environment. This may be overridden to use a different set of criteria.

Controlling which classes are used allows the administrator to decide which standard interface is used for ClearCase (Process or PerlApi) and ClearQuest (Web or PerlAPI) or which local subclass is used to support local extensions or overrides. Interfaces only supported on certain Perls or platforms can be added on here without touching lower level code.

Action_Cancel()
This method cancels the trigger operation and exits with a return code of 1.

Action_Cancel_ApplyToAll()
This method cancels the trigger operation and exits with a return code of 1. If an operation required any cleanup (i.e. canceling a checkout will require an uncheckout), IOExitHandler will call the cleanup routine.

Action_Commit()
This method commits association changes to the ClearCase and ClearQuest databases then exits. If associations are required but not provided it displays an error message rather than exiting.

Action_Commit_ApplyToAll({UseCheckouts})
This method sets the cache flags to apply the same values to the remaining versions in the same batch then calls the commit action.

The optional UseCheckouts argument is used to change how ApplyToAll will work with files in the batch. By default it will override the current associations (assumed 0 if undefined); if non-zero it will use the existing checked out associations.

Action_Commit_ApplyToAll_UseCheckouts()
This method is a variation on Action_Commit_ApplyToAll which asks that the remaining items in the batch use their original checkout associations rather being overridden by a new set of associations. It calls Action_Commit_ApplyToAll with a flag to cause it to use the checkout values (1).

Action_Help(topic)
This method presents help on the given topic then returns.

Action_Noop
This method presents a dividing line in the menus and otherwise is inactive.

Dialog_Cancel()
This method cancels the trigger operation and exits with a return code of 1. If a batch is being processed, it will offer the choice to cancel the remaining items in the batch without further interaction.

Dialog_Commit()
This method processes the choice to commit, making final tests on the appropriateness of the associations being made, etc. If the current version is part of a batch, additional choices are offered to a) apply the associations to the current version only, b) apply the same associations to the rest of the batch or c) process the rest of the batch using the original checked out associations.

Dialog_EditDesiredAssocs()
This method allows the user to delete individual items from the desired associations list and update it. Comparable to the AssociationDialog ``AssociatedRecords'' and ``Disassociate'' button provided by the V1 integration on Windows.

Dialog_SelectByTypein()
This method implements a simple type-in interface to select bugs, performing parsing to get the needed lists, and offering the user the choice to change mode to other alternatives like choosing from a list menu.

Dialog_SelectByQuery()
This method implements a query display with a simple type-in interface to select bugs, performing parsing to get the needed lists, and offering the user the choice to change mode to other alternatives like choosing from a list menu.

Dialog_SelectDatabase()
This method allows the user to select which ClearQuest database to connect to.

Dialog_SelectEntity()
This method allows the user to select which ClearQuest entity to make associations with, i.e. ``defect''.

Dialog_DisplayXPN()
This method displays information about the currently selected ClearCase version. Currently it doesn't display any additional information but provides a way to show the current version being operated on, which is important when working on a batch of changes.

GUIBuild()
This method is called as needed to initialize the Graphical User Interface (GUI) for the integration using the IOPerlTK package.

IOPerlTK provides the standard IOBase dialog methods (IOMessage, etc) and a limited vocabulary of ``canned'' user interface components consisting of panels (such as IOMainWindow or IOFrame), menus, and manipulators (such as IOLabel, IOListbox, etc). IOPerlTK isolates the Trigger from any direct dependency on the Perl/Tk widget package and simplifies some aspects of creating a GUI for the needs of this integration. See the IOPerlTK package for more information on how this layer works.

The GUI presents a main association dialog panel consisting of the following three frames:

    Frame 1 - Association Records browser and command menu
    Frame 2 - Database and Record Type buttons and status display
    Frame 3 - Query results browser, query name, and association menu

This method may be modified or overridden by subclasses as necessary. It is invoked by the GUIDisplay method which calls this method to build the GUI then starts the main event loop.

GUI_Action_ApplyToAll()
This method handles the call to apply the operation to the entire current series. If the operation is a checkin and it is still valid to apply the check-out associations to all, the choice is offered to the user.

GUI_Action_Associate()
This method copies the selected items on the Query results browser to the desired associations list and updates the Associated records browser to show the current list.

GUI_Action_Disassociate()
This method deletes the selected items in the Associated records browser from the desired associations list and updates the browser appropriately.

GUI_Action_Refresh()
This method flushes the current query selection list for the Browse operation and updates the two record browsers.

GUI_Action_Typein()
This method calls the standard dialog to process user input to type in a list of defect ids, then ADDS them to the desired association list rather than replacing the entire list. This is done because the GUI provides a more reasonable way to interact with the list to delete undesired associations.

GUI_Action_UpdateAssocRecords()
This method updates the Associated Records browser to reflect the current desired associations list.

GUI_Action_UpdateQueryResults()
This method updates the Query Results browser to reflect the latest query information returned by ClearQuest.

MenuBuild(menuName)
A menu is a list consisting of a title message tag and one or more choice message tags which can be translated through the message catalog along with a set of arguments. For example,

   [Action_Help, "main_menu"]

might be displayed as ``3) Help for main_menu''. If the title or choice message tags are NOT message tag arrays, then the literal value is shown instead of being looked up through the message tag.

When the user makes a selection, the menu gets back the message tag. The tag value is expected to be a trigger method name and will be called with the arguments, i.e. $obj->Action_Help(``main_menu'').

This approach allows a subclass to redefine the menu by editing its definition or to override any of its activities by overriding the method that gets called back.

new CQCC::TriggerCQCC()
This method presets the objects attributes to read in the basic command line arguments. The object is not active until the owner calls its Initialize() method.

Op_checkin()
This method handles the ClearCase checkin() operation.

When called from a pre-op trigger it calls the SelectAssocs() method to select the desired associations through user interaction or automation during batch operations. The associations it makes may be incorrect because the object id of the checked in file will not be known with certainty until ClearCase completes the checkin operation.

When called from a post-op trigger it fixes the associations to use the correct object id for the checked in file.

Op_checkout()
This method carries out the ClearCase checkout() operation by calling the SelectAssocs() function it shares in common with checkin(). If it fails, ClearCase will be asked to uncheckout the file.

Op_edit(vobPathName, XPN)
This method provides an operation that may be invoked from the command line to change the associations for an already checked in pathname.

The two optional arguments are the extended pathname (XPN) and the VOB pathname (vob_pn). If not provided they will be prompted for.

Op_test()
This method is invoked to carry out the -test mode operation. It will ask the ClearQuest object to do a basic query. Testing automatically enables debugging and tracing.

Op_uncheckout()
This method carries out the ClearCase uncheckout operation by deleting existing associations on checked out versions before they are unchecked out.

@list = QueryNameList(type)
This method returns the acceptable list of possible queries.

If the type argument is ``LOCAL'' then the list will include any valid LOCAL queries and may include ClearQuest queries if the list is already cached. Otherwise the full list will be provided. This optimization allows validating local queries without spending time getting the entire list from the ClearQuest database.

QueryNameValidate(option)
This method confirms that the current Query name is valid for the current database. If not, it is reset to LOCAL/STANDARD.

If the option argument is REFRESH, the cached query name list will be cleared to make sure the list is current.

Returns 1 if the current query name was valid, 0 if it was not and had to be reset to LOCAL/STANDARD.

SelectAssocs(operation)
This method provides shared functionality for a number of ClearCase operations. It sets up the initial settings appropriate for the operation then invokes the main menu which interacts with the user to display the current assocations, make changes, and update the desired and existing association lists.

It also processes the ApplyToAll settings from the last session to automate processing versions in a batch. When ApplyToAll is 1, then the cached associations from the last session will override the checkout associations if any. When ApplyToAll is 2, then the checked out associations for each version are used when that version is checked in.