com.android.apksig.util

Interface DataSource

All Known Subinterfaces:

ReadableDataSink

public interface DataSource

Abstract representation of a source of data.

This abstraction serves three purposes:

• Transparent handling of different types of sources, such as byte[], ByteBuffer, RandomAccessFile, memory-mapped file.
• Support sources larger than 2 GB. If all sources were smaller than 2 GB, ByteBuffer may have worked as the unifying abstraction.
• Support sources which do not fit into logical memory as a contiguous region.

There are following ways to obtain a chunk of data from the data source:

• Stream the chunk's data into a DataSink using feed. This is best suited for scenarios where there is no need to have the chunk's data accessible at the same time, for example, when computing the digest of the chunk. If you need to keep the chunk's data around after feed completes, you must create a copy during feed. However, in that case the following methods of obtaining the chunk's data may be more appropriate.
• Obtain a ByteBuffer containing the chunk's data using getByteBuffer. Depending on the data source, the chunk's data may or may not be copied by this operation. This is best suited for scenarios where you need to access the chunk's data in arbitrary order, but don't need to modify the data and thus don't require a copy of the data.
• Copy the chunk's data to a ByteBuffer using copyTo. This is best suited for scenarios where you require a copy of the chunk's data, such as to when you need to modify the data.

Method Summary

Modifier and Type	Method and Description
void	copyTo(long offset, int size, java.nio.ByteBuffer dest) Copies the specified chunk from this data source into the provided destination buffer, advancing the destination buffer's position by size.
void	feed(long offset, long size, DataSink sink) Feeds the specified chunk from this data source into the provided sink.
java.nio.ByteBuffer	getByteBuffer(long offset, int size) Returns a buffer holding the contents of the specified chunk of data from this data source.
long	size() Returns the amount of data (in bytes) contained in this data source.
DataSource	slice(long offset, long size) Returns a data source representing the specified region of data of this data source.

Method Detail

size

long size()

Returns the amount of data (in bytes) contained in this data source.

feed

void feed(long offset,
          long size,
          DataSink sink)
   throws java.io.IOException

Feeds the specified chunk from this data source into the provided sink.

Parameters:

offset - index (in bytes) at which the chunk starts inside data source

size - size (in bytes) of the chunk

Throws:

java.lang.IndexOutOfBoundsException - if offset or size is negative, or if offset + size is greater than size().

java.io.IOException

getByteBuffer

java.nio.ByteBuffer getByteBuffer(long offset,
                                  int size)
                           throws java.io.IOException

Returns a buffer holding the contents of the specified chunk of data from this data source. Changes to the data source are not guaranteed to be reflected in the returned buffer. Similarly, changes in the buffer are not guaranteed to be reflected in the data source.

The returned buffer's position is 0, and the buffer's limit and capacity is size.

Parameters:

offset - index (in bytes) at which the chunk starts inside data source

size - size (in bytes) of the chunk

Throws:

java.lang.IndexOutOfBoundsException - if offset or size is negative, or if offset + size is greater than size().

java.io.IOException

copyTo

void copyTo(long offset,
            int size,
            java.nio.ByteBuffer dest)
     throws java.io.IOException

Copies the specified chunk from this data source into the provided destination buffer, advancing the destination buffer's position by size.

Parameters:

offset - index (in bytes) at which the chunk starts inside data source

size - size (in bytes) of the chunk

Throws:

java.lang.IndexOutOfBoundsException - if offset or size is negative, or if offset + size is greater than size().

java.io.IOException

slice

DataSource slice(long offset,
                 long size)

Returns a data source representing the specified region of data of this data source. Changes to data represented by this data source will also be visible in the returned data source.

Parameters:

offset - index (in bytes) at which the region starts inside data source

size - size (in bytes) of the region

Throws:

java.lang.IndexOutOfBoundsException - if offset or size is negative, or if offset + size is greater than size().