Adding External Methods to Classes

You can write external user-methods (or routines) for Jade classes. External routines can be written in any language that can create a library. For details, see "Writing External Methods", later in this chapter and "Jade Application Programming Interface (API)", in Chapter 3 of the Object Manager Guide.

To add an external method to a class

1. In the Class List of the Class Browser, select the class to which the external method is to be added.

2. Select the New External Method command from the Methods menu in the Class Browser.

   The External Method Definition dialog, shown in the following image, is then displayed.

   

3. Check the Reimplement Superclass Method check box if you want to reimplement an existing external method in a superclass. (You can reimplement an external method only if it is not final in the superclass. For details, see "final Option" under "Controlling the Use of Elements in Other Schemas", in Chapter 1.) A drop‑down list containing all superclass external methods that are not final is then displayed.

   Select the method in the parent class that you want to reimplement in the current class. A message box then advises you that you are about to reimplement a superclass method, and prompts you to click the Yes button if you want to continue. The parent class and the method that you selected for reimplementation are then displayed in the Name text box.

4. Specify the name of your new external method in the Name text box; for example, newExtMethod. The external method name has a maximum length of 100 characters.

5. In the Entry Point text box, specify the name of the function in the library that is to be the entry point for your external method.

   Although the entry point name has a maximum length of 255 characters, if you specify an entry point name greater than 100 characters, it must be enclosed in single quote ('') or double quote ("") characters or exception 6007 (Token too long) is raised. (The schema extract process encloses all entry point names in quote characters.)

   The entry point name can include a period, the underscore (_), opening parenthesis ((), closing parenthesis ()), or the ampersand (&) special character. In addition, the entry point name is case-sensitive.

   You cannot specify an entry point for an abstract external method of an abstract class.

6. In the Library combo box, select the library containing your library (.dll) file from the list portion of the combo box or specify the name of an existing library in the text portion.

   If you specify a library in this combo box and you specified an entry point in the Entry Point text box, subsequently checking the Abstract check box (which is enabled only for an abstract class) removes values entered in the entry point and library controls.

   For details about libraries for your external routines, see "Maintaining Libraries for External Methods and Functions", later in this chapter.

7. Check the Updating check box if the method can modify properties in the object to which it is sent.

8. If you did not specify an entry point and library for your external method, check the Abstract check box if the selected class is abstract. An abstract method defines a signature with which all subclass implementations must comply.

   The Abstract check box is enabled only when the selected class is an abstract class.

9. Check the Protected check box if you want the protected method option added to the signature of your method so that it can be referenced only by methods in the same class or its subclasses. (A protected method is displayed in the browser Methods List with a padlock icon to the left of the method name.)

   By default, external methods are not protected; that is, they are displayed in the Methods List of the Class Browser or Primitive Types Browser with the public access icon to the left.

10. Check the Final check box if you want to specify that the external method cannot be reimplemented in a subclass. The final method option makes methods available to other schemas but prevents those schemas from modifying, reimplementing, or circumventing the defined method behavior. For details, see "final Option" under "Controlling the Use of Elements in Other Schemas", in Chapter 1.

11. Check the Subschema Hidden check box if you want to specify that the external method is available only in the local schema; that is, it is not available for use in any subschemas. For details, see "subschemaHidden Option" under "Controlling the Use of Elements in Other Schemas", in Chapter 1.

12. Check the Type Method check box if you want the typeMethod method option added to the signature of the external method so that the method is a type method.

    Type methods provide a way of calling a method declared on a type (class, primitive, or interface) without having to have an instance of the type. For more details, see "Type Methods", under "Jade Language Notation" in Chapter 1 of the Developer's Reference.

13. In the Final Settings group box, select one of the following option buttons for the appropriate final setting, if required.

    • Final, if you want to specify that the external method cannot be reimplemented in a subclass. The final method option makes external methods available to other schemas but prevents those schemas from modifying, reimplementing, or circumventing the defined method behavior. For details, see "final Option" under "Controlling the Use of Elements in Other Schemas", in Chapter 1.

    • Subschema Final, if you want to specify that the external method can be extended or reimplemented in its local schema but not in a subschema.

      The subschemaFinal method option makes external methods available to other schemas but prevents those schemas from modifying, reimplementing, or circumventing the defined method behavior. For details and an example, see "subschemaFinal Option" under "Controlling the Use of Elements in Other Schemas", in Chapter 1.

    • Subschema Copy Final, if you want to specify that the external method cannot be reimplemented in a subschema copy class. For details and an example, see "subschemaCopyFinal Option" under "Controlling the Use of Elements in Other Schemas", in Chapter 1.

14. In the Execution Location group box, select the Server or Client option button if you want the serverExecution or clientExecution method option added to the signature of your external method so that the method and all methods subsequently called by this external method are executed on the server node or client node, respectively.

    By default, no execution option is added to the external method signature and the node in which the method executes is determined by the location of the calling method. For more details, see "Method Options", in Chapter 1 of the Developer's Reference.

15. Click the Enter Text button if you want to specify or maintain descriptive text for the external method as part of the definition or maintenance of the method. For details, see "Specifying Text for a Schema Element", in Chapter 3.

    You can also specify descriptive text for the external method at any time, by selecting the Text command from the Methods menu. For details, see "Using the Free-Standing Editor Window to Define Text", in Chapter 3.

16. Click the OK button or the Next button.

A template for the method is then displayed in the editor pane of the Class Browser. Modify the template by adding your external routine code to perform the required operations and then compile it. (For more details, see "Compiling Methods", in Chapter 4 of this guide and "Method Options", in Chapter 1 of the Developer's Reference.)