Adding Business Logic

From JRapid

Jump to: navigation, search

Contents

Introduction

Based on your high-level application design, JRapid generates fully functional Java code for your enterprise application. While the generated files can save you a lot of time, your application may require additional customization. JRapid provides facilities for adding Java code, JavaScript, and CSS rules:

  • To help you add Java code, JRapid provides abstract classes with separate subclasses that you can extend. You can edit the source code in JRapid Designer or in Eclipse using the JRapid Plugin for Eclipse.
  • JRapid provides a well-organized project hierarchy (accessible in JRapid Designer and Eclipse) to which you can readily add auxiliary files containing scripts or CSS rules.
  • JRapid provides the Main.xml file, which defines your application. Including a reference to a custom file in JavaScript or CSS is simply accomplished by adding a one-line specification.

To describe how you add business logic to an application, we use a hypothetical CRM application as an example and perform the following tasks:

  • Create a Sale entity to record sales and a Sales Representative entity using the Web Designer.
  • Add Java code to calculate the commission for a sales representative when a new Sale entity is stored.
  • Add JavaScript to check the status property of a Sale entity and add CSS to display the salesDate field in red if the status is Urgent.

This shows how the resulting example will work.

Note: You will not be able to follow the entire tutorial running the customizations on the cloud environment if your project
is hosted in a Shared Development Server, as these do not allow developers to upload custom Java code.
You may test your customizations by running the application in a local development environment.
JavaScript, CSS and HTML files may be edited through the Files view in the JRapid Designer.

Creating the Entities

We created the Sale and SalesRepresentative entities for this example using JRapid Designer, as shown in the following figure.

Image:addbl1.jpg

The entities in the example are defined as follows:

  • A Sale entity for recording the details of a sale that uses the following properties:
      • salesDate (type: date) - The date on which the sale was recorded
      • salesRepresentative (type: entity) - The person who made the sale
      • total (type: double) - The dollar amount of this sale
      • status (type: enum) - Indicates state of the sale: New, Pending, Urgent, or Closed.
      • comments (type: text) - Optional text describing details of the sale
    • A Sales Representative entity for storing the basic information for a salesperson including the accumulated commission that uses the following properties:
      • firstName (type: string)
      • lastName (type: string)
      • accumulatedCommission (type: double)

When you specify the entities and their properties using the JRapid Designer, it stores the definitions in the Main.xml file. The Main.xml file is written in JRapid Modeling Language (AML), which uses XML-like tags. The following portion of the Main.xml file defines the two entities:

<entity label="Sales Representative" menu="Sales Representative" name="SalesRepresentative">
   <property display="primary" label="First Name" name="firstName"/>
   <property display="primary" label="Last Name" name="lastName"/>
   <property default="0.0" display="secondary" label="Accum. Commission" name="accumulatedCommission" type="double"/>
</entity>

<entity label="Sale" menu="Sales" name="Sale">
   <property default="now" display="primary" label="Date" name="saleDate" type="date" widget="jdatepicker"/>
   <property display="primary" entity="SalesRepresentative" label="Sales Rep." name="salesRepresentative"/>
   <property label="Status" name="status" type="enum"> 
      <enum>New</enum>
      <enum>Pending</enum>
      <enum>Urgent</enum>
      <enum>Closed</enum>
      <enum>Cancelled</enum>
    </property>
    <property label="Comments" name="comments" type="text"/>
    <property default="0.0" display="primary" label="Total" name="total" type="double"/>
</entity>

Note that although we created the entities using JRapid Designer, you can also type AML code directly into Main.xml.

Understanding the Generated Files

When you create a new entity or edit an existing one, the Code Generator automatically creates all the files for your application. These files are available in tree directories in both the Package Explorer in Eclipse and the file navigator in JRapid Designer. The Javasource folder contains the Java files generated for the application. The WebContent folder holds the web presentation files. The Main.xml, which holds the AML specifications for the application is also available in the tree. The following figure shows the Eclipse Package Explorer for this example.


Image:addbl2.jpg

Adding Java Code to a JRapid Application

For each entity in an application, JRapid generates both an abstract class file that contains the basic class operations and a subclass of the abstract class in which you can implement any modifications. You should never modify an abstract file; make your changes to the associated subclass only.

Each abstract file in the services folder (in this case, com.customcode1.services) contains a store method and a find method for that entity. You typically customize the behavior of an entity by overriding one or both methods. For this example, we have modified the Java code in the SalesServices.java file. The original version of SalesServices.java prior to our change contained the following code only:

package com.customcode1.services;

public class SaleServices extends SalesServicesAbstract { 

}

The new code for SalesServices.java overrides the store method in the abstract class to calculate and save the value for the commission accordingly depending on whether the sale is new or a change to old amount. The store method takes two parameters: id, which is the persistent ID for the Sale entity object and voobj, which is a bean-like java object that holds the values for the Sale entity properties defined by the XML code. As mentioned previously, the Code Generator creates a Data Access Object (DAO) layer that lets you look up entity information. In the example, we look up the entity information using id or voobj and the findBy method. Examples of DAO accesses are highlighted in green. The custom code for SalesServices.java follows.

package com.customcode1.services;

// Import the classes that define the entities.
import com.customcode1.entities.Sale;
import com.customcode1.entities.SalesRepresentative;

