Move ListResult and BaseListResult to core module

[mziccard]

ListResult and BaseListResult might be useful also for other modules so it might make sense to move them from com.google.gcloud.storage to com.google.gcloud.core. What do you think?

[ajkannan]

It'd be useful for ResourceManager; one of the methods returns a paginated list using page tokens.

[aozarov]

Yes, I think we have 2 types of list results.

One that works based on pages (has a page-level cursor) like the one for Storage and one that has
a row level cursor like for Datastore.

I think moving these classes to core is a fine idea though maybe when doing so, we need to fine a better name that would match other page-level list results?

[mziccard]

@aozarov What problem do you see with naming? Now we have:

public interface ListResult<T> extends Iterable<T> {
  String nextPageCursor();
  ListResult<T> nextPage();
}

Which should fit almost all paginated searches.

[aozarov]

I think we may one also at some point to support a common list result for a row-level cursor. If so,
how should we call it?

[ajkannan]

This is somewhat related (but not related to Arie's question): I think Tuple could be moved into core's spi layer as well. Some services (i.e. storage and resource manager) that have pagination also need a Tuple to return the token and the iterable/list.

[mziccard]

So you would like to use the same interface for both page-based and row-based cursor.
What about something simple as:

public interface ListResult<T> extends Iterable<T> {
  String nextCursor();
  ListResult<T> nextResults();
}

as well as

  public interface NextPageFetcher<T extends Serializable> extends Serializable {
    ListResult<T> nextResults();
  }

I lack of imagination:)

@ajkannan The only problem I see with moving Tuple to core is that we don't actually want to expose it to the users but only use internally.

[aozarov]

Honestly, I always wanted Java to have a Tuple/Pair type but I think I am in the minority in this case.

Considering this thread and this I don't think we should go against it (and avoid having it as part of the more visible "api" part).

[aozarov]

Another, more explicit, option (just thinking out load) could be:

public interface Page<T> implements Iterable<T> {
  String nextPageCursor();
  Page<T> nextPage();
}

and use Page as the type of the Iterable returned by a page-based-cursor list function.

[aozarov]

Also, hijacking this thread, what do you think about a common ServiceException with code and retryable?

[ajkannan]

I'm in favor of a common ServiceException with code and retryable.

[aozarov]

@mziccard, @ajkannan just made me realize that I didn't fully response to your suggestion of keep
using the ListResult name but removing the "page" part from nextCursor and nextResults.

I think there are 2 issues with this suggestion.

1. API is less clear about the cursor (we can javadoc it but I don't think this is as clear).
2. In the case of a row-level cursor, there is no such thing as nextResult as the original iterator
   can transparently iterate over the complete result set.

[mziccard]

I think there might be some benefits from having separate exceptions (e.g. catching them separately)

[aozarov]

I think there might be some benefits from having separate exceptions (e.g. catching them separately)

Oh, no doubt. My question was (and sorry for not making myself clear) if we should have a base exception class (but still make each service has its own top level exception extending that base class)?

[mziccard]

Uh I got it wrong. Then I agree, I'll take care of this.

[ajkannan]

Hey @mziccard, how's your workload? I can make the common BaseServiceException (with code and retryable) if you're not working on it.

[mziccard]

I can work on it tomorrow but if you have time today feel free to take it :) Just let me know, thanks!

[ajkannan]

I can take it, I have some time today.

[aozarov]

Fixed by #318 and #324