Add "zeroEntryTimestamps()" option

[blendmaster]

See javadoc on the method for details on why and how. This
is basically the half-assed deterministic build from #229,
which is to say still extremely helpful when dealing with rsync.

Also update docs.gradle since doclet resolution freezes the build until the http request times out.

[johnrengelman]

@blendmaster thanks for the submissions. I'm still finding time in my schedule to invest into some updates for shadow. As for this, I'm considering making it a higher level feature that allows a user to register arbitrary actions against each ZipEntry is is produced instead of a boolean flag.
That would make it more extensible to add new capabilities.

So I'm envisioning something like adding the following method to the ShadowJar class:

interface ZipEntryAction extends Action<ZipEntry> {}

ShadowJar zipEntries(ZipEntryAction action) {
  this.zipEntryActions << action
}

these would be passed down to the ShadowCopy Action and then applied to each ZipEntry.

If you want to take a crack at implementing it that way, that would be cool, otherwise when I find time, i'll probably incorporate your changes that way.

[blendmaster]

It seems reasonable to offer more general hooks into the final shadow zip file creation. However, I'm having trouble thinking of what anybody would do with just the ZipEntry besides zero the timestamps. Did you have anything particular in mind?

If you could somehow affect both the ZipEntry and the actual contents of the entry, it might be more useful. Something like (ZipEntry e, OutputStream original) -> OutputStream transformed, where you can either wrap the original ZipOutputStream in a transform of some sort, or return it verbatim. Contrived example:

zipEntryActions << { entry, orig ->
  if (entry.name ~= "*.java") {
    // prefix text with copyright
    def written = false
    return new FilterOutputStream(orig) {
      def write(bytes) {
        if (!written) {
          orig.write("my copyright notice\n")
          written = true
        }
        orig.write(bytes)
    }
  } else {
    return orig
  }
}

In any case, I can reimplement this PR on ZipEntryAction. I'm inclined to keep the zeroEntryTimestamps() option on ShadowJar as a useful shortcut, akin to mergeServiceFiles().

[johnrengelman]

yeah, it might end up being something like that or even extending the Transfomer interface to also take the ZipEntry as an arg...not sure. But i think implementing it this way will provide greater flexibility for moving toward something like that.

the shortcut method is fine.

Thanks.

[blendmaster]

Looking at this again, my implementation doesn't quite work with transformed (through Transformer#modifyOutputStream(ZipOutputStream)) files. Those use ZipOutputStream.putNextEntry themselves, avoiding the hook in ShadowCopyAction.

One implementation path I originally went down was to proxy the entire ZipOutputStream with something like javassist, allowing interception of all putNextEntry calls. However, I didn't want to add an extra dependency, so I went with the manual putNextEntry interception that seemed to (but doesn't) cover all callsites.

Given #247 and this PR, it does seem like a general way for munging the ZipOutputStream is appropriate. Let me know if you have any additional thoughts. I'll think of something to implement in the meantime.

[johnrengelman]

Closing this in favor of #333