As part of the latest Java client library, the SelectorBuilder utility class facilitates the creation of the generic selectors that are needed to query the AdWords API. Because of the nature of the generic selectors, some boilerplate code is needed in order to instantiate the selector objects properly. Also the way that a selector is configured depends on the implementation that is being used.

With the new SelectorBuilder, you have less boilerplate code and can still chain method calls and edit selectors without needing to know all the details of the generic Selector class. Let’s take a look at some examples comparing the current way of creating selectors, and the way it is with the utility class.

NOTE: Using the SelectorBuilder class to create selectors does not restrict the user from editing the selector after it has been built.

Some examples

The SelectorBuilder class is just a builder-like object that can be chained in order to simplify the code needed to create the predicates and fields used with the API. Let’s now take a look at how the selector is created in the GetCampaigns example (available on GitHub):

    SelectorBuilder builder = new SelectorBuilder()
       .fields("Id", "Name")
       .orderAscBy("Name")
       .offset(0)
       .limit(20)
       .build();

You still need to pass all the field names as strings, but all the boilerplate code involved in setting everything on the selector is handled by the SelectorBuilder. More than that, the methods have the same signature for Axis and JAX-WS.

NOTE: To add a new field to the selection, you must call the method fields passing all fields that were used before, plus the one that you want to add:

    builder.fields("Id",
       "Name",
       // new field to the selection
       "status");

This will return the same Selector as previously, but with the field status added to the selection. (IMPORTANT: The previously created Selector DOES NOT change when making additional method calls to the builder).

All configurations available in the selector can be set using the SelectorBuilder utility. Looking at the GetKeywords example, there is sample code on how to add predicates to the selector:

    SelectorBuilder builder = new SelectorBuilder()
       .fields("Id", "AdGroupId", "MatchType",
           "KeywordText")
       .orderAscBy("AdGroupId")
       .offset(0)
       .limit(20)
       .in("AdGroupId", adGroupId.toString())
       .equals("CriteriaType", "KEYWORD")
       .build();

More examples are available in the client library repository in GitHub.

Some additional considerations

It is important to remember that the builder returns a Selector, so all its accompanying features are still present, even if you use the builder to create it.

SelectorBuilder makes available all possible predicate operators as utility methods:

    builder
       .equals(“”, value)
       .notEquals(“”, value)
       .contains(“”, value)
       .containsIgnoreCase(“”, value)
       .doesNotcontain(“”, value)
       .doesNotContainIgnoreCase(“”, value)
       .in(“”, collection)
       .notIn(“”, collection)
       .greaterThan(“”, value)
       .greaterThanEquals(“”, value)
       .lessThan(“”, value)
       .lessThanEquals(“”, value);

    builder
       .orderAscBy(“”)
       .orderDescBy(“”)
       .offset(offset)
       .limit(amount)
       .forDateRange(start, end);

The start and end dates are Joda-Time dates, so it is easy to add and remove days from them. The builder will parse dates according to the API format.

If you have any questions about the client libraries, you can post them on our forums. Check out our Google+ page for client library and Ads APIs updates.

Gustavo M. P. Moreira, Ads API Team

Source: Google Ads Developer Blog