Validating via a Java External Object
This document will explain how to call an external object Java program for validity checking. For basic information regarding validity checking please see this document.
The source code for the Java used in this example can be found here. The purpose of this object is to check to see if the start date is less than the end date.
Note: This is a very simple example that is meant to demonstrate how to create and setup a Java validity checking external object. Your Java program could be designed to check anything!
In the included example, we are creating a Java program called Validate within the MRCWORKLIB data dictionary. Within this program are three parameters:
- ERROR — 99 length, used for setting the error message.
- strdatex — 8,0 length, used for accepting the start date, passed from the servlet.
- enddatex — 8,0 length, used for accepting the end date, passed from the servlet.
In the example, we setup a simple If/Else If statement that checks to see if the start date is greater than the end date. If it is, the Java program will return the error message, which has been set to read: "Starting Date is greater than End Date". However, if the start date is smaller or equal to the end date, the Java Program will return the error message, which will be set to blank. This example also has three other cases it tests for:
- If both date fields are blank, the error "You have not entered any dates" will be displayed.
- If the start date has been omitted, the error "You must enter a starting date" will be displayed.
- If the end date has been omitted, the error "You must enter an end date" will be displayed.
The code provided still needs to be compiled. If you do not have easy access to a Java compiling tool, you can use m-Painter. The following steps show how you can quickly and easily do this:
- Open m-Painter for any existing application, and click "Open File". Check the checkbox for "Show All Files" and then select the Java file for this application. This will open the Java code in m-Painter. Replace the existing code with the Java file referenced earlier in this document.
- Press the "Save as" button, be sure to save the file as Validate.java.
- Lastly, press the compile icon. This will compile your Java logic into a Class file, which can then be used by m-Power. When successful, you will see a confirmation window to close the window. Congratulations, you have successfully compiled your external object.
Once your object has been built, we need to register it to m-Power before we can use it.
- Click "Admin Menu" -> "Custom Code" -> "External Objects" -> "Create New Object"
- Specify Validate for your Object Name. Specify a meaningful object description. Select the "Java Method" radio button for Object Type. Specify MRCWORKLIB.Validate for the Class name, and valid_fields for the Method name. Click "Accept".
- Next, click on the "Parameters" icon for the external object you just created. Click "Create Parameter".
- Validity external objects require that the error message field is the first parameter used. It also requires that the description contains the text *VALID, the error message to be 99 alpha, and that the field is not required. By making this field non-required, we are allowing m-Power to pass this field a blank entry, and allowing it to receive the appropriate text from the Java program. Once this has been completed, press "Accept".
- Next, we should create two more parameters (for the start and end date). They need to be created in the same order they were listed in the Java program. So we will create Start Date first, then End date. Both fields should be 8,0 and be set to be Required Fields. They are required because they are both necessary for the external object to function correctly.
- We have now completed registering the object to m-Power, next we move on to calling the program from our application.
- Open your Maintenance or Report application, and navigate to the External Objects screen. Add your new external object to your application, using the *FLDVALID location (report users will use the *RUNVALID location), and mapping the 2nd and 3rd parameter. The *FLDVALID location will call your external object after your user submits the form, but before the data is written to the database.
After compiling and running my application, here is my result. As you can see below, I have entered a start date that has occurred after my end date. As a result, this error is returned to me and the data is not written to the table. In the second example, you can see that my application has correctly informed me that I need to specify an end date.
However, after correcting my date, you can see that no error message is returned and the data writes to the table successfully!
- The name of your .java file must match the class and file name. Notice in our example, we always used "Validate".
- In Java, case matters: Validate is different than validate.
- If you decided to build your java program through m-Painter, both the .java and .class files can be found in: \m-power\mrcjava\WEB-INF\classes\MRCWORKLIB
- Feel free to save this java object in any data dictionary, however you will need to change line 1 of your Java code to point to the correct data dictionary. Also, you will need to reference the correct data dictionary when registering your object's class path.
- If you would like to deploy your java external object programs via a jar file and using your own qualified package names, you can do so by placing the jar file in the mrcjava\WEB-INF\lib folder. Be sure to register each external object using the fully qualified class name (for example com.mrc.externalobjects.MyClass) in the "Class name" field.