cmnbroad commented 3 years ago

Bundle is another component of the CZI work, and provides a way to group a set of companion resources (such as a reads/index tuple, or a reference/index/dictionary tuple) into a single object. Each resource in a bundle is backed by either a URI-based IOPath; an InputStream; a SeekableStream; or an OutputStream, and has an associated content type string. Each bundle has a single "primary" content type (i.e., "READS", or "VARIANTS", etc.). Bundles that consist of IOPath-backed resources can be serialized to and deserialized from JSON:

{
  "schemaName":"htsbundle",
  "schemaVersion":"0.1.0",
  "primary":"READS"
  "READS":{"path":"myreads.bam","subtype":"BAM"},
  "READS_INDEX":{"path":"myreads.bai","subtype":"BAI"},
}

Resources can be iterated via a Bundle iterator, or accessed directly by content type. This PR also includes a ReadsBundle specialization of Bundle class that provides a convenience layer over a raw bundle; others will follow.

This PR also includes a Beta package annotation that can be used to declare a package as containing code that is "beta"-level and subject to change, as well as a new top level beta package which is annotated with the Beta annotation. All new code is in the beta package.

codecov-commenter commented 3 years ago

Codecov Report

Merging #1546 (a9aa5a2) into master (39b18c7) will increase coverage by 0.342%. The diff coverage is 72.115%.

@@               Coverage Diff               @@
##              master     #1546       +/-   ##
===============================================
+ Coverage     69.424%   69.766%   +0.342%     
- Complexity      8940      9273      +333     
===============================================
  Files            604       617       +13     
  Lines          35636     36568      +932     
  Branches        5923      6118      +195     
===============================================
+ Hits           24740     25512      +772     
- Misses          8547      8667      +120     
- Partials        2349      2389       +40

Impacted Files	Coverage Δ	Complexity Δ
.../htsjdk/beta/plugin/bundle/BundleResourceType.java	`0.000% <0.000%> (ø)`	`0.000 <0.000> (?)`
...jdk/beta/plugin/bundle/SeekableStreamResource.java	`0.000% <0.000%> (ø)`	`0.000 <0.000> (?)`
src/main/java/htsjdk/io/IOUtils.java	`56.522% <56.522%> (ø)`	`4.000 <4.000> (?)`
...ain/java/htsjdk/beta/plugin/reads/ReadsBundle.java	`66.667% <66.667%> (ø)`	`13.000 <13.000> (?)`
...htsjdk/beta/plugin/bundle/InputStreamResource.java	`70.588% <70.588%> (ø)`	`7.000 <7.000> (?)`
...tsjdk/beta/plugin/bundle/OutputStreamResource.java	`70.588% <70.588%> (ø)`	`7.000 <7.000> (?)`
...java/htsjdk/beta/plugin/bundle/IOPathResource.java	`71.429% <71.429%> (ø)`	`9.000 <9.000> (?)`
.../java/htsjdk/beta/plugin/bundle/BundleBuilder.java	`72.222% <72.222%> (ø)`	`4.000 <4.000> (?)`
...rc/main/java/htsjdk/beta/plugin/bundle/Bundle.java	`80.000% <80.000%> (ø)`	`10.000 <10.000> (?)`
.../htsjdk/beta/plugin/bundle/BundleResourceBase.java	`80.645% <80.645%> (ø)`	`14.000 <14.000> (?)`
... and 22 more

cmnbroad commented 3 years ago

@lbergelson Can you merge this - it won't allow me to do it. thx.

lbergelson commented 3 years ago

@cmnbroad 👍

samtools / htsjdk

Beta implementation of Bundles. #1546

Codecov Report