public class SaleServices extends SaleServicesAbstract {

// Set the commission at 10%.

static final double COMMISSION_PERCENTAGE = 10;

// Override the store method to calculate the commission.
@Override
public Object store(String id, Sale voobj) {

   // If it's a new Sale, assign commission to sales representative
   if("0".equals(id)) {
      // Get the Sales Representative persistent instance from DB
      SalesRepresentative salesRep = SalesRepresentative.DAO().findBy(voobj.getSalesRepresentative());

      // Calculate commission
      double commission = voobj.getTotal() * COMMISSION_PERCENTAGE / 100.0;

      // Add commission to the sales representative's accumulated commission
      salesRep.setAccumulatedCommission(salesRep.getAccumulatedCommission() + commission);
   }
   // If it's a Sale modification and Total changes, correct commission
   else {
      Sale storedSale = Sale.DAO().findById(id);
      // If Total has changed
      if(!storedSale.getTotal().equals(voobj.getTotal())) {
         // Get the Sales Representative's persistent instance from DB
         SalesRepresentative salesRep = SalesRepresentative.DAO().findBy(voobj.getSalesRepresentative());

         //Calculate commission awarded in previous total value
         double commission = storedSale.getTotal() * COMMISSION_PERCENTAGE / 100.0;

         //Remove commission from Sales Representative
         salesRep.setAccumulatedCommission(salesRep.getAccumulatedCommission() - commission);

         //Calculate commission for new Total 
         commission = voobj.getTotal() * COMMISSION_PERCENTAGE / 100.0;

         //Add commission to Sales Representative Total
         salesRep.setAccumulatedCommission(salesRep.getAccumulatedCommission() + commission);
      }
   }
   return super.store(id, voobj);
}

Adding JavaScript and CSS Files to a JRapid Application

Adding the JavaScript and CSS files is a three-step process:

  • Insert the new files into the project hierarchy.
  • Add content to the JavaScript and CSS files in Eclipse.
  • Add references to the files in Main.xml.

Adding the JavaScript and CSS File to the Project Hierarchy

In the current example we create new JavaScript and CSS files in which we add the new code and styles, but keep in mind that every JRapid project is created with the Main.js and Main.css files in the /WebContent/Main/js/ and /WebContent/Main/css/ folders respectively. This is where you can add your JavaScript and CSS customizations without the need of adding new files to your project, making it possible for developers on Shared Development Servers to use these features. These files are then included by default in every generated front end HTML.

As said, the js folder for JavaScript files and the css folder for CSS files are stored in the Main folder, which is contained in the WebContent folder. The following figure highlights the location of the files created for this example in the tree hierarchy.

Image:addbl3.jpg

Creating the JavaScript File for the Sales Commission Example

In the example, we call the JavaScript file myfunctions.js and store it in the js folder under Main. The code for myfunctions.js follows:

$('#sale_status').live('change', function() {
   if($(this).val() == 'Urgent') {
      $('#sale_saleDate').addClass('red_property');
   } else {
      $('#sale_saleDate').removeClass('red_property');
   }
});

The script tests the value of the status property in a Sales entity and changes the CSS class to red_property if the value is Urgent. Note that the script uses the jQuery selector $('#sale_status')to get the element representing the status property. The jQuery library is included in every JRapid project. Note also that the script uses the JQuery Live Event feature to attach the change event to the handler code, which tests for the status 'Urgent'. The Live Event feature ensures that all current or future elements that match the current selector will be handled. Once the page is loaded, if a new element is created and attached to the DOM, the handler will also be attached to it.

Creating the CSS File for the Sales Commission Example

The CSS file for the example is named mystyles.css, and is stored in the css folder under Main. The mystyles.css content defines a new class called red_property that specifies the background as red and the font as white as follows:

.red_property {
   background-color: red;
   color: white;
}

Adding References to the JavaScript and CSS Files in Main.xml

AML provides the following tags for referencing JavaScript and CSS files from Main.xml:

  • usescript specifies the location of the application's scripts by inserting a <script> tag in each HTML file in the application.
  • usestylesheet specifies the location of CSS files by inserting a <link> tag in each HTML file in the application.

We include the custom CSS file and the JavaScript file as shown in the following code snippet from Main.xml:

<config>
   <usestylesheet location="../jrapid-runtime/css/ui-lightness/jquery-ui-1.8rc2.custom.css"/>
   <usestylesheet location="css/mystyles.css"/>
   <usescript location="../jrapid-runtime/jquery-1.4.2.min.js"/>
   <usescript location="../jrapid-runtime/jquery-ui-1.8rc2.custom.min.js"/>
   <usescript location="js/myfunctions.js"/>
   ...

As a result, the locations of the script and CSS files are specified in the HTML files, as shown in the following snippet:

<script type="text/javascript" src="js/myfunctions.js">/**/</script>
...
<link href="css/mystyles.css" type="text/css" rel="stylesheet"/>

After all the changes have been made, the Sale entity appears with a red date when the status is 'Urgent', as shown in the following figure.

Image:addbl4.jpg

Summary

As this article has demonstrated, JRapid takes your basic model and generates files in an organized hierarchy so that you can readily find and add your own customizations.

For Java customizations, you typically override the find and/or store method in the appropriate subclass that extends the abstract class for the entity.

For JavaScript and CSS customizations, you create new files, add them to the hierarchy, and include references to them in the Main.xml file.

See also



Personal tools