Null-checking Methods Example

Flow Analysis will analyze methods in the analysis scope. Null-checking method parameterizations are required when the methods are out of the scope of the current analysis (e.g. third-party libraries). The classes in the following example are defined in a different assembly and are outside the scope of the analysis (UString). The class uses static methods to manipulate code with Java strings in various ways, including the UString.isEmptyOrNull(String), which is defined:

public class UString
{
    static boolean isEmptyOrNull(String variable)
    {
        if ((variable == null) || (variable.length() == 0)) {
            return true;
        }
        return false;
    }
}

And there is the following class, which is analyzed by Flow Analysis’s BD-EXCEPT-NP rule:

public class SomeClass
{
    void someMethod(String variable)
    {
        boolean flag = variable == null; // violation search starts here
        if (UString.isEmptyOrNull(variable)) {
            /** 
             * In case variable is null, we will always get to this branch of the if clause.
             */
            System.out.println("String is empty");
        } else {
            variable.toString(); // FALSE POSITIVE BD-EXCEPT-NP VIOLATION
        }
    }
}

Flow Analysis assumes that the return value for the method isEmptyOrNull() is unknown. This is because the method is not in the analysis scope. Flow Analysis will analyze the then and else branches of the if statement and find a violation in one of these statements. Calling this method, however, returns true when the variable is null.

By adding UString.isEmptyOrNull() to the list of methods in the Null-checking Methods parameterization with the specified return value, Flow Analysis will not report a violation if the tracked variable is passed to this method. This is because the wrong branch of the if statement will not be analyzed, resulting in an avoided false positive.

Null-checking Methods Restrictions

Methods added to this parameterization should be static methods that have a primitive boolean return value. This restriction is managed to avoid excessive complications in parameterization and ensuring that there are no other variables that could affect the result of the null-checking method. 

The Resource allocators table can be completed with the descriptors of methods that can produce a resource. The table has the following columns:

• Enabled: specifies whether the allocator should be considered during analysis.
• Fully-qualified type name (wildcard): the fully-qualified name of the type where the method is declared. Use '*' if you want to describe a function declared in any type, or a global function declared outside of any type.
• Method name (wildcard): the name of the allocating method. '*' can be used to denote any number of any symbols.
• Resource parameters: specifies that the method allocates a resource in one or more of its parameters. In this case, either specify a 1-based number of the parameter that is allocated by the method, or use '*' to denote that all of the parameters are allocated.
• + definitions in subclasses: a check box that indicates whether the definitions (of methods with the given name) in subclasses should be considered allocators as well. Note that this applies to both instance and static methods.
• "this" object is a resource: a check box that indicates that the method allocates a resource in the object on which the method is called.
• Returns a resource object: a check box that indicates that the method returns an allocated resource.

It is common that allocation methods return an error code to indicate allocation failure. When an allocation method returns a resource, a NULL value normally indicates an allocation failure. When Flow Analysis is looking for resource leaks, it needs to understand if allocation succeeded or failed; this helps it report only missing calls to deallocation methods on paths where allocation actually occurred. In cases where a resource allocator method returns a resource, Flow Analysis assumes that the resource is successfully allocated if the returned value is not NULL.

The Resource closers table can be completed with the descriptors of methods that can close a resource. The table has the following columns:

• Enabled: specifies whether the closer should be considered during analysis.
• Fully-qualified type name (wildcard): the fully-qualified name of the type where the method is declared. Use '*' if you want to describe a function declared in any type , or a global function declared outside of any type.
• Method name (wildcard): the name of the closing method. '*' can be used to denote any num-ber of any symbols.
• + definitions in subclasses: a check box that indicates whether the definitions (of methods with the given name) in subclasses should be considered closers as well. Note that this applies to both instance and static methods.
• "this" object is a resource: a check box that indicates that a resource in the object on which the method is called is closed.
• Resource parameters: specifies that a resource in one or more of its parameters is closed. In this case, either specify a 1-based number of the parameter that is closed by the method, or use '*' to denote that all of the parameters are allocated.