Page History

...

An

...

exceptional

...

condition

...

can

...

circumvent

...

the

...

release

...

of

...

a

...

lock,

...

leading

...

to

...

deadlock.

...

According

...

to

...

the

...

Java

...

API

...

[API 2014]:

A ReentrantLock is owned by the thread last successfully locking, but not yet unlocking it. A thread invoking lock will return, successfully acquiring the lock, when the lock is not owned by another thread.

Consequently, an unreleased lock in any thread will prevent other threads from acquiring the same lock. Programs must release all actively held locks on exceptional conditions. Intrinsic locks of class objects used for method and block synchronization are automatically released on exceptional conditions (such as abnormal thread termination).

This guideline is an instance of FIO04-J. Release resources when they are no longer needed. However, most Java lock objects are not closeable, so they cannot be automatically released using Java 7's try-with-resources feature.

Noncompliant Code Example (Checked Exception)

This noncompliant code example protects a resource, an open file, by using a ReentrantLock. However, the method fails to release the lock when an exception occurs while performing operations on the open file. When an exception is thrown, control transfers to the catch block and the call to unlock() never executes.

 06|AA. Java References#API 06]\]:

{quote}
A {{ReentrantLock}} is owned by the thread last successfully locking, but not yet unlocking it. A thread invoking {{lock}} will return, successfully acquiring the lock, when the lock is not owned by another thread.
{quote}

Consequently, an unreleased lock in any thread will stop other threads from acquiring the same lock.   Intrinsic locks of class objects used for method and block synchronization are automatically released on exceptional conditions (such as abnormal thread termination).

h2. Noncompliant Code Example (Checked Exception)

This noncompliant code example protects a resource using a {{ReentrantLock}} but fails to release the lock if an exception occurs while performing operations on the open file. If an exception is thrown, control transfers to the {{catch}} block and the call to {{unlock()}} is not executed.

