What "return this" means in Java

[Ramakrishna Udupa]

Hi All,

In crawljax open-source code, I seen this method,

 public Options addOption(String opt, String longOpt, boolean hasArg, String description)
    {
        addOption(new Option(opt, longOpt, hasArg, description));
        return this;
    }

I got, it should return "Options". But, "return this" ? I dint get the meaning of this. Because in the above code, they called method addOption(Params...); they are not catching anything from that method then how can they return "return this" ? Please explain me what "return this" means.

Thanks All:
Ramakrishna K.C

[I Wayan Saryada]

"return this" means return the current object instance. In your example it will return the Options object as shown by the addOption() method. For more information on the this keyword you can read the Java language specification.

[Ramakrishna Udupa]

Thanks for the reply,

It'll return the instance of

addOption(new Option(opt, longOpt, hasArg, description));  

. This is nothing but,

public Options addOption(String opt, String longOpt, boolean hasArg, String description)  
    {  
          Option opt = new Option(opt, longOpt, hasArg, description);
          addOption(opt);
          return this OR return opt;
     }

I'm I correct?

[I Wayan Saryada]

The addOption() method from your first example must be part of a class right? For example this class might be look like as simple as this:

public class Options {

    public Options addOption(String opt, String longOpt, boolean hasArg, String description)  
    {  
        addOption(new Option(opt, longOpt, hasArg, description));  
        return this;  
    } 
}

So, the return this simply means return me the current object instance, which is the instance of the class Options. The keyword this is a reference to the current object.

[Ramakrishna Udupa]

The addOption() method from your first example must be part of a class right?

Obviously yes. But, they called addOption() method and catching nothing. I mean,

private Options getOptions() {
		Options options = new Options();
		options.addOption("h", HELP, false, "print this message");
		options.addOption(VERSION, false, "print the version information and exit");

		options.addOption("b", BROWSER, true,
		        "browser type: " + availableBrowsers() + ". Default is Firefox");

		options.addOption(BROWSER_REMOTE_URL, true,
		        "The remote url if you have configured a remote browser");

		options.addOption("d", DEPTH, true, "crawl depth level. Default is 2");

		options.addOption("s", MAXSTATES, true,
		        "max number of states to crawl. Default is 0 (unlimited)");

		options.addOption("p", PARALLEL, true,
		        "Number of browsers to use for crawling. Default is 1");
		options.addOption("o", OVERRIDE, false, "Override the output directory if non-empty");

		options.addOption("a", CRAWL_HIDDEN_ANCHORS, false,
		        "Crawl anchors even if they are not visible in the browser.");

		options.addOption("t", TIME_OUT, true,
		        "Specify the maximum crawl time in minutes");

		options.addOption(CLICK, true,
		        "a comma separated list of HTML tags that should be clicked. Default is A and BUTTON");

		options.addOption(WAIT_AFTER_EVENT, true,
		        "the time to wait after an event has been fired in milliseconds. Default is "
		                + CrawlRules.DEFAULT_WAIT_AFTER_EVENT);

		options.addOption(WAIT_AFTER_RELOAD, true,
		        "the time to wait after an URL has been loaded in milliseconds. Default is "
		                + CrawlRules.DEFAULT_WAIT_AFTER_RELOAD);

		options.addOption("v", VERBOSE, false, "Be extra verbose");
		options.addOption(LOG_FILE, true, "Log to this file instead of the console");

		return options;
	}

see the above code. The above code from another class. Creating instance of Options and then calling options.addOption(Params....); they called and that method is returning something like "return this". But, they are not capturing "this" instance. Then, why they are returning "this"?

[Martin Vashko]

Returning this allows several calls on the same object to be "chained". Most often I see this used with a StringBuilder:

    @Override
    public String toString()
    {
        return new StringBuilder()
                .append("First name: ")
                .append(getFirstName())
                .append(", last name: ")
                .append(getLastName())
                .toString();
    }

This is functionally identical to the following code:

    @Override
    public String toString()
    {
        StringBuilder sbr = new StringBuilder();
        sbr.append("First name: ");
        sbr.append(getFirstName());
        sbr.append(", last name: ");
        sbr.append(getLastName());
        return sbr.toString();
    }

but requires less typing and, at least for some people, is more readable (this is obviously subjective).

Note that the append() methods in the second example returns this as well, but the caller just doesn't use it. You aren't required to "use" the value returned by a method in Java, but returning "this" allows to chain the methods as outlined in the first example.

Returning this is also used by so called Fluent interfaces. However, the concept of fluent interfaces is broader than just returning this - fluent interfaces always return the instance that is best suited for the particular context of the operation that was performed. (Uh, I hope the Wikipedia article makes better job of explaining it than I did here.)

[saurabh agr]

Ramakrishna Udupa wrote:

The addOption() method from your first example must be part of a class right?

Obviously yes. But, they called addOption() method and catching nothing. I mean,

private Options getOptions() {
		Options options = new Options();
		options.addOption("h", HELP, false, "print this message");
		options.addOption(VERSION, false, "print the version information and exit");

		options.addOption("b", BROWSER, true,
		        "browser type: " + availableBrowsers() + ". Default is Firefox");

		options.addOption(BROWSER_REMOTE_URL, true,
		        "The remote url if you have configured a remote browser");

		options.addOption("d", DEPTH, true, "crawl depth level. Default is 2");

		options.addOption("s", MAXSTATES, true,
		        "max number of states to crawl. Default is 0 (unlimited)");

		options.addOption("p", PARALLEL, true,
		        "Number of browsers to use for crawling. Default is 1");
		options.addOption("o", OVERRIDE, false, "Override the output directory if non-empty");

		options.addOption("a", CRAWL_HIDDEN_ANCHORS, false,
		        "Crawl anchors even if they are not visible in the browser.");

		options.addOption("t", TIME_OUT, true,
		        "Specify the maximum crawl time in minutes");

		options.addOption(CLICK, true,
		        "a comma separated list of HTML tags that should be clicked. Default is A and BUTTON");

		options.addOption(WAIT_AFTER_EVENT, true,
		        "the time to wait after an event has been fired in milliseconds. Default is "
		                + CrawlRules.DEFAULT_WAIT_AFTER_EVENT);

		options.addOption(WAIT_AFTER_RELOAD, true,
		        "the time to wait after an URL has been loaded in milliseconds. Default is "
		                + CrawlRules.DEFAULT_WAIT_AFTER_RELOAD);

		options.addOption("v", VERBOSE, false, "Be extra verbose");
		options.addOption(LOG_FILE, true, "Log to this file instead of the console");

		return options;
	}

see the above code. The above code from another class. Creating instance of Options and then calling options.addOption(Params....); they called and that method is returning something like "return this". But, they are not capturing "this" instance. Then, why they are returning "this"?

Hi,

As per your statement addOption() method "return this". It means this method is returning the instance of the object by which this method is called so that you can call anathor methods on the same object in a chain like :

options.addOption(...).addOption(...).addOption(...) and so on

I hope it clears now.

Regards,
Saurabh Agrawal