FileDocCategorySizeDatePackage
OffsettedItem.javaAPI DocAndroid 1.5 API9643Wed May 06 22:41:02 BST 2009com.android.dx.dex.file

OffsettedItem

public abstract class OffsettedItem extends Item implements Comparable
An item in a Dalvik file which is referenced by absolute offset.

Fields Summary
private final int
alignment
> 0; alignment requirement
private int
writeSize
>= -1; the size of this instance when written, in bytes, or -1 if not yet known
private Section
addedTo
null-ok; section the item was added to, or null if not yet added
private int
offset
>= -1; assigned offset of the item from the start of its section, or -1 if not yet assigned
Constructors Summary
public OffsettedItem(int alignment, int writeSize)
Constructs an instance. The offset is initially unassigned.

param
alignment > 0; output alignment requirement; must be a power of 2
param
writeSize >= -1; the size of this instance when written, in bytes, or -1 if not immediately known

        Section.validateAlignment(alignment);

        if (writeSize < -1) {
            throw new IllegalArgumentException("writeSize < -1");
        }

        this.alignment = alignment;
        this.writeSize = writeSize;
        this.addedTo = null;
        this.offset = -1;
Methods Summary
public final intcompareTo(com.android.dx.dex.file.OffsettedItem other)
{@inheritDoc} Comparisons for this class are defined to be class-major (if the classes don't match then the objects are not equal), with {@link #compareTo0} deciding same-class comparisons.

        if (this == other) {
            return 0;
        }

        ItemType thisType = itemType();
        ItemType otherType = other.itemType();

        if (thisType != otherType) {
            return thisType.compareTo(otherType);
        }

        return compareTo0(other);
protected intcompareTo0(com.android.dx.dex.file.OffsettedItem other)
Compares this instance to another which is guaranteed to be of the same class. The default implementation of this method is to throw an exception (unsupported operation). If a particular class needs to actually sort, then it should override this method.

param
other non-null; instance to compare to
return
-1, 0, or 1, depending on the sort order of this instance and the other

        throw new UnsupportedOperationException("unsupported");
public final booleanequals(java.lang.Object other)
{@inheritDoc} Comparisons for this class are defined to be type-major (if the types don't match then the objects are not equal), with {@link #compareTo0} deciding same-type comparisons.

        if (this == other) {
            return true;
        }

        OffsettedItem otherItem = (OffsettedItem) other;
        ItemType thisType = itemType();
        ItemType otherType = otherItem.itemType();

        if (thisType != otherType) {
            return false;
        }

        return (compareTo0(otherItem) == 0);
public final intgetAbsoluteOffset()
Gets the absolute item offset. The offset is from the start of the file which the instance was written to.

return
>= 0; the offset
throws
RuntimeException thrown if the offset is not yet known

        if (offset < 0) {
            throw new RuntimeException("offset not yet known");
        }

        return addedTo.getAbsoluteOffset(offset);
public static intgetAbsoluteOffsetOr0(com.android.dx.dex.file.OffsettedItem item)
Gets the absolute offset of the given item, returning 0 if handed null.

param
item null-ok; the item in question
return
>= 0; the item's absolute offset, or 0 if item == null

        if (item == null) {
            return 0;
        }

        return item.getAbsoluteOffset();
public final intgetAlignment()
Gets the alignment requirement of this instance. An instance should only be written when so aligned.

return
> 0; the alignment requirement; must be a power of 2

        return alignment;
public final intgetRelativeOffset()
Gets the relative item offset. The offset is from the start of the section which the instance was written to.

return
>= 0; the offset
throws
RuntimeException thrown if the offset is not yet known

        if (offset < 0) {
            throw new RuntimeException("offset not yet known");
        }

        return offset;
public final java.lang.StringoffsetString()
Gets the absolute offset of this item as a string, suitable for including in annotations.

return
non-null; the offset string

        return '[" + Integer.toHexString(getAbsoluteOffset()) + ']";
public final intplace(Section addedTo, int offset)
Indicates that this item has been added to the given section at the given offset. It is only valid to call this method once per instance.

param
addedTo non-null; the section this instance has been added to
param
offset >= 0; the desired offset from the start of the section where this instance was placed
return
>= 0; the offset that this instance should be placed at in order to meet its alignment constraint

        if (addedTo == null) {
            throw new NullPointerException("addedTo == null");
        }

        if (offset < 0) {
            throw new IllegalArgumentException("offset < 0");
        }

        if (this.addedTo != null) {
            throw new RuntimeException("already written");
        }

        int mask = alignment - 1;
        offset = (offset + mask) & ~mask;

        this.addedTo = addedTo;
        this.offset = offset;

        place0(addedTo, offset);

        return offset;
protected voidplace0(Section addedTo, int offset)
Does additional work required when placing an instance. The default implementation of this method is a no-op. If a particular class needs to do something special, then it should override this method. In particular, if this instance did not know its write size up-front, then this method is responsible for setting it.

param
addedTo non-null; the section this instance has been added to
param
offset >= 0; the offset from the start of the section where this instance was placed

        // This space intentionally left blank.
public final voidsetWriteSize(int writeSize)
Sets the write size of this item. This may only be called once per instance, and only if the size was unknown upon instance creation.

param
writeSize > 0; the write size, in bytes

        if (writeSize < 0) {
            throw new IllegalArgumentException("writeSize < 0");
        }

        if (this.writeSize >= 0) {
            throw new UnsupportedOperationException("writeSize already set");
        }

        this.writeSize = writeSize;
public abstract java.lang.StringtoHuman()
Gets a short human-readable string representing this instance.

return
non-null; the human form

public final intwriteSize()
{@inheritDoc}
throws
UnsupportedOperationException thrown if the write size
is not yet known
        if (writeSize < 0) {
            throw new UnsupportedOperationException("writeSize is unknown");
        }
                
        return writeSize;
    
public final voidwriteTo(DexFile file, com.android.dx.util.AnnotatedOutput out)
{@inheritDoc}
        out.alignTo(alignment);

        try {
            if (writeSize < 0) {
                throw new UnsupportedOperationException(
                        "writeSize is unknown");
            }
            out.assertCursor(getAbsoluteOffset());
        } catch (RuntimeException ex) {
            throw ExceptionWithContext.withContext(ex,
                    "...while writing " + this);
        }

        writeTo0(file, out);
    
protected abstract voidwriteTo0(DexFile file, com.android.dx.util.AnnotatedOutput out)
Performs the actual write of the contents of this instance to
the given data section. This is called by {@link #writeTo},
which will have taken care of ensuring alignment.
param
file non-null; the file to use for reference
param
out non-null; where to write to