Using Entry and Exit Trace Points

Consider these guidelines before adding entry and exit trace points to your code:

• Use Trace.Level1 entry or exit trace points for all Identity Manager component external interface methods, which are the public methods declared in the resource adapter interface.

• Use Trace.Level2 entry or exit trace points for significant non-public methods including constructors and static methods or methods not included in the Identity Manager component external interface.

• Specify arguments in the trace points.

  If the argument is not a primitive type or java.lang.String, and the argument requires any kind of object creation or method calls, conditionalize the entry trace point so that the formatting work is only done when tracing is enabled.

• When specifying an exit trace point, show the return value if the method is a primitive type or java.lang.String. If the return value requires some sort of formatting, conditionalize the object formatting as specified in these guidelines. Use the following:

  int getLevel() int getLevel (Method) boolean isLogging(level,method) boolean level1 (method) boolean level2 (method) boolean level31 (method) boolean level4 (method)

• If you are tracing information that requires appending several java.lang.Strings together, use java.lang.StringBuffer instead of java.lang.String. Appends are faster using java.lang.StringBuffer. Also, conditionalize as in the preceding bullet item.

• When adding entry or exit trace points for significant constructors, remember that you cannot place a trace point before a this() or super() method call within a constructor. Put the entry trace point immediately after the this() or super() method call.

• Do not use an exit trace point to trace an exception condition. If the method throws an exception, use an exception trace point at the same trace level as the entry or exit trace point just before the exception is thrown. See Using Exception Trace Pointsfor more information.

  If a method contains an entry trace point, that method also must contain a code path that executes either a throwing method, a caught method, or an exit.

Following are some simple entry and exit trace statements. For these examples, assume the following CLASS variables are declared for each statement.

private static final String CLASS = 
"com.waveset.adapter.MyResourceAdapter"; 
protected static Trace _trace = Trace.getTrace();

Example 5–1 Entry Trace Point Example

final String METHOD = methodName; 
_trace.entry(_trace.LEVEL1, CLASS, METHOD);
_trace.entry(_trace.LEVEL1, CLASS, METHOD, user);
if (_trace.level1(CLASS, METHOD)) {    
_trace.entry(_trace.ALWAYS, CLASS, METHOD,
user= + user); 
}

// Show the size of an array argument
// ASSUME: password is an argument to the method
// Note the use of the Util.length() method. It is
// a convenience method that guards against null.
if (_trace.level1(CLASS, METHOD)) {
    StringBuffer sb = new StringBuffer(32);
    sb.append(password length=);
    ab.append(Util.length(password));
    _trace.entry(_trace.ALWAYS, CLASS, METHOD, sb.toString());
}

Example 5–2 Exit Trace Point Example

_trace.exit(_trace.LEVEL1, CLASS, METHOD);

_trace.exit(_trace.LEVEL1, CLASS, METHOD, returnValue);
if (_trace.level1(CLASS, METHOD)) {
    _trace.exit(_trace.ALWAYS, CLASS, METHOD,
      returnValue != null ? returnValue.getName() : returnValue);
}

// Show the size of an array 
String[] accounts = ... 
if (_trace.level1(CLASS, METHOD)) {    
    StringBuffer sb = new StringBuffer(32)
    sb.append(accounts length=);    
    ab.append(accounts.length);    
    _trace.exit(_trace.ALWAYS, CLASS, METHOD, sb.toString()); 
}