Basic Swift App tutorial

Tutorial Installation

• Download the tutorial code here here
• Download a zipped copy of these pages here
• UNZIP the tutorial to a subdirectory of your choice
• Set your classpath to include
  • current directory '.'
  • the directory above current directory ..\
  • The swiftapp API jar swiftappj.jar from the main swiftappj distribution
  • The MMMYSQL driver jar file (mysql.jar or mysql_uncomp.jar depending on which version of MMMYSQL you have) NOTE:This API has been tested with MMMYSQL version 1.2c but should also work with any later version.
  • dg_code.jar from the dg_coder distribution
  • The main runtime jar file rt.jar (usually in \jre\lib under the JDK install directory) such as c:\jdk1.3\jre\lib\rt.jar
  • on my system all jar files are in c:\jars so my classpath is:

    SET CLASSPATH=..;.;c:\jdk1.3\jre\lib\rt.jar;c:\jars\mysql_uncomp.jar;c:\jars\swiftappj.jar;c:\jars\dg_code.jar
    

Getting started...

• This tutorial is arranged into a number of basically self contained subdirectories step1 ,step2 etc.
• Each of these contains a working version of the application.
• The application is created in small steps to illustrate the process of application creation.
• By the last step, we will have developed a relatively complex customer and order entry application
• NOTE: Each step directory containes a subdirectory called dgregtest which contains the compiled class files for each version of the application.
• Sample classes and the design tools can be run at any stage of application creation by changing directory into the proper subdirectory and proceeding as explained below.
• Comments are added at various stages to allow code changes from step to step to be easily seen.
• The intent here is to allow the code for an application to be studied in relatively small steps to serve as an easy-to_follow example of application creation.

To run the sample at any stage:
• Make sure your classpath is set as described above
• Change into the proper subdirectory /Step1 ,/Step2 etc
• Run the appropriate batch file:
  • dg_coder.bat loads the user interface for the app into dg_coder (you may also just look at the .java source directly )
  • form_design.bat loads the sample form into the SQL form designer
  • run.bat actually runs the application

---

