CQCC::TriggerCQCC - Class that defines user interactions with the
ClearCase/ClearQuest integration.
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.
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.