Product Documentation

• The following resources are expensive and should be watched carefully
   
  • Database connections
  • Prepared statements
  • Result sets
• For any resource you use
   
  • After opening the resource, you must close it when you are finished with it
  • Resources should be initialized within a ‘’try’’ block
  • Resources should be closed or de-allocated within a ‘finally’ block.

Database Connections

• These are an expensive and finite resource
• Remember to close all connections you open, once your code has completed using them
• Failing to do so can lead to obscure problems “down the line”, when other processes run out of available connections in the available connection pool
• The number of connections and their time to live is controlled in the Configuration.properties file. This is an excerpt of the file with these settings –
  

  # Connection pool settings
  ConnectionPoolSize    = 10
  ConnectionPoolMax     = 200
  ConnectionUseCount    = 500
  ConnectionTimeout     = 10
  ConnectionPoolTimeout = 20

• Note that database connections should not use con.close
• Name the connection you open with the name of the method that opens the connection. This makes debugging using ConnectionPoolMon simpler as all connections using this name will be visible (all ExtraView connections are anonymous)
• Example -
  

  public void frSelectList(SesameSession session, ValidationList selList,  
  		String pGlobal, HashMap selectedVals, HashMap attributes)
    {
  
    // code removed for clarity
  
    try{  con = Z.pool.getConnection();
            sql = "select security_user_id, first_name || ' ' || 
                  last_name from security_user";
            pstmt = con.prepareStatement(sql);
            rs = pstmt.executeQuery();
            selList.put( "$$USER$$","* Current User Name *");
            while(rs.next()) {
                  selList.put( rs.getString(1), rs.getString(2));
            }
            pstmt.close();
          }
          catch(SQLException sqle) {
              Z.log.writeToLog(Z.log.ERROR, 
               "UserCustom.getAllowedValues SQLException: " + sql);
              ErrorWriter.write(sqle, ErrorWriter.LOGERR);
          }
          catch(Exception e){
              ErrorWriter.write(e, ErrorWriter.LOGERR);
          }
          finally{  if (con != null) Z.pool.close(con);
          }
        }
          return;
      }

Values

• Values within User Custom are generally objects such as Problem and Problem_UDF. They are stored as Strings or String Arrays in a hashmap (such as Problem Form Parameters) or as objects in the SesameSession Object
• Class and method variables can be any of these
• Generally, Strings and String arrays are used on the "user-facing" side, and Objects or ArrayLists of objects when dealing with the database
• It is generally easier to use the user facing ProblemFormParameters to manipulate data rather than the ArrayLists, so wherever possible, do the coding in these routines
• These are identifiable easily by the parameter lists
• In exits that are database oriented (primarily the ucAddPreInsert, ucEditPreUpdate ucAddPostInsert and ucEditPostUpdate routines) it is necessary to work with the Objects directly as well as the form parameters
• The session object can be used to store objects of arbitrary size, but this uses memory, and care should be taken to remove the object when it is no longer needed to prevent wasteful memory usage
• The memory will ultimately be returned when the session is invalidated, but depending on the session timeout, this can take some time.

Turning on Tracing of User Custom Calls

• To see all the calls to user custom methods and their timing information
  • As an ExtraView Administrator set USER_CUSTOM_ENABLE_METRICS = YES
  • View the log output using either tail –f evj.log (Unix / Linux) or an editor (Windows)
  • As you use ExtraView, the log will dynamically show the user custom methods called
• After Apache Tomcat (or your application server) is bounced, the log shows the current user custom class in use –
  

  2003-12-26 14:35:52 [  info   ]
  USER_CUSTOM_CLASSNAME=com.extraview.usercustom.myUserCustom3

• After Tomcat is bounced, the log shows the log’s name –
  

  2004-01-02 14:00:18 [  info   ]
  Manage Log Files Entered, prefix= art  , suffix= .log

• You can specify the name of the log file, which can make it easier to find the log you are using during development by modifying the ExtraView configuration file. The name of the log file is set in the file named Configuration.properties. This is stored in the directory named –
  
  %TOMCAT-HOME%\webapps\art\WEB-INF\configuration

  There will be a line like the following defining the log file’s name –

  LOG_FILE_PATH_NAME = logs/EVJ.log
• To make it easier to find you debug output in the log, with an editor select and delete the contents of the log before starting a debug run
• When tomcat is bounced, the log shows the database used by ExtraView and the user custom class that’s currently in use.

Determining your Code’s Performance

• To determine the performance impact of your user custom methods, turn on user custom metrics. Timing information will then be emitted to the ExtraView application server log
• To turn on tracing and metrics
  • Logon to ExtraView as an a user with administrator privileges
  • Select the Behavior Settings screen and set the value of the the behavior setting named USER_CUSTOM_ENABLE_METRICS to a value of YES
  • ExtraView will now make alog entry every time a user custom method is called and each entry has the number of milliseconds the call took to execute
  • If one of your user custom methods takes a second or longer to execute, it is probably degrading ExtraView’s performance significantly.

Determining Useful Methods of a Class

• An IDE (Integrated Development Environment) like Eclipse will show all the methods in a class. The debugger will show the value of objects, such passed user custom method parameters and ExtraView objects like Z
• To determine what is either useful or available from a user custom method parameter, look at its getXXX methods. For example, the SesameSession class has the following available methods
  • getUserId
  • getUserRole
  • getRemoteAddress
  • getArea
  • getProject
  • etc.
• Looking at the class’s Javadoc is another way to explore a class’s available methods. The getters and setters are typically the ones of most interest to the User Custom programmer

Log Your Messages

• The user custom method w(String) is an easy way to write debugging messages to the log
• By default, the messages will be at the level of WARN messages, making them easy to find
• The Z.log.writeToLog() method also writes to the log.