This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-compress.git
The following commit(s) were added to refs/heads/master by this push:
new 81c13fcba Javadoc
81c13fcba is described below
commit 81c13fcba891405b438d9f2d2517c358414c7288
Author: Gary D. Gregory <[email protected]>
AuthorDate: Sat Jan 25 08:17:44 2025 -0500
Javadoc
---
.../compress/harmony/unpack200/BandSet.java | 269 ++++++++++++++++++++-
1 file changed, 258 insertions(+), 11 deletions(-)
diff --git
a/src/main/java/org/apache/commons/compress/harmony/unpack200/BandSet.java
b/src/main/java/org/apache/commons/compress/harmony/unpack200/BandSet.java
index 4b791bae4..9fe61db42 100644
--- a/src/main/java/org/apache/commons/compress/harmony/unpack200/BandSet.java
+++ b/src/main/java/org/apache/commons/compress/harmony/unpack200/BandSet.java
@@ -45,10 +45,21 @@
*/
public abstract class BandSet {
+ /**
+ * Segment.
+ */
protected Segment segment;
+ /**
+ * Segment header.
+ */
protected SegmentHeader header;
+ /**
+ * Constructs a new instance for the given segment.
+ *
+ * @param segment The segment.
+ */
public BandSet(final Segment segment) {
this.segment = segment;
this.header = segment.getSegmentHeader();
@@ -57,13 +68,13 @@ public BandSet(final Segment segment) {
/**
* Decodes a band and return an array of {@code int} values.
*
- * @param name the name of the band (primarily for logging/debugging
purposes)
- * @param in the InputStream to decode from
- * @param codec the default Codec for this band
- * @param count the number of elements to read
- * @return an array of decoded {@code int} values
- * @throws IOException if there is a problem reading from the
underlying input stream
- * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid
+ * @param name the name of the band (for logging and debugging).
+ * @param in the InputStream to decode.
+ * @param codec the default Codec for this band.
+ * @param count the number of elements to read.
+ * @return an array of decoded {@code int} values.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
*/
public int[] decodeBandInt(final String name, final InputStream in, final
BHSDCodec codec, final int count) throws IOException, Pack200Exception {
if (count < 0) {
@@ -155,12 +166,26 @@ public int[][] decodeBandInt(final String name, final
InputStream in, final BHSD
return result;
}
+ /**
+ * Gets a new array of String references for the subset defined by the
given {@code ints} array.
+ *
+ * @param ints The indices into the {@code reference} array.
+ * @param reference The source array.
+ * @return a new array.
+ */
protected String[] getReferences(final int[] ints, final String[]
reference) {
final String[] result = new String[ints.length];
Arrays.setAll(result, i -> reference[ints[i]]);
return result;
}
+ /**
+ * Gets a new array of String references for the subset defined by the
given {@code ints} array.
+ *
+ * @param ints The indices into the {@code reference} array.
+ * @param reference The source array.
+ * @return a new array.
+ */
protected String[][] getReferences(final int[][] ints, final String[]
reference) {
final String[][] result = new String[ints.length][];
for (int i = 0; i < result.length; i++) {
@@ -172,6 +197,17 @@ protected String[][] getReferences(final int[][] ints,
final String[] reference)
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPClass}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPClass}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPClass[] parseCPClassReferences(final String name, final
InputStream in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final int[] indices = decodeBandInt(name, in, codec, count);
@@ -182,6 +218,17 @@ public CPClass[] parseCPClassReferences(final String name,
final InputStream in,
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPNameAndType}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPNameAndType}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPNameAndType[] parseCPDescriptorReferences(final String name,
final InputStream in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final CpBands cpBands = segment.getCpBands();
@@ -194,6 +241,17 @@ public CPNameAndType[] parseCPDescriptorReferences(final
String name, final Inpu
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPDouble}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPDouble}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPDouble[] parseCPDoubleReferences(final String name, final
InputStream in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final int[] indices = decodeBandInt(name, in, codec, count);
@@ -204,6 +262,17 @@ public CPDouble[] parseCPDoubleReferences(final String
name, final InputStream i
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPFieldRef}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPFieldRef}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPFieldRef[] parseCPFieldRefReferences(final String name, final
InputStream in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final CpBands cpBands = segment.getCpBands();
@@ -216,6 +285,17 @@ public CPFieldRef[] parseCPFieldRefReferences(final String
name, final InputStre
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPFloat}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPFloat}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPFloat[] parseCPFloatReferences(final String name, final
InputStream in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final int[] indices = decodeBandInt(name, in, codec, count);
@@ -226,6 +306,17 @@ public CPFloat[] parseCPFloatReferences(final String name,
final InputStream in,
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPInterfaceMethodRef}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPInterfaceMethodRef}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPInterfaceMethodRef[] parseCPInterfaceMethodRefReferences(final
String name, final InputStream in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final CpBands cpBands = segment.getCpBands();
@@ -237,6 +328,17 @@ public CPInterfaceMethodRef[]
parseCPInterfaceMethodRefReferences(final String n
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPInteger}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPInteger}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPInteger[] parseCPIntReferences(final String name, final
InputStream in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final int[] reference = segment.getCpBands().getCpInt();
@@ -252,6 +354,17 @@ public CPInteger[] parseCPIntReferences(final String name,
final InputStream in,
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPLong}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPLong}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPLong[] parseCPLongReferences(final String name, final InputStream
in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final long[] reference = segment.getCpBands().getCpLong();
@@ -267,6 +380,17 @@ public CPLong[] parseCPLongReferences(final String name,
final InputStream in, f
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPMethodRef}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPMethodRef}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPMethodRef[] parseCPMethodRefReferences(final String name, final
InputStream in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final CpBands cpBands = segment.getCpBands();
@@ -278,6 +402,17 @@ public CPMethodRef[] parseCPMethodRefReferences(final
String name, final InputSt
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPUTF8}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPUTF8}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPUTF8[] parseCPSignatureReferences(final String name, final
InputStream in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final int[] indices = decodeBandInt(name, in, codec, count);
@@ -288,6 +423,17 @@ public CPUTF8[] parseCPSignatureReferences(final String
name, final InputStream
return result;
}
+ /**
+ * Parses an input stream into an array of array of {@link CPUTF8}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param counts the number of elements to read.
+ * @return an array of array of decoded {@link CPUTF8}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
protected CPUTF8[][] parseCPSignatureReferences(final String name, final
InputStream in, final BHSDCodec codec, final int[] counts)
throws IOException, Pack200Exception {
int sum = 0;
@@ -310,6 +456,17 @@ protected CPUTF8[][] parseCPSignatureReferences(final
String name, final InputSt
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPString}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPString}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPString[] parseCPStringReferences(final String name, final
InputStream in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final int[] indices = decodeBandInt(name, in, codec, count);
@@ -320,6 +477,17 @@ public CPString[] parseCPStringReferences(final String
name, final InputStream i
return result;
}
+ /**
+ * Parses an input stream into an array of {@link CPUTF8}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param count the number of elements to read.
+ * @return an array of decoded {@link CPUTF8}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPUTF8[] parseCPUTF8References(final String name, final InputStream
in, final BHSDCodec codec, final int count)
throws IOException, Pack200Exception {
final int[] indices = decodeBandInt(name, in, codec, count);
@@ -331,6 +499,17 @@ public CPUTF8[] parseCPUTF8References(final String name,
final InputStream in, f
return result;
}
+ /**
+ * Parses an input stream into an array of array of {@link CPUTF8}.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the input stream to parse.
+ * @param codec the default {@link BHSDCodec} for this band
+ * @param counts the number of elements to read.
+ * @return an array of array of decoded {@link CPUTF8}.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public CPUTF8[][] parseCPUTF8References(final String name, final
InputStream in, final BHSDCodec codec, final int[] counts)
throws IOException, Pack200Exception {
final CPUTF8[][] result = new CPUTF8[counts.length][];
@@ -355,16 +534,52 @@ public CPUTF8[][] parseCPUTF8References(final String
name, final InputStream in,
return result;
}
+ /**
+ * Parses an input stream into an array of flags.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the InputStream to decode.
+ * @param count the number of elements to read.
+ * @param hiCodec an optional codec if the high flag is on.
+ * @param loCodec the codec.
+ * @return an array of decoded {@code long} flags.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public long[] parseFlags(final String name, final InputStream in, final
int count, final BHSDCodec hiCodec, final BHSDCodec loCodec)
throws IOException, Pack200Exception {
return parseFlags(name, in, new int[] { count }, hiCodec, loCodec)[0];
}
+ /**
+ * Parses an input stream into an array of flags.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the InputStream to decode.
+ * @param count the number of elements to read.
+ * @param codec the codec.
+ * @param hasHi whether to the high flag is enabled.
+ * @return an array of decoded {@code long} flags.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public long[] parseFlags(final String name, final InputStream in, final
int count, final BHSDCodec codec, final boolean hasHi)
throws IOException, Pack200Exception {
return parseFlags(name, in, new int[] { count }, hasHi ? codec : null,
codec)[0];
}
+ /**
+ * Parses an input stream into an array of flags.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the InputStream to decode.
+ * @param counts the number of elements to read.
+ * @param hiCodec an optional codec if the high flag is on.
+ * @param loCodec the codec.
+ * @return an array of decoded {@code long} flags.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public long[][] parseFlags(final String name, final InputStream in, final
int[] counts, final BHSDCodec hiCodec, final BHSDCodec loCodec)
throws IOException, Pack200Exception {
final int count = counts.length;
@@ -398,6 +613,18 @@ public long[][] parseFlags(final String name, final
InputStream in, final int[]
return result;
}
+ /**
+ * Parses an input stream into an array of flags.
+ *
+ * @param name the name of the band (for logging and debugging).
+ * @param in the InputStream to decode.
+ * @param counts the number of elements to read.
+ * @param codec the codec.
+ * @param hasHi whether the high flag is enabnled.
+ * @return an array of decoded {@code long} flags.
+ * @throws IOException if there is a problem reading from the
underlying input stream.
+ * @throws Pack200Exception if there is a problem decoding the value or
that the value is invalid.
+ */
public long[][] parseFlags(final String name, final InputStream in, final
int[] counts, final BHSDCodec codec, final boolean hasHi)
throws IOException, Pack200Exception {
return parseFlags(name, in, counts, hasHi ? codec : null, codec);
@@ -413,8 +640,8 @@ public long[][] parseFlags(final String name, final
InputStream in, final int[]
* @param count the number of references to decode
* @param reference the array of values to use for the references
* @return Parsed references.
- * @throws IOException if a problem occurs during reading from the
underlying stream
- * @throws Pack200Exception if a problem occurs with an unexpected value
or unsupported Codec
+ * @throws IOException if a problem occurs during reading from the
underlying stream.
+ * @throws Pack200Exception if a problem occurs with an unexpected value
or unsupported Codec.
*/
public String[] parseReferences(final String name, final InputStream in,
final BHSDCodec codec, final int count, final String[] reference)
throws IOException, Pack200Exception {
@@ -432,8 +659,8 @@ public String[] parseReferences(final String name, final
InputStream in, final B
* @param counts the numbers of references to decode for each array
entry
* @param reference the array of values to use for the references
* @return Parsed references.
- * @throws IOException if a problem occurs during reading from the
underlying stream
- * @throws Pack200Exception if a problem occurs with an unexpected value
or unsupported Codec
+ * @throws IOException if a problem occurs during reading from the
underlying stream.
+ * @throws Pack200Exception if a problem occurs with an unexpected value
or unsupported Codec.
*/
public String[][] parseReferences(final String name, final InputStream in,
final BHSDCodec codec, final int[] counts, final String[] reference)
throws IOException, Pack200Exception {
@@ -467,10 +694,30 @@ public String[][] parseReferences(final String name,
final InputStream in, final
return result;
}
+ /**
+ * Reads the input stream.
+ *
+ * @param inputStream the stream to read.
+ * @throws IOException if a problem occurs during reading from the
underlying stream.
+ * @throws Pack200Exception if a problem occurs with an unexpected value
or unsupported Codec.
+ */
public abstract void read(InputStream inputStream) throws IOException,
Pack200Exception;
+ /**
+ * Unpacks this instance.
+ *
+ * @throws IOException if a problem occurs during reading from the
underlying stream.
+ * @throws Pack200Exception if a problem occurs with an unexpected value
or unsupported Codec.
+ */
public abstract void unpack() throws IOException, Pack200Exception;
+ /**
+ * Unpacks the input stream.
+ *
+ * @param in the stream to unpack.
+ * @throws IOException if a problem occurs during reading from the
underlying stream.
+ * @throws Pack200Exception if a problem occurs with an unexpected value
or unsupported Codec.
+ */
public void unpack(final InputStream in) throws IOException,
Pack200Exception {
read(in);
unpack();
