List repositories for a GHAppInstallation

[tginiotis-at-work]

Description

Implements the API method for listing repositories associated to an app installation. Docs here.
Resolves #948.

Before submitting a PR:

We love getting PRs, but we hate asking people for the same basic changes every time.

• Push your changes to a branch other than master. Create your PR from that branch.
• Add JavaDocs and other comments
• Write tests that run and pass in CI. See CONTRIBUTING.md for details on how to capture snapshot data.
• Run mvn clean compile locally. This may reformat your code, commit those changes.
• Run mvn -D enable-ci clean install site locally. If this command doesn't succeed, your change will not pass CI.

When creating a PR:

• Fill in the "Description" above.
• Enable "Allow edits from maintainers".

[tginiotis-at-work]

I have recreated this PR to make it count for Hacktoberfest. Hope no one minds!

[tginiotis-at-work]

The issue with this API method is that its response structure is unlike other methods. Specifically, it returns the pull request list in a repositories field inside the body of the response JSON instead of just putting the list into the root of the response JSON.

I.e. it returns like so:

{
  "total_count": 1,
  "repositories": [
    {...}, 
    {...}, 
    {...}
  ]
}

while the usual way the API structures the responses is e.g. (listing commits on a repository):

[
  {...}, 
  {...}, 
  {...}
]

As far as I looked - this library did not support parsing responses such as the former.

I added handling for parsing responses containing item lists in nested fields. And the API method in question itself.

This is an initial draft, to see if this is the correct approach to take. I have it working in an internal application, but I am aware that there might be different requirements to make the changes public. Can someone check if the approach here is alright?

If the approach taken is suitable - I would continue with cleaning it up, adding tests & doing the other tasks necessary for final reviews.

[bitwiseman]

The nestedFieldKey is an interesting way to do this, but requires significant changes to across multiple classes and layers.
The docs you pointed to return records that look like search results (it has a total_count field. Rather than wiring through this whole new functionality, I think you should look at using the PagedSearchIterable. You will create a class, something like private class GHAppInstallationRepositoryResult extends SearchResult` - similar to

github-api/src/main/java/org/kohsuke/github/GHContentSearchBuilder.java

Lines 121 to 130 in 3a11b7c

	private static class ContentSearchResult extends SearchResult<GHContent> {
	private GHContent[] items;
	@Override
	GHContent[] getItems(GitHub root) {
	for (GHContent item : items)
	item.wrap(root);
	return items;
	}
	}

.

Make sense?

There is no way you would have known to look for this - it is something I wasn't aware of for a quite sometime after becoming a maintainer here. Sorry.

Other than that, this looks like a great change. Thanks for contributing!

[tginiotis-at-work]

Right, I have not thought about looking into other API methods that could have a similar return format and so already implemented ways of parsing such responses. I thought this is a GitHub response anomaly.
This approach does make more sense than wiring that variable through all those layers!

I have reimplemented the API method using PagedSearchIterable.

[bitwiseman]

Excellent!

[Chumper]

Is there a reason the methods are marked as @deprecated?

[tginiotis-at-work]

I think the reason @Deprecated is used is to make IDEs and compiler outputs indicate that you are using preview API methods (MACHINE_MAN in this case), because just the @Preview annotation does not do that.

[Chumper]

Yeah, correct. I was too tired to notice that. Sorry for asking :)

[bitwiseman]

@Chumper @tginiotis-at-work
This is common question. Any suggestions on who to document this or clearly represent the "preview" state of some parts of the API would be appreciated.