Creating user-defined checks

You can create user-defined checks, which are also known as external checks, which are customized checks that you code yourself. System profiles, for example, often require domain‑specific checks.

About this task

Just as the predefined internal checks provided by IBM® Rational® Rhapsody®, you can define if external checks are called from code generation or not. In addition, you can define on which metaclasses external checks will be executed.

You can implement user‑defined external checks through the Rational Rhapsody API and use the GUI already in place in Rational Rhapsody to run them. Whether it is an internal check or an external check, the checks are performed and their results displayed through the same GUI in the product.

Rational Rhapsody provides an API for registering, enumerating, and removing user-defined external checks through the use of the COM API for C++ and VB users, and the Java API for Java users. COM callbacks (connection points) allow you to open user-defined code when checks are executed. This capability is available for those users who use the COM API or Java API so that you can add, execute, or remove user-defined checks.

You decide which metaclasses (or new terms) you want to check, and your checks are called to check elements of whichever metaclasses you decided upon.

Procedure

For example, for COM API users to create a user-defined check:

  1. Implement a class defined from the interface IRPExternalCheck in the COM API.
  2. Register this class using the IRPExternalCheckRegister Add method. You get this singleton through a method on IRPApplication.
  3. You must implement IRPExternalCheck on your client machine.

Results

The following table lists the methods in the interface that you must implement for a user‑defined check.

Table 1. Methods in the interface that you must implement for a user‑defined check
Method Explanation
GetName() Returns the name attribute as a string.
GetDomain() Returns the domain attribute as a string.
GetSeverity() Returns one of the predefined severity strings: Error, Warning, or Info.
IsCompleteness() Returns TRUE if the check is for completeness, otherwise FALSE (the check is for correctness
ShouldCallFromCG() Returns TRUE if this check must be called when the user generates code
GetRelevantMetaclasses() Returns a list of relevant metaclasses, terms, or both. The check will be started by Rational Rhapsody for any element in the scope of the current configuration whose metaclass is returned.
Execute() Called by Rational Rhapsody in order to run the check. This routine returns TRUE if the check passes or FALSE if the check failed. It has two parameters:
  • The first parameter provided by Rational Rhapsody is the IRPModelElements that the check must be run on (its metaclass is in the checks GetReleventMeltaclass() list).
  • The second parameter, returned by the check when relevant, is a collection of IRPModelElements that Rational Rhapsody will highlight if the check fails.

Deploying user-defined checks

About this task

You provide the code in a COM client.

  • If using VB, the client is an EXE file.
  • If using C++, the client is an EXE or DLL file.
  • If using Java, the client is a CLASS or JAR file.

IBM Rational Rhapsody uses the plug-in mechanism to load your code, typically with a HEP file or INI file. Typically, you added the HEP file next to the relevant project or file. For example, a user wanting to write a Java plug-in would write the plug-in using the Rational Rhapsody Java API and provide a HELP file like the one in the following example.

[Helpers]
numberOfElements=1
name1=ExternalChecks
JavaMainClass1=JavaPlugin.ExternalChecks
JavaClassPath1=$OMROOT\..\DoDAF

Sample check projects are provided for Java and VB in the ExternalChecksSample subfolder of your Rational Rhapsody installation path (for example, &ltproduct installation folder>\Samples\ExtensibilitySamples\ExternalChecksSample).

Removing user-defined checks

About this task

To remove a user-defined check, remove your class using the IRPExternalCheckRegister Remove method. You get this singleton with a method on IRPApplication.


Feedback