Java syntax - what does this code mean?

Question

I am starting to learn Android programming with Java, mainly from online Android documentation. I also looked through several books but they don't seem to address this issue: a feature of Java syntax which I have come across several times and which is a mystery to me. Here is just one example from about half-way through the Contacts Provider documentation at

http://developer.android.com/guide/topics/providers/contacts-provider.html

I have removed the comments to unclutter the code snippet:

op = 
ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
.withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)
.withValue(ContactsContract.Data.MIMETYPE,
    ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE)
.withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email)
.withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType);

This is all one statement, I think. What is confusing me is all those "dot operators" that look as though they belong in a Visual Basic "with clause". Where can I find out what all this means?

It's just a bunch of methods chained together.

sshannin
– sshannin

2013-01-14 17:13:13 +00:00
Commented Jan 14, 2013 at 17:13 — sshannin
– sshannin, Commented Jan 14, 2013 at 17:13

radai · Accepted Answer · 2013-01-14 17:20:10Z

6

youre looking at a builder pattern, where the return value of each such with* method is the builder itself (or the object, if its not a builder exactly). theyre handly when you want to chain a lot of setters, or when there are a lot of constructors for the underlying object and you dont want people using it to get confused. or, as fge stated below, when you want the returned object to be immutable (so it cant have setters).

more specifically to your case, the return value of ContentProviderOperation.newInsert() is a ContentProviderOperation.Builder, all of who's methods return itself. usually such a chain of configuration calls will end in a call to build(), which will produce an operation.

edited Jan 14, 2013 at 17:20

answered Jan 14, 2013 at 17:13

radai

24.3k10 gold badges76 silver badges118 bronze badges

Sign up to request clarification or add additional context in comments.

5 Comments

Peter Lawrey Over a year ago

+1 It's much the same as new StringBuilder().append(a).append("=").append(b).toString();

fge Over a year ago

The main advantage of a builder pattern is that you can .build() immutable instances.

Sergey Kalinichenko Over a year ago

Note that the builder pattern does not require fluent interfaces. In particular, the Wikipedia page shows an example of builder that does not support method chaining, because its various setters have void return type.

radai Over a year ago

@dasblinkenlight - true, its not a requirement, but most builders use fluent APIs.

Kingamajick Over a year ago

Although though in this case, this is an instance of the builder pattern, it doesn't answer the question which was originally asked, which is "What is confusing me is all those "dot operators" that look as though they belong in a Visual Basic "with clause". Where can I find out what all this means?" I think dasblinkenlight's answer is more accurate.

Sergey Kalinichenko · Accepted Answer · 2013-01-14 17:14:55Z

2

This is an instance of so called fluent interfaces (link to wikipedia). There is noting special about it: the value returned from the previous call is being used as the target of the subsequent call.

API like this present a useful alternative to methods with lots of optional parameters, because the resulting code is much easier to read and understand. The code is somewhat more verbose, but in this case it is a good thing, because the parameters passed to constructors get better "tagging". This style is also preferable when you have multiple parameters of the same type (say, strings) next to each other, because it lets the readers avoid parameter counting.

answered Jan 14, 2013 at 17:14

Sergey Kalinichenko

729k85 gold badges1.2k silver badges1.6k bronze badges

Comments

Peter Elliott · Accepted Answer · 2013-01-14 17:18:11Z

0

each of those methods returns an ContentProviderOperation.Builder object that has been modified by the method. So you can chain together calls to methods like that and do everything in a more compact way. It's similar to how jQuery works in the javascript world.

It may clear things up a bit to look at the newInsert method on the Android documentation, then look at the documentation for the ContentProviderOperation.Builder class. note that all of the methods on that object also return ContentProviderOperation.Builder objects.

answered Jan 14, 2013 at 17:18

Peter Elliott

3,32218 silver badges30 bronze badges

2 Comments

johnl1943 Over a year ago

Would I then be right in thinking it comes out the same as ... op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI); op = op.withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0); op = op.withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE); op = op.withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email); op = op.withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType); ? Many thanks. I'm reading the references given.

Peter Elliott Over a year ago

not exactly, since as @radai points out, there is also a build method, so you would have to assign the output of newInsert to an intermediate variable like build, then make a bunch of build = build.withValue... calls, then finally call op = build.build()

Collectives™ on Stack Overflow

Java syntax - what does this code mean?

3 Answers 3

5 Comments

Comments

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

5 Comments

Comments

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related