jConnect for JDBC Programmer's Reference

Home

Storing Java objects as column data in a table

jConnect for JDBC Programmer's Reference

Chapter 2 Programming Information

Implementing advanced features

Handling error messages

jConnect provides two classes for returning Sybase-specific error information, SybSQLException and SybSQLWarning, as well as a SybMessageHandler interface that allows you to customize the way jConnect handles error messages received from the server.

Retrieving Sybase-specific error information

jConnect provides an EedInfo interface that specifies methods for obtaining Sybase-specific error information. The EedInfo interface is implemented in SybSQLException and SybSQLWarning, which extend the SQLException and SQLWarning classes.

SybSQLException and SybSQLWarning contain the following methods:

public ResultSet getEedParams( );
Returns a one-row result set containing any parameter values that accompany the error message.
public int getStatus( );
Returns a "1" if there are parameter values, returns a "0" if there are no parameter values in the message.
public int getLineNumber( );
Returns the line number of the stored procedure or query that caused the error message.
public String getProcedureName( );
Returns the name of the procedure that caused the error message.
public String getServerName( );
Returns the name of the server that generated the message.
public int getSeverity( );
Returns the severity of the error message.
public int getState( );
Returns information about the internal source of the error message in the server. For use by Sybase Technical Support only.
public int getTranState( );
Returns one of the following transaction states:
- 0 The connection is currently in an extended transaction.
- 1 The previous transaction committed successfully.
- 3 The previous transaction aborted.

Some error messages may be SQLException or SQLWarning messages, without being SybSQLException or SybSQLWarning messages. Your application should check the type of exception it is handling before it downcasts to SybSQLException or SybSQLWarning.

Customizing error-message handling

You can use the SybMessageHandler interface to customize the way jConnect handles error messages generated by the server. Implementing SybMessageHandler in your own class for handling error messages can provide the following benefits:

"Universal" error handling
Error-handling logic can be placed in your error-message handler, instead of being repeated throughout your application.
"Universal" error logging
Your error-message handler can contain the logic for handling all error logging.
Remapping of error-message severity, based on application requirements.
Your error-message handler can contain logic for recognizing specific error messages and downgrading or upgrading their severity based on application considerations rather than the server's severity rating. For example, during a cleanup operation that deletes old rows, you might want to downgrade the severity of a message that a row does not exist; you may want to upgrade the severity in other circumstances.

Error-message handlers implementing the SybMessageHandler interface only receive server-generated messages. They do not handle messages generated by jConnect.

When jConnect receives an error message, it checks to see if a SybMessageHandler class has been registered for handling the message. If so, jConnect invokes the messageHandler( ) method. The messageHandler( ) method accepts a SQL exception as its argument, and jConnect processes the message based on what value is returned from messageHandler( ). The error-message handler can:

Return the SQL exception as is.
Return a null. As a result, jConnect ignores the message.
Create a SQL warning from a SQL exception, and return it. This results in the warning being added to the warning-message chain.
If the originating message is a SQL warning, messageHandler( ) can evaluate the SQL warning as urgent and create and return a SQL exception to be thrown once control is returned to jConnect.

Installing an error-message handler

You can install an error-message handler implementing SybMessageHandler by calling the setMessageHandler( ) method from SybDriver, SybConnection, or SybStatement. If you install an error-message handler from SybDriver, all subsequent SybConnection objects inherit it. If you install an error-message handler from a SybConnection object, it is inherited by all SybStatement objects created by that SybConnection.

This hierarchy only applies from the time the error-message handler object is installed. For example, if you create a SybConnection object, myConnection, and then call SybDriver.setMessageHandler( ) to install an error-message handler object, myConnection cannot use that object.

To return the current error-message handler object, use getMessageHandler( ).

Error-message-handler example

The following example uses jConnect version 5.2.

import java.io.*;
 import java.sql.*;
 import com.sybase.jdbcx.SybMessageHandler;
 import com.sybase.jdbcx.SybConnection;
 import com.sybase.jdbcx.SybStatement;
 import java.util.*;
 
 public class MyApp
 {
   static SybConnection conn = null;
   static SybStatement stmt = null
   static ResultSet rs = null;
   static String user = "guest";
   static String password = "sybase";
   static String server = "jdbc:sybase:Tds:192.138.151.39:4444";
   static final int AVOID_SQLE = 20001;
 
   public MyApp()
   {
      try
      {
               Class.forName("com.sybase.jdbc2.jdbc.SybDriver").newInstance;
               Properties props = new Properties();
               props.put("user", user);
               props.put("password", password);
       conn = (SybConnection) 
       DriverManager.getConnection(server, props);
       conn.setMessageHandler(new NoResultSetHandler());
       stmt =(SybStatement) conn.createStatement();
       stmt.executeUpdate("raiserror 20001 'your error'");
   
     for (SQLWarning sqw = _stmt.getWarnings();
       sqw != null;
       sqw = sqw.getNextWarning());
     {
       if (sqw.getErrorCode() == AVOID_SQLE);
       {
         System.out.println("Error" +  sqw.getErrorCode()+ 
           " was found in the Statement's warning list.");
         break;
       }
     }
     stmt.close();
     conn.close();
   }
   catch(Exception e)
   {
     System.out.println(e.getMessage());
     e.printStackTrace();
   }
 }
 
 class NoResultSetHandler implements SybMessageHandler
 {
   public SQLException messageHandler(SQLException sqe)
   {
     int code = sqe.getErrorCode();
     if (code == AVOID_SQLE)
     {
       System.out.println("User " + _user + " downgrading " +
         AVOID_SQLE + " to a warning");
       sqe = new SQLWarning(sqe.getMessage(),
         sqe.getSQLState(),sqe.getErrorCode());
     }
     return sqe;
   }
 }
 
 public static void main(String args[])
 {
   new MyApp();
 }


	Expand Search