From fe9bd933bb7aea68897b73a2f0dc8c74702f79c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20G=C3=B3mez-S=C3=A1nchez?= Date: Thu, 6 Jul 2017 15:58:23 +0200 Subject: [PATCH] Proposal to evolve to HTSJDK version 3 --- htsjdk3-dev/htsjdk-core/README.md | 7 +++ .../java/htsjdk/samtools/package-info.java | 6 +++ .../src/main/java/htsjdk/tribble/Feature.java | 35 ++++++++++++++ .../java/htsjdk/tribble/package-info.java | 6 +++ .../src/main/java/htsjdk/util/Locatable.java | 48 +++++++++++++++++++ .../main/java/htsjdk/util/package-info.java | 6 +++ .../java/htsjdk/variant/package-info.java | 6 +++ htsjdk3-dev/htsjdk-cram/README.md | 3 ++ .../htsjdk/samtools/cram/package-info.java | 6 +++ htsjdk3-dev/htsjdk-jexl/README.md | 3 ++ htsjdk3-dev/htsjdk-sra/README.md | 3 ++ .../htsjdk/samtools/sra/package-info.java | 6 +++ src/main/java/htsjdk/Htsjdk3.java | 31 ++++++++++++ .../java/htsjdk/samtools/util/Locatable.java | 3 ++ src/main/java/htsjdk/tribble/Feature.java | 2 + 15 files changed, 171 insertions(+) create mode 100644 htsjdk3-dev/htsjdk-core/README.md create mode 100644 htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/samtools/package-info.java create mode 100644 htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/tribble/Feature.java create mode 100644 htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/tribble/package-info.java create mode 100644 htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/util/Locatable.java create mode 100644 htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/util/package-info.java create mode 100644 htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/variant/package-info.java create mode 100644 htsjdk3-dev/htsjdk-cram/README.md create mode 100644 htsjdk3-dev/htsjdk-cram/src/main/java/htsjdk/samtools/cram/package-info.java create mode 100644 htsjdk3-dev/htsjdk-jexl/README.md create mode 100644 htsjdk3-dev/htsjdk-sra/README.md create mode 100644 htsjdk3-dev/htsjdk-sra/src/main/java/htsjdk/samtools/sra/package-info.java create mode 100644 src/main/java/htsjdk/Htsjdk3.java diff --git a/htsjdk3-dev/htsjdk-core/README.md b/htsjdk3-dev/htsjdk-core/README.md new file mode 100644 index 0000000000..33873c744d --- /dev/null +++ b/htsjdk3-dev/htsjdk-core/README.md @@ -0,0 +1,7 @@ +# HTSJDK-CORE + +Contains common code and interface/api definitions. + +Includes SAM/BAM, VCF and tribble support. + +Should not include significant dependencies. \ No newline at end of file diff --git a/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/samtools/package-info.java b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/samtools/package-info.java new file mode 100644 index 0000000000..347e243a1f --- /dev/null +++ b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/samtools/package-info.java @@ -0,0 +1,6 @@ +/** + * Contains SAM support. + * + * @author Daniel Gomez-Sanchez (magicDGS) + */ +package htsjdk.samtools; \ No newline at end of file diff --git a/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/tribble/Feature.java b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/tribble/Feature.java new file mode 100644 index 0000000000..b21ea6d4db --- /dev/null +++ b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/tribble/Feature.java @@ -0,0 +1,35 @@ +/* + * The MIT License (MIT) + * + * Copyright (c) 2017 Daniel Gomez-Sanchez + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ +package htsjdk.tribble; + + +import htsjdk.util.Locatable; + +/** + * Marker interface for Locatables with Tribble support. A Feature represents a record in a tribble-supported file format. + * As {@link Locatable}, represents a locus on a reference sequence and is expected to return 1-based closed-ended intervals. + */ +public interface Feature extends Locatable { + +} diff --git a/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/tribble/package-info.java b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/tribble/package-info.java new file mode 100644 index 0000000000..3799619845 --- /dev/null +++ b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/tribble/package-info.java @@ -0,0 +1,6 @@ +/** + * Support for indexed and query-able genomic file formats. + * + * @author Daniel Gomez-Sanchez (magicDGS) + */ +package htsjdk.tribble; \ No newline at end of file diff --git a/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/util/Locatable.java b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/util/Locatable.java new file mode 100644 index 0000000000..7b69331b0a --- /dev/null +++ b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/util/Locatable.java @@ -0,0 +1,48 @@ +/* + * The MIT License (MIT) + * + * Copyright (c) 2017 Daniel Gomez-Sanchez + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +package htsjdk.util; + +/** + * Any class that has a single logical mapping onto the genome should implement Locatable + * positions should be reported as 1-based and closed at both ends. + */ +public interface Locatable { + + /** + * Gets the contig name for the contig this is mapped to. May return null if there is no unique mapping. + * @return name of the contig this is mapped to, potentially null + */ + String getContig(); + + /** + * @return 1-based start position, undefined if getContig() == null + */ + int getStart(); + + /** + * @return 1-based closed-ended position, undefined if getContig() == null + */ + int getEnd(); +} diff --git a/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/util/package-info.java b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/util/package-info.java new file mode 100644 index 0000000000..255ba5ac0c --- /dev/null +++ b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/util/package-info.java @@ -0,0 +1,6 @@ +/** + * Common utilies. + * + * @author Daniel Gomez-Sanchez (magicDGS) + */ +package htsjdk.util; \ No newline at end of file diff --git a/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/variant/package-info.java b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/variant/package-info.java new file mode 100644 index 0000000000..536ca91ddc --- /dev/null +++ b/htsjdk3-dev/htsjdk-core/src/main/java/htsjdk/variant/package-info.java @@ -0,0 +1,6 @@ +/** + * + * + * @author Daniel Gomez-Sanchez (magicDGS) + */ +package htsjdk.variant; \ No newline at end of file diff --git a/htsjdk3-dev/htsjdk-cram/README.md b/htsjdk3-dev/htsjdk-cram/README.md new file mode 100644 index 0000000000..22f97ba043 --- /dev/null +++ b/htsjdk3-dev/htsjdk-cram/README.md @@ -0,0 +1,3 @@ +# HTSJDK-CRAM + +Includes support for CRAM format. \ No newline at end of file diff --git a/htsjdk3-dev/htsjdk-cram/src/main/java/htsjdk/samtools/cram/package-info.java b/htsjdk3-dev/htsjdk-cram/src/main/java/htsjdk/samtools/cram/package-info.java new file mode 100644 index 0000000000..9195a3346b --- /dev/null +++ b/htsjdk3-dev/htsjdk-cram/src/main/java/htsjdk/samtools/cram/package-info.java @@ -0,0 +1,6 @@ +/** + * Support for CRAM format. + * + * @author Daniel Gomez-Sanchez (magicDGS) + */ +package htsjdk.samtools.cram; \ No newline at end of file diff --git a/htsjdk3-dev/htsjdk-jexl/README.md b/htsjdk3-dev/htsjdk-jexl/README.md new file mode 100644 index 0000000000..237cdd734f --- /dev/null +++ b/htsjdk3-dev/htsjdk-jexl/README.md @@ -0,0 +1,3 @@ +# HTSJDK-JEXL + +Includes support for JEXL expressions in VariantContext. \ No newline at end of file diff --git a/htsjdk3-dev/htsjdk-sra/README.md b/htsjdk3-dev/htsjdk-sra/README.md new file mode 100644 index 0000000000..ea1930eb3b --- /dev/null +++ b/htsjdk3-dev/htsjdk-sra/README.md @@ -0,0 +1,3 @@ +# HTSJDK-SRA + +Includes support for SRA format. \ No newline at end of file diff --git a/htsjdk3-dev/htsjdk-sra/src/main/java/htsjdk/samtools/sra/package-info.java b/htsjdk3-dev/htsjdk-sra/src/main/java/htsjdk/samtools/sra/package-info.java new file mode 100644 index 0000000000..8c71474d49 --- /dev/null +++ b/htsjdk3-dev/htsjdk-sra/src/main/java/htsjdk/samtools/sra/package-info.java @@ -0,0 +1,6 @@ +/** + * SRA support. + * + * @author Daniel Gomez-Sanchez (magicDGS) + */ +package htsjdk.samtools.sra; \ No newline at end of file diff --git a/src/main/java/htsjdk/Htsjdk3.java b/src/main/java/htsjdk/Htsjdk3.java new file mode 100644 index 0000000000..6924828490 --- /dev/null +++ b/src/main/java/htsjdk/Htsjdk3.java @@ -0,0 +1,31 @@ +package htsjdk; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker interface to indicate the status of the class in the HTSJDK3 development. + * + * @author Daniel Gomez-Sanchez (magicDGS) + */ +@Retention(RetentionPolicy.CLASS) +@Target({ + ElementType.ANNOTATION_TYPE, + ElementType.CONSTRUCTOR, + ElementType.FIELD, + ElementType.METHOD, + ElementType.TYPE +}) +@Documented +public @interface Htsjdk3 { + + /** Indicates the name of the new package if changed; if not changed, returns the empty String. */ + public String newPackage(); + + /** Returns {@code true} if the port is backwards compatible; {@code false} otherwise. */ + public boolean backwardsCompatible(); + +} diff --git a/src/main/java/htsjdk/samtools/util/Locatable.java b/src/main/java/htsjdk/samtools/util/Locatable.java index 0d70090d76..ea2496a791 100644 --- a/src/main/java/htsjdk/samtools/util/Locatable.java +++ b/src/main/java/htsjdk/samtools/util/Locatable.java @@ -1,10 +1,13 @@ package htsjdk.samtools.util; +import htsjdk.Htsjdk3; + /** * Any class that has a single logical mapping onto the genome should implement Locatable * positions should be reported as 1-based and closed at both ends * */ +@Htsjdk3(newPackage = "", backwardsCompatible = true) public interface Locatable { /** diff --git a/src/main/java/htsjdk/tribble/Feature.java b/src/main/java/htsjdk/tribble/Feature.java index 9ed852b14c..cef31c01b1 100644 --- a/src/main/java/htsjdk/tribble/Feature.java +++ b/src/main/java/htsjdk/tribble/Feature.java @@ -24,12 +24,14 @@ package htsjdk.tribble; +import htsjdk.Htsjdk3; import htsjdk.samtools.util.Locatable; /** * Marker interface for Locatables with Tribble support. A Feature represents a record in a tribble-supported file format. * As {@link Locatable}, represents a locus on a reference sequence and is expected to return 1-based closed-ended intervals. */ +@Htsjdk3(newPackage = "", backwardsCompatible = false) public interface Feature extends Locatable { /**