chore: support complex resource identifiers

[miraleung]

Add support for the non-slash resource name separators. That is, "-", "~", "_", ".". These changes are needed for gapic-generator.

Relevant issue here.

[codecov]

Codecov Report

Merging #125 into master will increase coverage by 3.02%.
The diff coverage is 88.33%.

@@             Coverage Diff              @@
##             master     #125      +/-   ##
============================================
+ Coverage     60.93%   63.96%   +3.02%     
- Complexity      148      163      +15     
============================================
  Files            14       14              
  Lines           622      702      +80     
  Branches         92      112      +20     
============================================
+ Hits            379      449      +70     
- Misses          217      219       +2     
- Partials         26       34       +8     

Impacted Files	Coverage Δ	Complexity Δ
...java/com/google/api/pathtemplate/PathTemplate.java	69.06% <88.33%> (+4.21%)	106.00 <7.00> (+15.00)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b6e9dad...12b22f3. Read the comment docs.

[vam-google]

There is a lot of complex logic, which is hard to comprehend and "compile" in head =) (especially the parseComplexResourceId() method), so given the test cases, I trust that it works correctly.

Basically looks good, with a few questions:

1. It is probably a silly question, but I'm wondering if in the implementation we replaced the complex delimiters with /, remembering the mapping between the original delimiters and "fake" slashes, then propagated that to the existing PathTemplate logic (which knows only slashes), and then used the saved mapping, if needed, to reverse that in PathTemplate.match() implementation. Does it have a chance to work? If yes, it can result in much simpler implementation.
   Or, in other words: are the "new" delimiters just another syntax for delimiters or is there a fundamental difference between /{a}/{b} and /{a}~{b} formats (does ~ put {a} and {b} in some sort of different relation compared to / separator)?

2. This is slightly related to the question 1 (because it may make 1 more feasible). Should we forbade usage of a delimiter character in the body of the resoruce name? (see a comment for one of the test cases for more details).

[vam-google]

Look like it uses greedy approach and for the last ambiguous segment ({zone_c}-{zone_d}), when provided with us-west2-b-europe-west2-b input it treats the stuff before the first hyphen (us) as zone_c and everything else as zone_d.

This ambiguity looks like a real problem. Even thought the implementation behaves predictably and reasonably, looks like us-west2-b-europe-west2-b should be split as zone_c=us-west2-b and zone_d=europe-west2-b.

Should we forbade a character in the body if the same character uses as a splitter?

[miraleung]

This is a spec question, let's take this discussion over there. @chrisdunelm FYI.

[chrisdunelm]

Yes, this is a known potential problem.
The spec currently states that it is the responsibility of the API producer to ensure that any split character(s) are not present in the variables. As things are now, I consider this sufficient.
An alternative would be to verify that no parsed variable values contain any of the [used] split character(s); but I think this would be too much,

[miraleung]

Responding to @vam-google's comment:

1. Mixing up the existing "/" and complex resource ID delimiter parsing logic risks introducing error edge cases. For example, if someone passes in projects/{project}-zones/{zone_a}/{zone_b} where they meant projects/{project}/zones/{zone_a}-{zone_b}, the former could result in a valid parsing under the mixed implementation. Not only would we require additional logic to separate out literals and IDs (which could become even more complex), we'd risk having literals being parsed in as IDs, and vice-versa.
   One advantage of the current set-up is that it's easy to isolate and toggle complex resource ID parsing on/off, or add in a whitelist for the relevant clients if that becomes necessary.
2. PTAL at the comment here.

[vam-google]

The travis jobs are failing on formatting validation. Please run ./gradlew googleJavaFormat to automatically format the files and push updated files.

LGTM, to not block this work, assuming build jobs pass and the spec "ambiguity" (the hyphen thing) is resolved/clarified in the spec.

[chrisdunelm]

LGTM once CI passes.