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?

• sshannin: It's just a bunch of methods chained together.

Answer 1

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.

• Peter Lawrey: +1 It's much the same as new StringBuilder().append(a).append("=").append(b).toString();
• fge: The main advantage of a builder pattern is that you can .build() immutable instances.
• Sergey Kalinichenko: 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: @dasblinkenlight - true, its not a requirement, but most builders use fluent APIs.
• Kingamajick: 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.

Answer 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.

Answer 3

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.

• johnl1943: 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.
• Parker: 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()