{code:bgColor=#FFcccc}
public final class Client {
  private final Lock lock = new ReentrantLock();

  public void doSomething(File file) {
    finalInputStream Lockin lock = new ReentrantLock()null;
    try {
       lock.lock(in = new FileInputStream(file);
      InputStream in = new FileInputStream(filelock.lock();

      // Perform operations on the open file

      lock.unlock();
    } catch (FileNotFoundException fnfx) {
      // Handle the exception
    } finally {
      if (in != null) }
}
{code}

Note that the lock is not released, even when the {{doSomething()}} method returns. 

This noncompliant code example does not close the input stream and consequently, also violates [FIO06-J. Ensure all resources are properly closed when they are no longer needed].


h2. Compliant Solution ({{finally}} block)

This compliant solution encapsulates operations that may throw an exception in a {{try}} block immediately after acquiring the lock.  The lock is acquired just before the try block, which guarantees that it is held when the finally block executes. The lock is released in the corresponding {{finally}} block, which ensures the lock is released regardless of whether or not an exception occurs.

{code:bgColor=#ccccff}
public final class Client {
  public void doSomething(File file) {
    {
        try {
          in.close();
        } catch (IOException x) {
          // Handle exception
        }  
      }
    }
  }
}

Noncompliant Code Example (finally Block)

This noncompliant code example attempts to rectify the problem of the lock not being released by invoking Lock.unlock() in the finally block. This code ensures that the lock is released regardless of whether or not an exception occurs. However, it does not acquire the lock until after trying to open the file. If the file cannot be opened, the lock may be unlocked without ever being locked in the first place.

public final class Client {
  private final Lock lock = new ReentrantLock();

  public void doSomething(File file) {
    InputStream in = null;
    try {
      in = new FileInputStream(file);
      lock.lock();
      // Perform operations on the open file
    } catch (FileNotFoundException fnf) {
      // Forward to handler
    } finally {
      lock.unlock();
      if (in != null) {
        try {
          in.close();
        } catch (IOException e) {
          // Forward to handler
        }
      }
    }
  }
}

Compliant Solution (finally Block)

This compliant solution encapsulates operations that could throw an exception in a try block immediately after acquiring the lock (which cannot throw). The lock is acquired just before the try block, which guarantees that it is held when the finally block executes.

public final class Client {
  private final Lock lock = new ReentrantLock();

  public void doSomething(File file) {
    InputStream in = null;
    lock.lock();
    try {
      in = new FileInputStream(file);
      // Perform operations on the open file
    } catch (FileNotFoundException fnf) {
      // Forward to handler
    } finally {
      lock.unlock();

      if (in != null) {
        try {
	          in.close();
	        } catch (IOException e) {
	          // Forward to handler
        }
      }
    }
  }
}
{code}

h2. Compliant Solution 

Compliant Solution (Execute-

...

Around Idiom)

...

The

...

execute-around

...

idiom

...

provides

...

a

...

generic

...

mechanism to

...

perform

...

resource

...

allocation

...

and

...

cleanup operations

...

so

...

that

...

the

...

client

...

can

...

focus

...

on

...

specifying

...

only

...

the

...

required

...

functionality.

...

This

...

idiom

...

reduces

...

clutter

...

in

...

client

...

code

...

and

...

provides

...

a

...

secure

...

mechanism

...

for

...

resource

...

management.

...

In

...

this

...

compliant

...

solution,

...

the

...

client's

...

doSomething()

...

method

...

provides

...

only

...

the

...

required

...

functionality

...

by

...

implementing

...

the

...

doSomethingWithFile()

...

method

...

of

...

the

...

LockAction

...

interface

...

without

...

having

...

to

...

manage

...

the acquisition

...

and

...

release

...

of

...

locks

...

or

...

the open

...

and

...

close

...

operations

...

of

...

files.

...

The

...

ReentrantLockAction

...

class

...

encapsulates

...

all

...

resource

...

management

...

actions.

{:=

Code Block
bgColor	#ccccff
} public interface LockAction { void doSomethingWithFile(InputStream in); } public final class ReentrantLockAction { private static final Lock lock = new ReentrantLock(); public static void doSomething(File file, LockAction action) { Lock lock = new ReentrantLock(); InputStream in = null; lock.lock(); try { in = new FileInputStream(file); action.doSomethingWithFile(in); } catch (FileNotFoundException fnf) { // Forward to handler } finally { lock.unlock(); if (in != null) { try { in.close(); } catch (IOException e) { // Forward to handler } } } } } public final class Client { public void doSomething(File file) { ReentrantLockAction.doSomething(file, new LockAction() { public void doSomethingWithFile(InputStream in) { // Perform operations on the open file } }); } } {code} h2. Noncompliant Code Example (unchecked exception) This noncompliant code example uses a {{ReentrantLock}} to protect a {{

Noncompliant Code Example (Unchecked Exception)

This noncompliant code example uses a ReentrantLock to protect a java.util.Date instance—recall that java.util.Date

...

is

...

thread-

...

unsafe by design.

 design.  

{mc} Do not declare lock as private as it need package-wide accessibility for illustrative purposes {mc}

{code:bgColor=#FFcccc}
final class DateHandler {

  private final Date date = new Date();

  private final Lock lock = new ReentrantLock();

  public void doSomethingSafely(String str) {
    try {
      doSomething(str);
    } catch(Throwable t) {
      // Forwardstr tocould handler
    }
  }

be null
  public void doSomething(String str) {
    lock.lock();
    String dateString = date.toString();
    if (str.equals(dateString)) {
      // ...
    }
    // ...

    lock.unlock();
  }
}
{code}

Because the {{

A runtime exception can occur because the doSomething()

...

method

...

fails

...

to

...

check whether str is a null reference, preventing the lock from being released.

Compliant Solution (finally Block)

This compliant solution encapsulates all operations that can throw an exception in a try block and releases the lock in the associated finally block. Consequently, the lock is released even in the event of a runtime exception.

 if {{str}} is {{null}}, a runtime exception can occur, preventing the lock from being released.

Note that the {{doSomethingSafely()}} method must catch {{Throwable}} to be compliant with [EXC06-J. Do not allow exceptions to transmit sensitive information].

h2. Compliant Solution ({{finally}} block)

This compliant solution encapsulates operations that can throw an exception in a try block and release the lock in the associated {{finally}} block.  

{code:bgColor=#ccccff}
final class DateHandler {

  private final Date date = new Date();

  private final Lock lock = new ReentrantLock();

  public void doSomethingSafely(String str) {
    try {
      doSomething(str);
    } catch(Throwable t) {
      // Forwardstr tocould handler
    }
  }
be null
  public void doSomething(String str) {
    lock.lock();
    try {
      String dateString = date.toString();
      if (str != null && str.equals(dateString)) {
        // ...
      }
      // ...

    } finally {
      lock.unlock();
    }
  }
}
{code}

Consequently, the lock is released even in the event of a runtime exception. The {{

The doSomething()

...

method

...

also avoids throwing a NullPointerException by ensuring that the string does not contain a null reference.

Risk Assessment

Failure to release locks on exceptional conditions could lead to thread starvation and deadlock.

Automated Detection

Some static analysis tools are capable of detecting violations of this rule.

Related Vulnerabilities

The GERONIMO-2234 issue report describes a vulnerability in the Geronimo application server. If the user single-clicks the keystore portlet, the user will lock the default keystore without warning. This causes a crash and stack trace to be produced. Furthermore, the server cannot be restarted because the lock is never cleared.

Related Guidelines

Bibliography

...

Image Added Image Added Image Added