• Step1

  At this step (3) things have been done

  • The file create_sample.txt has been used to create and pupulate a sample SQL table . The sample table used is just a simple customer file. NOTE:This script is designed to be run multiple times from the GUI CLIENT to populate the sample table
  • The form designer has been used to connect to MySQL and create an entry form and associated code. NOTE: the batch file form_design.bat can be run to invoke the form designer with the sample form
  • A basic form class (dgreg_test_form.java ) has been generated NOTE:Generated code should never be modified. Any changes to default form behavior must be done in a class which extends the basic form!!

    ---

  • Open a dos window
  • Change into the \step1 directory

    The base form may be run by

      java dgregtest.dgreg_test_form
    

  • A class extending the base form (ovr_dgreg_test_form.java ) has been created.

    At this stage, no methods have been overridden but the extended form may be run by

      java dgregtest.ovr_dgreg_test_form
    

  • All .java source files in the \step1 directory may be compiled by running

    build.bat
    

  • At this stage, the generated form class has most of the code needed for data entry and maintenance of the sample customer table. Several more steps are needed to allow it to actually be connected to the database and run 'live'
  
  
  
  Fields on the form are active (except for CUST# which is the primary key for the table.
  
  
  The field labelled "class_combo_loc" will be used later to add a JComboBox to the form

  ---

• Step2

• At this stage , dg_coder has been used to start creating a basic User interface for our sample application. The main frame contains a JTabbedPane with several several tabs. Several standard API objects have been added:
• On the tab labelled "main"
  • Our extended form (dgregtest.ovr_test_form) has been added at the upper left
  • A standard API object (com.wicolor.form.std_form_buttons) has been added. In a later step, this will be connected to the form to control basic app function.
  • NOTE: The lower area of the "main" panel has been left empty to be used at a later step.
  • Two other panels have also been added.
    
    • "browse tab" containing another standard API object (com.wicolor.db.std_table_browse ) which will be customized to look up customers in our sample table
    • " "MULTIPLE SELECT BROWSE" which contains another standard API class ( com.wicolor.db.mult_browse ) which will be customized into a more complex lookup control.
      

  ---

• Step3

  • We have added code at several places :
    • imports of necessary classes
      • import com.wicolor.app_desktop.*; // app_desktop API classes
      • import com.wicolor.db.*; // database connectivity and User interface API
      • import java.sql.*; // Normal
    • At this step we have added several more non-visual API objects

      /** declarations of added Objects
      
      
      */
      
      /** this standard API object will manage database connections 
      for this application */
      public  connection_manager manager = null;
      /** this standard API object will allow tuser input 
      to be easily blocked during database queries or other
      time consuming operations*/
      public blocking_pane blocker;
      
      /** standard data_table_model , will be used for updates
      by the form, and will be used as a general_purpose coneecttion to the database
      */
      data_table_model util_mod = null;
      
      /** reads property file to get database url
      actual file is at ../../dg_url.txt
      
      NOTE:Change this file to match the actual URL
      of your database server
      If MySQL is running on your local machine
      the default
      jdbc:mysql://localhost:3306/test
      
      should work
      
      When MySQL is installed , this database is accessible to any user
      without a password
      
      
      
      
      
       
      
      
      */
      properties_from_file init_props = null;
      
      /** string for database URL */
      String URL = null;
      
      /** will hold reference to database connection */
      Connection app_con = null;
      
      
      
      

      ---

    • Added objects initialized as follows

      
      /** initialize the connection manager */
       manager = new connection_manager(this);
      /** load the default driver*/
      manager.load_default_driver();
      /** initialize the blocking pane and set it as the JFrame's glasspane */
      blocker  = new blocking_pane(this,true);
      setGlassPane(blocker);
      /** initialize the data table model */
      util_mod = util_mod = new data_table_model(null,this,false);
      /** open properties file, get the url */
      try{
      init_props = new properties_from_file("/dg_url.txt"  );
      URL = init_props.getProperty("url");
      JOptionPane.showMessageDialog(null,        
      URL,			
      "URL!!",      JOptionPane.INFORMATION_MESSAGE);
      }
       catch (Exception e)
        {
      JOptionPane.showMessageDialog(null,        
      "CANNOT READ URL \n APPLICATION WILL NOT BE STARTED ",			
      "ERROR OCCURRED!!",      JOptionPane.ERROR_MESSAGE);
      System.exit(0);
        }
      
      

  ---

• Step4

  • At this stage we add some code to actually connect to the database
    • A method is added to initialize the connection
      the connection_manager takes care of the details such as showing the login dialog . It will allow (4) tries then exit if the proper username and password is not used.

      /** sets up connection browse, update  models  */
      public boolean init_connection(String connect_str)
      {
      /** this shows the login dialog and tries to connect */
      connection_manager.qualified_connection c2 =
      manager.get_qualified_connection(connect_str);
      if (c2 == null) // check if we got a connection
      {
      app_con  = null;
      return false;
      }
      else
      {
      app_con = c2.conn;
      /** connect the util_mod data_table_model */
      util_mod.submit_qry(app_con,
      manager.get_statement(app_con));
      /** connect the browse table's model to the database */
      browse1.get_model().submit_qry(app_con,
      manager.get_statement(app_con),test_form.get_select_string());
      
      NOTE: To have correct function in the next steps,
      you must  use the SQL select generated by the form by using
      " test_form.get_select_string() " as an initializing query.
       
      
      
      /** actually run the browse to display some records */
      browse1.get_model().run_qry();
      /** return true if everything is OK */
      return true;
      }
      
      }
      

    • A method is added to cleanly disconnect
      this just tells the connection_manager to cleanly shut down the connection NOTE: connection_manager can have multiple connections going at a time

      public void drop_connection()
      {
      System.out.println(" drop connection top");
      manager.cleanup_connection(app_con);
      
      }
      
      
      

    • A call to init_connection() is added near the end of the constructor

      /** try to connect , exit if not */
      if (! init_connection(URL))
      {
      JOptionPane.showMessageDialog(null,        
      "CANNOT CONNECT TO URL \n APPLICATION WILL NOT BE STARTED ",			
      "ERROR OCCURRED!!",      JOptionPane.ERROR_MESSAGE);
      System.exit(0);
      }
      

    • A WindowAdapter is added to make sure the connection is cleaned up when the application exits

      /** add a WindowAdapter to close Connection on exit */
      addWindowListener(new WindowAdapter() { 
      	public void windowClosing(java.awt.event.WindowEvent ev) 
      	{	
       {
      drop_connection();
      
      }}
      
      
      });
      
      

  • use the run batch file in the \step4 directory, you will be shown a login dialog if you supply a valid login and password ( and your database is running) you should see something like the following:
  

  ---

• Step5

  • If we've gotten this far, we have a basic connected application, but have no control over it
    • First , we add some code in the init_connection() method to connect the form to the table browse and form buttons

      /** connect the button panel and browse to the form */
      button_p.set_refs(browse1.get_model(),
      util_mod,
      this,
      test_form);
      

      Where parameters are:

      • The underlying data_table model for the browse , initialized with the SQL query generated by the test form
      • A second connected data_table_model to be used for validation and commoitting of changes
      • A reference to the parent JFrame conteining the applicatopn
      • A reference to our test form.
    • Next, we add some standard lookup controls to the browse

      /** add some lookup controls to the browse panel */
      browse1.get_browse_pan()
      .add_selector("CUST# ","DCUST_MAST.DCMST_NUM",data_table_model.TEXT,false);
      
      browse1.get_browse_pan()
      .add_selector("name ","DCUST_MAST.DCMST_NAME",data_table_model.TEXT,false);
      browse1.get_browse_pan()
      .add_selector("address ","DCUST_MAST.DCMST_ADRS",data_table_model.TEXT,false);
      
      browse1.get_browse_pan()
      .add_selector("CITY ","DCUST_MAST.DCMST_CITY",data_table_model.TEXT,false);
      
      
      

    • For these controls several things need to be specified:
      • A label to display to the user such as "ADDRESS"
      • The actual name of the field to be looked up such as "DCUST_MAST.DCMST_ADRS"
      • The type of the field NOTE:these examples all are for text fields, but there are several other types NUMBER,DATE,TIME,LOGICAL
    • Function is as follows
      • Tabs above the selectors allow the user to choose whch field to look up on
      • the combobox at the left allows several type of selection to be used such as starts with, ends with etc
      • AND button ands the current selection onto what has been looked up
      • The RST button resets the control so the next time "AND" is clicked only the current field is used to narrow the selection.
      • The "AND" button will narrow the selection of records until "RST" is clicked again
      • "Clear" button clears the entry field
      • The records are shown ordered by the last field selected.
      • Using the "BETWEEN" condition with both entry fields cleared returns all records. NOTE:These selectors are designed to be used in situations where only one or a couple steps are needed to find the correct record. In a future step, we will set up a "mult_browse" which can be used for more complex ad-hoc queries
      • The Form buttons are now also connected, allowing the user to edit,add, save and delete records as well as goto next or previous record.

  ---

• Step6

  In the next few steps we will extend the form to add validation , and a way to set the customer's class.
  • All functions performed by the generated form , such as INSERT,UPDATE,DELETE are performed on separate threads. This allows the application's user interface to behave properly even if
  • The generated form contains a number of

     public boolean pre-XXX()
      and 
    public boolean post-XXX()
     methods.
    

    By default, these methods do nothing, but may be overridden to add processing to the basic functionality of the form

  • The form also has a facility for adding references to connected data_table_models , this allows connected data sources to be used in validation.
  • It ia also posible to add User interface objects to the form.
• In this step we will do several additions to the code for the overridden form:

  ovr_dgreg_test_form.java
  
  

  • We will add code to allow a JComboBox to be used to set customer class to be set to one of the following three values

    "WHS" for wholesaler
    "RET" for retailer
    "RES" for residential
    
    

  • We will set up a reference to out util_mod data_table model so it can be used for validation
  • We will add a statement_preparer to allow a lookup to be done to check for uniqueness of added customer numbers.
• Code additions are as follows:

  • :/** step 6 added declarations */ 
    /** this will function similarly to a prepared statement, and allow us to check exist
    ence of a customer number before allowing an insert */
    statement_preparer  exist_check  =  new  statement_preparer(  
      "  SELECT  COUNT(  *  )  from  DCUST_MAST  WHERE   DCMST_NUM = ?   "  
      )  ;  
    data_table_model util_mod = null;
    JComboBox class_combo = null;
    

    :/** overridden constructor, to initialize the JComboBox and add it
    */ 
    
    
    public ovr_dgreg_test_form()
    { super();
    class_combo = new JComboBox();
    //use the placeholder in the form to set it's size
    class_combo.setBounds(form_design_CLASS_COMBO_LOC.getBounds());
    /** add the combo box 'on top of' the placeholder
    form elements are on two levels , the upper control_lev, and the lower box_lev
    this is designed so actual controls are always accessible even when they are 
    surrounded by labels or boxes.
    */
    add(class_combo,control_lev);
    class_combo.addItem("WHS");
    class_combo.addItem("RET");
    class_combo.addItem("RES");
        
    /** add an ActionListener to set the form value when combo selection is changed
    */
    class_combo.addActionListener(
    new ActionListener()
    {
    public void actionPerformed(ActionEvent e)
    {
    set_field_value(  "DCUST_MAST","DCMST_CLASS",class_combo.getSelectedItem()) ;
    }}); 
    } // end of constructor
    

  • /**  overridden to set ref to external model in this class  
    this is done for convenience in referencing the added model
    */ 
      
     	  public void add_extern_model(data_table_model ext_mod)   
     	  {  
     		if (external_models.size() == 0)  
     		{  
      			util_mod = ext_mod;   
      		}  
      		super.add_extern_model( ext_mod) ;  
         }  
    
    

  • The following code is added in dgreg_test_app.java to connect the external data_table_model to the form.

    /** in init_connection() connect the util_mod to the form*/
    
    
    test_form.add_extern_model(util_mod); 
    

  • At this stage, the only visible addition is the JComboBox
  

  ---

• Step 7

  In this step , we will override several methods to allow validation ,and improve the behavior of our saample application.

  • We will add validation code to check :
    • That a unique 3-character code has been entered if a new record is being added
    • That Customer name and class are filled; a record will not be allowed to be saved if these are not filled
    • We will warn the user if zip code or region are not filled in, but allow to save anyway
  • Added code:

    
    
    
     /** these are overridden just to control when cust number field is enabled
    makes sure it is not when existing record is being edited */
    
    
      public boolean pre_load_record()   
     	{  
     		 DCUST_MAST_DCMST_NUM.setEnabled(false);  
      
     		return true;}  
       
     public void clear_form_values()  
     	{     
    
             DCUST_MAST_DCMST_NUM.setEnabled(true);  
        		super.clear_form_values();  
       
     	}
    
     /** these are overridden just to clear
    the form after insert or update */
     public boolean post_insert()  
     	  {  
     		  clear_form_values();  
     		  return true;  
     	  }  
     public boolean post_update()  
     	  {  
     		  clear_form_values();  
     		  return true;  
     	  }  
     
     public boolean post_delete()  
     	  {  
     		  clear_form_values();  
     		  return true;  
     	  }  
    
      
    

  • /** check record before inserting 
    
        This is pretty much a mechanical process, just check values in the form 
        either internally , or as in the case of CUSTOMER number , check by doing
        a database lookup . return true if everything is ok. show a dialog and give
       the user a choice to save or not if optional stuff is missing
        the call to 
      
             button_p.reset_for_new();  
            just re-sets the button panel for another try
    
          pre-update is basically the same, except it assumes we have a
          valid customer number if we're editing an existing record.
           
    
    
    
           */  
    
     
    	public boolean pre_insert() 
    	{	/** check  fields for filled before insert */ 
    		StringBuffer msg_buf = new StringBuffer(); 
    		boolean insrt_ok = true; 
                boolean ok_to_check = true ;
     
    
    // check pieces of primary key 
    
     		String tmp_str0 = (String)DCUST_MAST_DCMST_NUM.getValue(); 
    		if ((tmp_str0 == null) || (tmp_str0.trim().length() != 3)) 
    		{ 
    			insrt_ok = false; 
                      ok_to_check = false ; // if not 3 chars , bypass next check
    			msg_buf.append(" DCMST_NUM  MUST BE THREE CHARACTERS\n" ); 
    		} 
                String tmp_str1 = (String)DCUST_MAST_DCMST_NAME.getValue(); 
    		if ((tmp_str1 == null) || (tmp_str1.trim().length() <5 )) 
    		{ 
    			insrt_ok = false; 
                      ok_to_check = false ; // if not 3 chars , bypass next check
    			msg_buf.append(" NAME MUST BE AT LEAST 5 CHARACTERS \n" ); 
    		} 
                 String tmp_str2 = (String)DCUST_MAST_DCMST_CLASS.getValue(); 
    		if ((tmp_str2 == null) || (tmp_str2.trim().length() != 3)) 
    		{ 
    			insrt_ok = false; 
                      ok_to_check = false ; // if not 3 chars , bypass next check
    			msg_buf.append(" CLASS MUST BE FILLED IN\n" ); 
    		} 
                String tmp_str3 = (String)DCUST_MAST_DCMST_ZIP.getValue(); 
    		if ((tmp_str3 == null) || (tmp_str3.trim().length()<5 )) 
    		{ 
    			
                      
    			msg_buf.append(" WARNING: ZIP NOT FILLED IN\n" ); 
    		} 
    
                String tmp_str4 = (String)DCUST_MAST_DCMST_REGION.getValue(); 
    		if ((tmp_str4 == null) || (tmp_str4.trim().length()<4 )) 
    		{ 
    			
                      
    			msg_buf.append(" WARNING: ZIP NOT FILLED IN\n" ); 
    		} 
    
    
                   /** this is skipped in pre_update()
                     this actually checks the database to see if the customer number 
                 to be inserted already exists
    
                      */
     			if (ok_to_check) 
    		{ 
                     exist_check.set_object(1,DCUST_MAST_DCMST_NUM.getValue());
    			  
    			Vector is_exist = util_mod.run_immediately(exist_check.get_string()   ); 
    			if (util_mod.exists(is_exist)) 
    			{ 
    				insrt_ok = false; 
    				msg_buf.append("   ALREADY EXISTS\n" ); 
    			} 
    		} 
    
                
                
                if (insrt_ok== false )// errors in addition to warnings 
    		{ 
    			set_err_msg(msg_buf.toString()); 
    			if (button_p != null) 
    				button_p.reset_for_new(); 
    			return false; 
    		} 
    		else // if just warnings , show , let user decide to save or not 
    			if (msg_buf.length() >10) 
    		{ 
     		int is_ok = JOptionPane.YES_OPTION;   
     			msg_buf.append( "DO YOU WANT TO SAVE ANYWAY\n");  
     			is_ok = warning_dialogs.show_confirm_dialog( parent_frame,   
     			new scrol_dialog_txt(msg_buf.toString())  
     			, " SOME VALUES MISSING !!!",   
     			JOptionPane.YES_NO_OPTION, JOptionPane.WARNING_MESSAGE  
     			,warning_dialogs.NO_BUTTON);   
     			if (is_ok != JOptionPane.YES_OPTION)  
     			{  
     				set_err_msg(" CURRENT OPERATION ABORTED \n"   
     				+ " BY USER ");   
     				if (is_ok == JOptionPane.NO_OPTION)  
     				{  
       
                                   
     					if (button_p != null)  
     						button_p.reset_for_new();  
     				}  
     				else  
     					clear_form_values();  
       
     				return false; // false if want to continue editing  
     			}  
       
     		}  
       
     		return true;  
     	}  
    
    

At this stage our program behaves pretty well, play around with it and see what it does.!!

---

• Step 8

  Next, we will get a little fancier

  • Using the SQL CLIENT create a simple table of sales regions

    CREATE TABLE REGIONS(
    REG_NUM CHAR(4),
    REG_NAME CHAR(20)
    );
    
    Populate it with the following:
    
    INSERT INTO REGIONS VALUES ('0001','REGION OOO1');
    INSERT INTO REGIONS VALUES ('0002','REGION OOO2');
    INSERT INTO REGIONS VALUES ('0003','REGION OOO3');
    INSERT INTO REGIONS VALUES ('0004','REGION OOO4');
    

    At this point, we will not do any fancy validation, all this table is for is to demonstrate the use of record select tables

  • Next , we add a com.wicolor.card_panel at the botton of the main user interface panel. NOTE:card_panel is a user interface control which allows a bunch of components to be in the same screen space with only one showing. It is more compact then a JTabbedPane

    the side buttons labelled "<" and ">" can be used to cycle 
    through all components in the card_panel
    
    

  • Inside the card_panel add a com.wicolor.db.horiz_record_select_table
  • Next code is added to init_connection() to connect the selector:

    /** connect it to the form 
    this will send the selected row to a method called
    public void set_from_vector(Vector v,int form_idx)
    
    which we will implement in the form below
    */
    sel_tab.set_form_ref(test_form,1);
    /** connect the selector */
    sel_tab.get_model().submit_qry(app_con,
    manager.get_statement(app_con)," SELECT * from REGIONS");
    /** actually run the browse to display some records */
    sel_tab.get_model().run_qry();
    
    
    

  • Code is also added to the ovr_dgreg_test_form class

    /**  allows selectors etc to be 
    	  wired by setting an entry_form reference, to  set 
    	  form values  ; multiple controls can use this method, can tell 
            them apart    by  their int index */ 
    	public void set_from_vector(Vector v,int form_idx) 
    	{ 
                     if (form_idx ==1)
                 set_field_value(  "DCUST_MAST","DCMST_REGION",
                     v.elementAt(0) );
    	} 
    

  • Similarly to the normal browse table, selectors are added to the horiz_record_select_table

    sel_tab.add_selector("NUMBER ","REGION.REG_NUM",data_table_model.TEXT,false);
    sel_tab.add_selector("NAME ","REGION.REG_NAME",data_table_model.TEXT,false);
    

  At this point region codes can be looked up in the lower selector, clicking the "set form field" button sets the region field of the form

  Validation also works