dx/src/com/android/dx/dex/file/Section.java - platform/dalvik - Git at Google

 /*
  * Copyright (C) 2007 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package com.android.dx.dex.file;

 import com.android.dx.util.AnnotatedOutput;
 import java.util.Collection;

 /**
  * A section of a {@code .dex} file. Each section consists of a list
  * of items of some sort or other.
  */
 public abstract class Section {
     /** {@code null-ok;} name of this part, for annotation purposes */
     private final String name;

     /** {@code non-null;} file that this instance is part of */
     private final DexFile file;

     /** {@code > 0;} alignment requirement for the final output;
      * must be a power of 2 */
     private final int alignment;

     /** {@code >= -1;} offset from the start of the file to this part, or
      * {@code -1} if not yet known */
     private int fileOffset;

     /** whether {@link #prepare} has been called successfully on this
      * instance */
     private boolean prepared;

     /**
      * Validates an alignment.
      *
      * @param alignment the alignment
      * @throws IllegalArgumentException thrown if {@code alignment}
      * isn't a positive power of 2
      */
     public static void validateAlignment(int alignment) {
         if ((alignment <= 0) ||
             (alignment & (alignment - 1)) != 0) {
             throw new IllegalArgumentException("invalid alignment");
         }
     }

     /**
      * Constructs an instance. The file offset is initially unknown.
      *
      * @param name {@code null-ok;} the name of this instance, for annotation
      * purposes
      * @param file {@code non-null;} file that this instance is part of
      * @param alignment {@code > 0;} alignment requirement for the final output;
      * must be a power of 2
      */
     public Section(String name, DexFile file, int alignment) {
         if (file == null) {
             throw new NullPointerException("file == null");
         }

         validateAlignment(alignment);

         this.name = name;
         this.file = file;
         this.alignment = alignment;
         this.fileOffset = -1;
         this.prepared = false;
     }

     /**
      * Gets the file that this instance is part of.
      *
      * @return {@code non-null;} the file
      */
     public final DexFile getFile() {
         return file;
     }

     /**
      * Gets the alignment for this instance's final output.
      *
      * @return {@code > 0;} the alignment
      */
     public final int getAlignment() {
         return alignment;
     }

     /**
      * Gets the offset from the start of the file to this part. This
      * throws an exception if the offset has not yet been set.
      *
      * @return {@code >= 0;} the file offset
      */
     public final int getFileOffset() {
         if (fileOffset < 0) {
             throw new RuntimeException("fileOffset not set");
         }

         return fileOffset;
     }

     /**
      * Sets the file offset. It is only valid to call this method once
      * once per instance.
      *
      * @param fileOffset {@code >= 0;} the desired offset from the start of the
      * file where this for this instance
      * @return {@code >= 0;} the offset that this instance should be placed at
      * in order to meet its alignment constraint
      */
     public final int setFileOffset(int fileOffset) {
         if (fileOffset < 0) {
             throw new IllegalArgumentException("fileOffset < 0");
         }

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

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

         this.fileOffset = fileOffset;

         return fileOffset;
     }

     /**
      * Writes this instance to the given raw data object.
      *
      * @param out {@code non-null;} where to write to
      */
     public final void writeTo(AnnotatedOutput out) {
         throwIfNotPrepared();
         align(out);

         int cursor = out.getCursor();

         if (fileOffset < 0) {
             fileOffset = cursor;
         } else if (fileOffset != cursor) {
             throw new RuntimeException("alignment mismatch: for " + this +
                                        ", at " + cursor +
                                        ", but expected " + fileOffset);
         }

         if (out.annotates()) {
             if (name != null) {
                 out.annotate(0, "\n" + name + ":");
             } else if (cursor != 0) {
                 out.annotate(0, "\n");
             }
         }

         writeTo0(out);
     }

     /**
      * Returns the absolute file offset, given an offset from the
      * start of this instance's output. This is only valid to call
      * once this instance has been assigned a file offset (via {@link
      * #setFileOffset}).
      *
      * @param relative {@code >= 0;} the relative offset
      * @return {@code >= 0;} the corresponding absolute file offset
      */
     public final int getAbsoluteOffset(int relative) {
         if (relative < 0) {
             throw new IllegalArgumentException("relative < 0");
         }

         if (fileOffset < 0) {
             throw new RuntimeException("fileOffset not yet set");
         }

         return fileOffset + relative;
     }

     /**
      * Returns the absolute file offset of the given item which must
      * be contained in this section. This is only valid to call
      * once this instance has been assigned a file offset (via {@link
      * #setFileOffset}).
      *
      * <p><b>Note:</b> Subclasses must implement this as appropriate for
      * their contents.</p>
      *
      * @param item {@code non-null;} the item in question
      * @return {@code >= 0;} the item's absolute file offset
      */
     public abstract int getAbsoluteItemOffset(Item item);

     /**
      * Prepares this instance for writing. This performs any necessary
      * prerequisites, including particularly adding stuff to other
      * sections. This method may only be called once per instance;
      * subsequent calls will throw an exception.
      */
     public final void prepare() {
         throwIfPrepared();
         prepare0();
         prepared = true;
     }

     /**
      * Gets the collection of all the items in this section.
      * It is not valid to attempt to change the returned list.
      *
      * @return {@code non-null;} the items
      */
     public abstract Collection<? extends Item> items();

     /**
      * Does the main work of {@link #prepare}.
      */
     protected abstract void prepare0();

     /**
      * Gets the size of this instance when output, in bytes.
      *
      * @return {@code >= 0;} the size of this instance, in bytes
      */
     public abstract int writeSize();

     /**
      * Throws an exception if {@link #prepare} has not been
      * called on this instance.
      */
     protected final void throwIfNotPrepared() {
         if (!prepared) {
             throw new RuntimeException("not prepared");
         }
     }

     /**
      * Throws an exception if {@link #prepare} has already been called
      * on this instance.
      */
     protected final void throwIfPrepared() {
         if (prepared) {
             throw new RuntimeException("already prepared");
         }
     }

     /**
      * Aligns the output of the given data to the alignment of this instance.
      *
      * @param out {@code non-null;} the output to align
      */
     protected final void align(AnnotatedOutput out) {
         out.alignTo(alignment);
     }

     /**
      * Writes this instance to the given raw data object. This gets
      * called by {@link #writeTo} after aligning the cursor of
      * {@code out} and verifying that either the assigned file
      * offset matches the actual cursor {@code out} or that the
      * file offset was not previously assigned, in which case it gets
      * assigned to {@code out}'s cursor.
      *
      * @param out {@code non-null;} where to write to
      */
     protected abstract void writeTo0(AnnotatedOutput out);

     /**
      * Returns the name of this section, for annotation purposes.
      *
      * @return {@code null-ok;} name of this part, for annotation purposes
      */
     protected final String getName() {
         return name;
     }
 }
	/*
	* Copyright (C) 2007 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package com.android.dx.dex.file;

	import com.android.dx.util.AnnotatedOutput;
	import java.util.Collection;

	/**
	* A section of a {@code .dex} file. Each section consists of a list
	* of items of some sort or other.
	*/
	public abstract class Section {
	/** {@code null-ok;} name of this part, for annotation purposes */
	private final String name;

	/** {@code non-null;} file that this instance is part of */
	private final DexFile file;

	/** {@code > 0;} alignment requirement for the final output;
	* must be a power of 2 */
	private final int alignment;

	/** {@code >= -1;} offset from the start of the file to this part, or
	* {@code -1} if not yet known */
	private int fileOffset;

	/** whether {@link #prepare} has been called successfully on this
	* instance */
	private boolean prepared;

	/**
	* Validates an alignment.
	*
	* @param alignment the alignment
	* @throws IllegalArgumentException thrown if {@code alignment}
	* isn't a positive power of 2
	*/
	public static void validateAlignment(int alignment) {
	if ((alignment <= 0) \|\|
	(alignment & (alignment - 1)) != 0) {
	throw new IllegalArgumentException("invalid alignment");
	}
	}

	/**
	* Constructs an instance. The file offset is initially unknown.
	*
	* @param name {@code null-ok;} the name of this instance, for annotation
	* purposes
	* @param file {@code non-null;} file that this instance is part of
	* @param alignment {@code > 0;} alignment requirement for the final output;
	* must be a power of 2
	*/
	public Section(String name, DexFile file, int alignment) {
	if (file == null) {
	throw new NullPointerException("file == null");
	}

	validateAlignment(alignment);

	this.name = name;
	this.file = file;
	this.alignment = alignment;
	this.fileOffset = -1;
	this.prepared = false;
	}

	/**
	* Gets the file that this instance is part of.
	*
	* @return {@code non-null;} the file
	*/
	public final DexFile getFile() {
	return file;
	}

	/**
	* Gets the alignment for this instance's final output.
	*
	* @return {@code > 0;} the alignment
	*/
	public final int getAlignment() {
	return alignment;
	}

	/**
	* Gets the offset from the start of the file to this part. This
	* throws an exception if the offset has not yet been set.
	*
	* @return {@code >= 0;} the file offset
	*/
	public final int getFileOffset() {
	if (fileOffset < 0) {
	throw new RuntimeException("fileOffset not set");
	}

	return fileOffset;
	}

	/**
	* Sets the file offset. It is only valid to call this method once
	* once per instance.
	*
	* @param fileOffset {@code >= 0;} the desired offset from the start of the
	* file where this for this instance
	* @return {@code >= 0;} the offset that this instance should be placed at
	* in order to meet its alignment constraint
	*/
	public final int setFileOffset(int fileOffset) {
	if (fileOffset < 0) {
	throw new IllegalArgumentException("fileOffset < 0");
	}

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

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

	this.fileOffset = fileOffset;

	return fileOffset;
	}

	/**
	* Writes this instance to the given raw data object.
	*
	* @param out {@code non-null;} where to write to
	*/
	public final void writeTo(AnnotatedOutput out) {
	throwIfNotPrepared();
	align(out);

	int cursor = out.getCursor();

	if (fileOffset < 0) {
	fileOffset = cursor;
	} else if (fileOffset != cursor) {
	throw new RuntimeException("alignment mismatch: for " + this +
	", at " + cursor +
	", but expected " + fileOffset);
	}

	if (out.annotates()) {
	if (name != null) {
	out.annotate(0, "\n" + name + ":");
	} else if (cursor != 0) {
	out.annotate(0, "\n");
	}
	}

	writeTo0(out);
	}

	/**
	* Returns the absolute file offset, given an offset from the
	* start of this instance's output. This is only valid to call
	* once this instance has been assigned a file offset (via {@link
	* #setFileOffset}).
	*
	* @param relative {@code >= 0;} the relative offset
	* @return {@code >= 0;} the corresponding absolute file offset
	*/
	public final int getAbsoluteOffset(int relative) {
	if (relative < 0) {
	throw new IllegalArgumentException("relative < 0");
	}

	if (fileOffset < 0) {
	throw new RuntimeException("fileOffset not yet set");
	}

	return fileOffset + relative;
	}

	/**
	* Returns the absolute file offset of the given item which must
	* be contained in this section. This is only valid to call
	* once this instance has been assigned a file offset (via {@link
	* #setFileOffset}).
	*
	* <p><b>Note:</b> Subclasses must implement this as appropriate for
	* their contents.</p>
	*
	* @param item {@code non-null;} the item in question
	* @return {@code >= 0;} the item's absolute file offset
	*/
	public abstract int getAbsoluteItemOffset(Item item);

	/**
	* Prepares this instance for writing. This performs any necessary
	* prerequisites, including particularly adding stuff to other
	* sections. This method may only be called once per instance;
	* subsequent calls will throw an exception.
	*/
	public final void prepare() {
	throwIfPrepared();
	prepare0();
	prepared = true;
	}

	/**
	* Gets the collection of all the items in this section.
	* It is not valid to attempt to change the returned list.
	*
	* @return {@code non-null;} the items
	*/
	public abstract Collection<? extends Item> items();

	/**
	* Does the main work of {@link #prepare}.
	*/
	protected abstract void prepare0();

	/**
	* Gets the size of this instance when output, in bytes.
	*
	* @return {@code >= 0;} the size of this instance, in bytes
	*/
	public abstract int writeSize();

	/**
	* Throws an exception if {@link #prepare} has not been
	* called on this instance.
	*/
	protected final void throwIfNotPrepared() {
	if (!prepared) {
	throw new RuntimeException("not prepared");
	}
	}

	/**
	* Throws an exception if {@link #prepare} has already been called
	* on this instance.
	*/
	protected final void throwIfPrepared() {
	if (prepared) {
	throw new RuntimeException("already prepared");
	}
	}

	/**
	* Aligns the output of the given data to the alignment of this instance.
	*
	* @param out {@code non-null;} the output to align
	*/
	protected final void align(AnnotatedOutput out) {
	out.alignTo(alignment);
	}

	/**
	* Writes this instance to the given raw data object. This gets
	* called by {@link #writeTo} after aligning the cursor of
	* {@code out} and verifying that either the assigned file
	* offset matches the actual cursor {@code out} or that the
	* file offset was not previously assigned, in which case it gets
	* assigned to {@code out}'s cursor.
	*
	* @param out {@code non-null;} where to write to
	*/
	protected abstract void writeTo0(AnnotatedOutput out);

	/**
	* Returns the name of this section, for annotation purposes.
	*
	* @return {@code null-ok;} name of this part, for annotation purposes
	*/
	protected final String getName() {
	return name;
	}
	}