rspec/rules/S1217/java/rule.adoc

This rule raises an issue when `Thread.run()` is called instead of `Thread.start()`.

== Why is this an issue?

The likely intention of a user calling `Thread.run()` is to start the execution of code within a new thread.
This, however, is not what happens when this method is called.

The purpose of `Thread.run()` is to provide a method that users can overwrite to specify the code to be executed.
The actual thread is then started by calling `Thread.start()`.
When `Thread.run()` is called directly, it will be executed as a regular method within the current thread.

== How to fix it

If you intend to execute the contents of the `Thread.run()` method within a new thread,
call `Thread.start()` instead.

If your intention is only to have a container for a method but execute this method within the current thread,
do not use `Thread` but `Runnable` or another functional interface.

=== Code examples

==== Noncompliant code example

[source,java,diff-id=1,diff-type=noncompliant]
----
Thread myThread = new Thread(runnable);
myThread.run(); // Noncompliant, does not start a thread
----

==== Compliant solution

[source,java,diff-id=1,diff-type=compliant]
----
Thread myThread = new Thread(runnable);
myThread.start(); // Compliant
----

==== Noncompliant code example

[source,java,diff-id=2,diff-type=noncompliant]
----
class ComputePrimesThread extends Thread {
    @Override
    public void run() {
        // ...
    }
}
new ComputePrimesThread().run(); // Noncompliant, does not start a thread
----

==== Compliant solution

[source,java,diff-id=2,diff-type=compliant]
----
class ComputePrimesThread extends Thread {
    @Override
    public void run() {
        // ...
    }
}
new ComputePrimesThread().start(); // Compliant
----

==== Noncompliant code example

[source,java,diff-id=3,diff-type=noncompliant]
----
class Button {

    private Thread onClick;

    Button(Thread onClick) {
        this.onClick = onClick;
    }

    private void clicked() {
        if (onClick != null) onClick.run(); // Noncompliant, use functional interface
    }
}

new Button(new Thread() {
    @Override public void run() {
        System.out.println("clicked!");
    }
});
----

==== Compliant solution

[source,java,diff-id=3,diff-type=compliant]
----
class Button {

    private Runnable onClick;

    Button(Runnable onClick) {
        this.onClick = onClick;
    }

    private void clicked() {
        if (onClick != null) onClick.run(); // compliant
    }
}

new Button(() -> System.out.println("clicked!"));
----

== Resources

=== Documentation

* https://docs.oracle.com/javase/8/docs/api/java/lang/Thread.html#start--[Java™ Platform, Standard Edition 8 API Specification - Thread.start()]

=== Articles & blog posts

* https://www.javatpoint.com/what-if-we-call-java-run-method-directly[JavaTPoint - What if we call Java run() method directly instead start() method?]

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Call the method Thread.start() to execute the content of the run() method in a dedicated thread.


'''
== Comments And Links
(visible only on this page)

=== on 20 Aug 2013, 15:40:32 Freddy Mallet wrote:
Is implemented by \http://jira.codehaus.org/browse/SONARJAVA-308

endif::env-github,rspecator-view[]